From 0c915c8fcfe6f61fd5adf3e8f73d03340038fe5d Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 2 Apr 2002 03:27:03 +0000 Subject: PEP 287: reStructuredText Standard Docstring Format As posted to the Doc-SIG 2002-03-26. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@7 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 677 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 677 insertions(+) create mode 100644 docs/peps/pep-0287.txt (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt new file mode 100644 index 000000000..f19354587 --- /dev/null +++ b/docs/peps/pep-0287.txt @@ -0,0 +1,677 @@ +PEP: +Title: reStructuredText Standard Docstring Format +Version: $Revision$ +Last-Modified: $Date$ +Author: goodger@users.sourceforge.net (David Goodger) +Discussions-To: doc-sig@python.org +Status: Draft +Type: Informational +Created: 2002-03-25 +Post-History: + + +Abstract + + This PEP proposes that the reStructuredText [1]_ markup be adopted + as the standard markup format for plaintext documentation in + Python docstrings, and (optionally) for PEPs and ancillary + documents as well. reStructuredText is a rich and extensible yet + easy-to-read, what-you-see-is-what-you-get plaintext markup + syntax. + + Only the low-level syntax of docstrings is addressed here. This + PEP is not concerned with docstring semantics or processing at + all. + + +Goals + + These are the generally accepted goals for a docstring format, as + discussed in the Python Documentation Special Interest Group + (Doc-SIG) [2]_: + + 1. It must be easy to type with any standard text editor. + + 2. It must be readable to the casual observer. + + 3. It must not need to contain information which can be deduced + from parsing the module. + + 4. It must contain sufficient information (structure) so it can be + converted to any reasonable markup format. + + 5. It must be possible to write a module's entire documentation in + docstrings, without feeling hampered by the markup language. + + [[Are these in fact the goals of the Doc-SIG members? Anything to + add?]] + + reStructuredText meets and exceeds all of these goals, and sets + its own goals as well, even more stringent. See "Features" below. + + The goals of this PEP are as follows: + + 1. To establish a standard docstring format by attaining + "accepted" status (Python community consensus; BDFL + pronouncement). Once reStructuredText is a Python standard, all + effort can be focused on tools instead of arguing for a + standard. Python needs a standard set of documentation tools. + + 2. To address any related concerns raised by the Python community. + + 3. To encourage community support. As long as multiple competing + markups are out there, the development community remains + fractured. Once a standard exists, people will start to use + it, and momentum will inevitably gather. + + 4. To consolidate efforts from related auto-documentation + projects. It is hoped that interested developers will join + forces and work on a joint/merged/common implementation. + + 5. (Optional.) To adopt reStructuredText as the standard markup + for PEPs. One or both of the following strategies may be + applied: + + a) Keep the existing PEP section structure constructs (one-line + section headers, indented body text). Subsections can either + be forbidden or supported with underlined headers in the + indented body text. + + b) Replace the PEP section structure constructs with the + reStructuredText syntax. Section headers will require + underlines, subsections will be supported out of the box, and + body text need not be indented (except for block quotes). + + Support for RFC822 headers will be added to the + reStructuredText parser (unambiguous given a specific context: + the first contiguous block of a PEP document). It may be + desired to concretely specify what over/underline styles are + allowed for PEP section headers, for uniformity. + + 6. (Optional.) To adopt reStructuredText as the standard markup + for README-type files and other standalone documents in the + Python distribution. + + +Rationale + + The __doc__ attribute is called a documentation string, or + docstring. It is often used to summarize the interface of the + module, class or function. The lack of a standard syntax for + docstrings has hampered the development of standard tools for + extracting docstrings and transforming them into documentation in + standard formats (e.g., HTML, DocBook, TeX). There have been a + number of proposed markup formats and variations, and many tools + tied to these proposals, but without a standard docstring format + they have failed to gain a strong following and/or floundered + half-finished. + + The adoption of a standard will, at the very least, benefit + docstring processing tools by preventing further "reinventing the + wheel". + + Throughout the existence of the Doc-SIG, consensus on a single + standard docstring format has never been reached. A lightweight, + implicit markup has been sought, for the following reasons (among + others): + + 1. Docstrings written within Python code are available from within + the interactive interpreter, and can be 'print'ed. Thus the + use of plaintext for easy readability. + + 2. Programmers want to add structure to their docstrings, without + sacrificing raw docstring readability. Unadorned plaintext + cannot be transformed ('up-translated') into useful structured + formats. + + 3. Explicit markup (like XML or TeX) is widely considered + unreadable by the uninitiated. + + 4. Implicit markup is aesthetically compatible with the clean and + minimalist Python syntax. + + Proposed alternatives have included: + + - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_ + + XML and SGML are explicit, well-formed meta-languages suitable + for all kinds of documentation. XML is a variant of SGML. They + are best used behind the scenes, because they are verbose, + difficult to type, and too cluttered to read comfortably as + source. DocBook, HTML, and XHTML are all applications of SGML + and/or XML, and all share the same basic syntax and the same + shortcomings. + + - TeX [8]_ + + TeX is similar to XML/SGML in that it's explicit, not very easy + to write, and not easy for the uninitiated to read. + + - Perl POD [9]_ + + Most Perl modules are documented in a format called POD -- Plain + Old Documentation. This is an easy-to-type, very low level + format with strong integration with the Perl parser. Many tools + exist to turn POD documentation into other formats: info, HTML + and man pages, among others. However, the POD syntax takes + after Perl itself in terms of readability. + + - JavaDoc [10]_ + + Special comments before Java classes and functions serve to + document the code. A program to extract these, and turn them + into HTML documentation is called javadoc, and is part of the + standard Java distribution. However, the only output format + that is supported is HTML, and JavaDoc has a very intimate + relationship with HTML, using HTML tags for most markup. Thus + it shares the readability problems of HTML. + + - Setext [11]_, StructuredText [12]_ + + Early on, variants of Setext (Structure Enhanced Text), + including Zope Corp's StructuredText, were proposed for Python + docstring formatting. Hereafter these variants will + collectively be call 'STexts'. STexts have the advantage of + being easy to read without special knowledge, and relatively + easy to write. + + Although used by some (including in most existing Python + auto-documentation tools), until now STexts have failed to + become standard because: + + - STexts have been incomplete. Lacking "essential" constructs + that people want to use in their docstrings, STexts are + rendered less than ideal. Note that these "essential" + constructs are not universal; everyone has their own + requirements. + + - STexts have been sometimes surprising. Bits of text are + marked up unexpectedly, leading to user frustration. + + - SText implementations have been buggy. + + - Most STexts have have had no formal specification except for + the implementation itself. A buggy implementation meant a + buggy spec, and vice-versa. + + - There has been no mechanism to get around the SText markup + rules when a markup character is used in a non-markup context. + + Proponents of implicit STexts have vigorously opposed proposals + for explicit markup (XML, HTML, TeX, POD, etc.), and the debates + have continued off and on since 1996 or earlier. + + reStructuredText is a complete revision and reinterpretation of + the SText idea, addressing all of the problems listed above. + + +Features + + Rather than repeating or summarizing the extensive + reStructuredText spec, please read the originals available from + http://structuredtext.sourceforge.net/spec/ (.txt & .html files). + Reading the documents in following order is recommended: + + - An Introduction to reStructuredText [13]_ + + - Problems With StructuredText [14]_ (optional, if you've used + StructuredText; it explains many markup decisions made) + + - reStructuredText Markup Specification [15]_ + + - A Record of reStructuredText Syntax Alternatives [16]_ (explains + markup decisions made independently of StructuredText) + + - reStructuredText Directives [17]_ + + There is also a "Quick reStructuredText" user reference [18]_. + + A summary of features addressing often-raised docstring markup + concerns follows: + + - A markup escaping mechanism. + + Backslashes (``\``) are used to escape markup characters when + needed for non-markup purposes. However, the inline markup + recognition rules have been constructed in order to minimize the + need for backslash-escapes. For example, although asterisks are + used for *emphasis*, in non-markup contexts such as "*" or "(*)" + or "x * y", the asterisks are not interpreted as markup and are + left unchanged. For many non-markup uses of backslashes (e.g., + describing regular expressions), inline literals or literal + blocks are applicable; see the next item. + + - Markup to include Python source code and Python interactive + sessions: inline literals, literal blocks, and doctest blocks. + + Inline literals use ``double-backquotes`` to indicate program + I/O or code snippets. No markup interpretation (including + backslash-escape [``\``] interpretation) is done within inline + literals. + + Literal blocks (block-level literal text, such as code excerpts + or ASCII graphics) are indented, and indicated with a + double-colon ("::") at the end of the preceding paragraph (right + here -->):: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + + Doctest blocks begin with ">>> " and end with a blank line. + Neither indentation nor literal block double-colons are + required. For example:: + + Here's a doctest block: + + >>> print 'Python-specific usage examples; begun with ">>>"' + Python-specific usage examples; begun with ">>>" + >>> print '(cut and pasted from interactive sessions)' + (cut and pasted from interactive sessions) + + - Markup that isolates a Python identifier: interpreted text. + + Text enclosed in single backquotes is recognized as "interpreted + text", whose interpretation is application-dependent. In the + context of a Python docstring, the default interpretation of + interpreted text is as Python identifiers. The text will be + marked up with a hyperlink connected to the documentation for + the identifier given. Lookup rules are the same as in Python + itself: LGB namespace lookups (local, global, builtin). The + "role" of the interpreted text (identifying a class, module, + function, etc.) is determined implicitly from the namespace + lookup. For example:: + + class Keeper(Storer): + + """ + Extend `Storer`. Class attribute `instances` keeps track + of the number of `Keeper` objects instantiated. + """ + + instances = 0 + """How many `Keeper` objects are there?""" + + def __init__(self): + """ + Extend `Storer.__init__()` to keep track of + instances. Keep count in `self.instances` and data + in `self.data`. + """ + Storer.__init__(self) + self.instances += 1 + + self.data = [] + """Store data in a list, most recent last.""" + + def storedata(self, data): + """ + Extend `Storer.storedata()`; append new `data` to a + list (in `self.data`). + """ + self.data = data + + Each piece of interpreted text is looked up according to the + local namespace of the block containing its docstring. + + - Markup that isolates a Python identifier and specifies its type: + interpreted text with roles. + + Although the Python source context reader is designed not to + require explicit roles, they may be used. 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 syntax chosen for roles is verbose, but necessarily so (if + anyone has a better alternative, please post it to the Doc-SIG). + The intention of the markup is that there should be little need + to use explicit roles; their use is to be kept to an absolute + minimum. + + - Markup for "tagged lists" or "label lists": field lists. + + Field lists represent a mapping from field name to field body. + These are mostly used for extension syntax, such as + "bibliographic field lists" (representing document metadata such + as author, date, and version) and extension attributes for + directives (see below). They may be used to implement docstring + semantics, such as identifying parameters, exceptions raised, + etc.; such usage is beyond the scope of this PEP. + + A modified RFC822 syntax is used, with a colon *before* as well + as *after* the field name. Field bodies are more versatile as + well; they may contain multiple field bodies (even nested field + lists). For example:: + + :Date: 2002-03-22 + :Version: 1 + :Authors: + - Me + - Myself + - I + + Standard RFC822 header syntax cannot be used for this construct + because it is ambiguous. A word followed by a colon at the + beginning of a line is common in written text. However, with + the addition of a well-defined context, such as when a field + list invariably occurs at the beginning of a document (e.g., + PEPs and email messages), standard RFC822 header syntax can be + used. + + - Markup extensibility: directives and substitutions. + + Directives are used as an extension mechanism for + reStructuredText, a way of adding support for new block-level + constructs without adding new syntax. Directives for images, + admonitions (note, caution, etc.), and tables of contents + generation (among others) have been implemented. For example, + here's how to place an image:: + + .. image:: mylogo.png + + Substitution definitions allow the power and flexibility of + block-level directives to be shared by inline text. For + example:: + + The |biohazard| symbol must be used on containers used to + dispose of medical waste. + + .. |biohazard| image:: biohazard.png + + - Section structure markup. + + Section headers in reStructuredText use adornment via underlines + (and possibly overlines) rather than indentation. For example:: + + This is a Section Title + ======================= + + This is a Subsection Title + -------------------------- + + This paragraph is in the subsection. + + This is Another Section Title + ============================= + + This paragraph is in the second section. + + +Questions & Answers + + Q: Is reStructuredText rich enough? + + A: Yes, it is for most people. If it lacks some construct that is + require for a specific application, it can be added via the + directive mechansism. If a common construct has been + overlooked and a suitably readable syntax can be found, it can + be added to the specification and parser. + + Q: Is reStructuredText *too* rich? + + A: No. + + Since the very beginning, whenever a markup syntax has been + proposed on the Doc-SIG, someone has complained about the lack + of support for some construct or other. The reply was often + something like, "These are docstrings we're talking about, and + docstrings shouldn't have complex markup." The problem is that + a construct that seems superfluous to one person may be + absolutely essential to another. + + reStructuredText takes the opposite approach: it provides a + rich set of implicit markup constructs (plus a generic + extension mechanism for explicit markup), allowing for all + kinds of documents. If the set of constructs is too rich for a + particular application, the unused constructs can either be + removed from the parser (via application-specific overrides) or + simply omitted by convention. + + Q: Why not use indentation for section structure, like + StructuredText does? Isn't it more "Pythonic"? + + A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG + post: + + I still think that using indentation to indicate sectioning + is wrong. If you look at how real books and other print + publications are laid out, you'll notice that indentation + is used frequently, but mostly at the intra-section level. + Indentation can be used to offset lists, tables, + quotations, examples, and the like. (The argument that + docstrings are different because they are input for a text + formatter is wrong: the whole point is that they are also + readable without processing.) + + I reject the argument that using indentation is Pythonic: + text is not code, and different traditions and conventions + hold. People have been presenting text for readability for + over 30 centuries. Let's not innovate needlessly. + + See "Section Structure via Indentation" in "Problems With + StructuredText" [14 ]_ for further elaboration. + + Q: Why use reStructuredText for PEPs? What's wrong with the + existing standard? + + A: The existing standard for PEPs is very limited in terms of + general expressibility, and referencing is especially lacking + for such a reference-rich document type. PEPs are currently + converted into HTML, but the results (mostly monospaced text) + are less than attractive, and most of the value-added potential + of HTML is untapped. + + Making reStructuredText the standard markup for PEPs will + enable much richer expression, including support for section + structure, inline markup, graphics, and tables. In several + PEPs there are ASCII graphics diagrams, which are all that + plaintext documents can support. Since PEPs are made available + in HTML form, the ability to include proper diagrams would be + immediately useful. + + Current PEP practices allow for reference markers in the form + "[1]" in the text, and the footnotes/references themselves are + listed in a section toward the end of the document. There is + currently no hyperlinking between the reference marker and the + footnote/reference itself (it would be possible to add this to + pep2html.py, but the "markup" as it stands is ambiguous and + mistakes would be inevitable). A PEP with many references + (such as this one ;-) requires a lot of flipping back and + forth. When revising a PEP, often new references are added or + unused references deleted. It is painful to renumber the + references, since it has to be done in two places and can have + a cascading effect (insert a single new reference 1, and every + other reference has to be renumbered; always adding new + references to the end is suboptimal). It is easy for + references to go out of sync. + + PEPs use references for two purposes: simple URL references and + footnotes. reStructuredText differentiates between the two. A + PEP might contain references like this:: + + Abstract + + This PEP proposes a adding frungible doodads [1] to the + core. It extends PEP 9876 [2] via the BCA [3] + mechanism. + + References and Footnotes + + [1] http://www.doodads.org/frungible.html + + [2] PEP 9876, Let's Hope We Never Get Here + http://www.python.org/peps/pep-9876.html + + [3] "Bogus Complexity Addition" + + Reference 1 is a simple URL reference. Reference 2 is a + footnote containing text and a URL. Reference 3 is a footnote + containing text only. Rewritten using reStructuredText, this + PEP could look like this:: + + Abstract + ======== + + This PEP proposes a adding `frungible doodads`_ to the + core. It extends PEP 9876 [#pep9876] via the BCA [#] + mechanism. + + .. _frungible doodads: + http://www.doodads.org/frungible.html + + .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here + + __ http://www.python.org/peps/pep-9876.html + + .. [#] "Bogus Complexity Addition" + + URLs and footnotes can be defined close to their references if + desired, making them easier to read in the source text, and + making the PEPs easier to revise. The "References and + Footnotes" section can be auto-generated with a document tree + transform. Footnotes from throughout the PEP would be gathered + and displayed under a standard header. If URL references + should likewise be written out explicitly (in citation form), + another tree transform could be used. + + URL references can be named ("frungible doodads"), and can be + referenced from multiple places in the document without + additional definitions. When converted to HTML, references + will be replaced with inline hyperlinks (HTML tags). The + two footnotes are automatically numbered, so they will always + stay in sync. The first footnote also contains an internal + reference name, "pep9876", so it's easier to see the connection + between reference and footnote in the source text. Named + footnotes can be referenced multiple times, maintaining + consistent numbering. + + The "#pep9876" footnote could also be written in the form of a + citation:: + + It extends PEP 9876 [PEP9876]_ ... + + .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here + + Footnotes are numbered, whereas citations use text for their + references. + + Q: Wouldn't it be better to keep the docstring and PEP proposals + separate? + + A: The PEP markup proposal is an option to this PEP. It may be + removed if it is deemed that there is no need for PEP markup. + The PEP markup proposal could be made into a separate PEP if + necessary. If accepted, PEP 1, PEP Purpose and Guidelines [19]_, + and PEP 9, Sample PEP Template [20]_ will be updated. + + It seems natural to adopt a single consistent markup standard + for all uses of plaintext in Python. + + Q: The existing pep2html.py script converts the existing PEP + format to HTML. How will the new-format PEPs be converted to + HTML? + + A: One of the deliverables of the Docutils project [21]_ will be a + new version of pep2html.py with integrated reStructuredText + parsing. The Docutils project will support PEPs with a "PEP + Reader" component, including all functionality currently in + pep2html.py (auto-recognition of PEP & RFC references). + + Q: Who's going to convert the existing PEPs to reStructuredText? + + A: A call for volunteers will be put out to the Doc-SIG and + greater Python communities. If insufficient volunteers are + forthcoming, I (David Goodger) will convert the documents + myself, perhaps with some level of automation. A transitional + system whereby both old and new standards can coexist will be + easy to implement (and I pledge to implement it if necessary). + + Q: Why use reStructuredText for README and other ancillary files? + + A: The same reasoning used for PEPs above applies to README and + other ancillary files. By adopting a standard markup, these + files can be converted to attractive cross-referenced HTML and + put up on python.org. Developers of Python projects can also + take advantage of this facility for their own documentation. + + +References and Footnotes + + [1] http://structuredtext.sourceforge.net/ + + [2] http://www.python.org/sigs/doc-sig/ + + [3] http://www.w3.org/XML/ + + [4] http://www.oasis-open.org/cover/general.html + + [5] http://docbook.org/tdg/en/html/docbook.html + + [6] http://www.w3.org/MarkUp/ + + [7] http://www.w3.org/MarkUp/#xhtml1 + + [8] http://www.tug.org/interest.html + + [9] http://www.perldoc.com/perl5.6/pod/perlpod.html + + [10] http://java.sun.com/j2se/javadoc/ + + [11] http://docutils.sourceforge.net/mirror/setext.html + + [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage + + [13] An Introduction to reStructuredText + http://structuredtext.sourceforge.net/spec/introduction.txt + + [14] Problems with StructuredText + http://structuredtext.sourceforge.net/spec/problems.txt + + [15] reStructuredText Markup Specification + http://structuredtext.sourceforge.net/spec/reStructuredText.txt + + [16] A Record of reStructuredText Syntax Alternatives + http://structuredtext.sourceforge.net/spec/alternatives.txt + + [17] reStructuredText Directives + http://structuredtext.sourceforge.net/spec/directives.txt + + [18] Quick reStructuredText + http://structuredtext.sourceforge.net/docs/quickref.html + + [19] PEP 1, PEP Guidelines, Warsaw, Hylton + http://www.python.org/peps/pep-0001.html + + [20] PEP 9, Sample PEP Template, Warsaw + http://www.python.org/peps/pep-0009.html + + [21] http://docutils.sourceforge.net/ + + [22] PEP 216, Docstring Format, Zadka + http://www.python.org/peps/pep-0216.html + + +Copyright + + This document has been placed in the public domain. + + +Acknowledgements + + Some text is borrowed from PEP 216, Docstring Format, by Moshe + Zadka [22]_. + + Special thanks to all members past & present of the Python Doc-SIG. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +sentence-end-double-space: t +fill-column: 70 +End: -- cgit v1.2.1 From 8eb0cda78664e494cdd033e3cdaf8c5c51be9c81 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 2 Apr 2002 03:28:25 +0000 Subject: As checked in to Python CVS 2002-04-01. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@8 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index f19354587..0b12971e3 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -1,4 +1,4 @@ -PEP: +PEP: 287 Title: reStructuredText Standard Docstring Format Version: $Revision$ Last-Modified: $Date$ @@ -6,8 +6,9 @@ Author: goodger@users.sourceforge.net (David Goodger) Discussions-To: doc-sig@python.org Status: Draft Type: Informational -Created: 2002-03-25 +Created: 25-Mar-2002 Post-History: +Replaces: 216 Abstract @@ -53,8 +54,8 @@ Goals 1. To establish a standard docstring format by attaining "accepted" status (Python community consensus; BDFL - pronouncement). Once reStructuredText is a Python standard, all - effort can be focused on tools instead of arguing for a + pronouncement). Once reStructuredText is a Python standard, + all effort can be focused on tools instead of arguing for a standard. Python needs a standard set of documentation tools. 2. To address any related concerns raised by the Python community. @@ -73,16 +74,17 @@ Goals applied: a) Keep the existing PEP section structure constructs (one-line - section headers, indented body text). Subsections can either - be forbidden or supported with underlined headers in the - indented body text. + section headers, indented body text). Subsections can + either be forbidden or supported with underlined headers in + the indented body text. b) Replace the PEP section structure constructs with the reStructuredText syntax. Section headers will require - underlines, subsections will be supported out of the box, and - body text need not be indented (except for block quotes). + underlines, subsections will be supported out of the box, + and body text need not be indented (except for block + quotes). - Support for RFC822 headers will be added to the + Support for RFC 2822 headers will be added to the reStructuredText parser (unambiguous given a specific context: the first contiguous block of a PEP document). It may be desired to concretely specify what over/underline styles are @@ -342,10 +344,10 @@ Features semantics, such as identifying parameters, exceptions raised, etc.; such usage is beyond the scope of this PEP. - A modified RFC822 syntax is used, with a colon *before* as well - as *after* the field name. Field bodies are more versatile as - well; they may contain multiple field bodies (even nested field - lists). For example:: + A modified RFC 2822 syntax is used, with a colon *before* as + well as *after* the field name. Field bodies are more versatile + as well; they may contain multiple field bodies (even nested + field lists). For example:: :Date: 2002-03-22 :Version: 1 @@ -354,13 +356,13 @@ Features - Myself - I - Standard RFC822 header syntax cannot be used for this construct - because it is ambiguous. A word followed by a colon at the - beginning of a line is common in written text. However, with - the addition of a well-defined context, such as when a field - list invariably occurs at the beginning of a document (e.g., - PEPs and email messages), standard RFC822 header syntax can be - used. + Standard RFC 2822 header syntax cannot be used for this + construct because it is ambiguous. A word followed by a colon + at the beginning of a line is common in written text. However, + with the addition of a well-defined context, such as when a + field list invariably occurs at the beginning of a document + (e.g., PEPs and email messages), standard RFC 2822 header syntax + can be used. - Markup extensibility: directives and substitutions. @@ -407,7 +409,7 @@ Questions & Answers A: Yes, it is for most people. If it lacks some construct that is require for a specific application, it can be added via the - directive mechansism. If a common construct has been + directive mechanism. If a common construct has been overlooked and a suitably readable syntax can be found, it can be added to the specification and parser. -- cgit v1.2.1 From 489ce879407408f5a852347ff7561ccdafa393f1 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 2 Apr 2002 03:50:38 +0000 Subject: As posted to Python-Dev and comp.lang.python on 2002-04-02. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@9 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 570 ++++++++++++++++++++++++++++--------------------- 1 file changed, 326 insertions(+), 244 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 0b12971e3..a61a40253 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -7,33 +7,78 @@ Discussions-To: doc-sig@python.org Status: Draft Type: Informational Created: 25-Mar-2002 -Post-History: +Post-History: 02-Apr-2002 Replaces: 216 Abstract - This PEP proposes that the reStructuredText [1]_ markup be adopted - as the standard markup format for plaintext documentation in - Python docstrings, and (optionally) for PEPs and ancillary - documents as well. reStructuredText is a rich and extensible yet - easy-to-read, what-you-see-is-what-you-get plaintext markup - syntax. + When plaintext hasn't been expressive enough for inline + documentation, Python programmers have sought out a format for + docstrings. This PEP proposes that the reStructuredText markup + [1]_ be adopted as the standard markup format for structured + plaintext documentation in Python docstrings, and for PEPs and + ancillary documents as well. reStructuredText is a rich and + extensible yet easy-to-read, what-you-see-is-what-you-get + plaintext markup syntax. Only the low-level syntax of docstrings is addressed here. This PEP is not concerned with docstring semantics or processing at - all. + all. Nor is it an attempt to deprecate pure plaintext docstrings, + which are always going to be legitimate. The reStructuredText + markup is an alternative for those who want more expressive + docstrings. + + +Benefits + + Programmers are by nature a lazy breed. We reuse code with + functions, classes, modules, and subsystems. Through its + docstring syntax, Python allows us to document our code from + within. The "holy grail" of the Python Documentation Special + Interest Group (Doc-SIG) [2]_ has been a markup syntax and toolset + to allow auto-documentation, where the docstrings of Python + systems can be extracted in context and processed into useful, + high-quality documentation for multiple purposes. + + The proposed format (reStructuredText) is entirely readable in + plaintext format, and many of the markup forms match common usage + (e.g., ``*emphasis*``), so it reads quite naturally. Yet it is + rich enough to produce complex documents, and extensible so that + there are few limits. + + The reStructuredText parser is available now. The Docutils + project is at the point where standalone reStructuredText + documents can be converted to HTML; other output format writers + will become available over time. Work is progressing on a Python + source "Reader" which will implement auto-documentation. Authors + of existing auto-documentation tools are encouraged to integrate + the reStructuredText parser into their projects, or better yet, to + join forces to produce a world-class toolset for the Python + standard library. + + Tools will become available in the near future, which will allow + programmers to generate HTML for online help, XML for multiple + purposes, and perhaps eventually PDF/DocBook/LaTeX for printed + documentation, essentially "for free" from the existing + docstrings. The adoption of a standard will, at the very least, + benefit docstring processing tools by preventing further + "reinventing the wheel". + + Eventually PyDoc, the one existing standard auto-documentation + tool, could have reStructuredText support added. In the interim + it will have no problem with reStructuredText markup, since it + treats all docstrings as plaintext. Goals These are the generally accepted goals for a docstring format, as - discussed in the Python Documentation Special Interest Group - (Doc-SIG) [2]_: + discussed in the Doc-SIG: - 1. It must be easy to type with any standard text editor. + 1. It must be readable in source form by the casual observer. - 2. It must be readable to the casual observer. + 2. It must be easy to type with any standard text editor. 3. It must not need to contain information which can be deduced from parsing the module. @@ -44,18 +89,15 @@ Goals 5. It must be possible to write a module's entire documentation in docstrings, without feeling hampered by the markup language. - [[Are these in fact the goals of the Doc-SIG members? Anything to - add?]] - reStructuredText meets and exceeds all of these goals, and sets its own goals as well, even more stringent. See "Features" below. The goals of this PEP are as follows: - 1. To establish a standard docstring format by attaining - "accepted" status (Python community consensus; BDFL + 1. To establish reStructuredText as a standard docstring format by + attaining "accepted" status (Python community consensus; BDFL pronouncement). Once reStructuredText is a Python standard, - all effort can be focused on tools instead of arguing for a + effort can be focused on tools instead of arguing for a standard. Python needs a standard set of documentation tools. 2. To address any related concerns raised by the Python community. @@ -69,9 +111,8 @@ Goals projects. It is hoped that interested developers will join forces and work on a joint/merged/common implementation. - 5. (Optional.) To adopt reStructuredText as the standard markup - for PEPs. One or both of the following strategies may be - applied: + 5. To adopt reStructuredText as the standard markup for PEPs. One + or both of the following strategies may be applied: a) Keep the existing PEP section structure constructs (one-line section headers, indented body text). Subsections can @@ -90,27 +131,20 @@ Goals desired to concretely specify what over/underline styles are allowed for PEP section headers, for uniformity. - 6. (Optional.) To adopt reStructuredText as the standard markup - for README-type files and other standalone documents in the - Python distribution. + 6. To adopt reStructuredText as the standard markup for + README-type files and other standalone documents in the Python + distribution. Rationale - The __doc__ attribute is called a documentation string, or - docstring. It is often used to summarize the interface of the - module, class or function. The lack of a standard syntax for - docstrings has hampered the development of standard tools for - extracting docstrings and transforming them into documentation in - standard formats (e.g., HTML, DocBook, TeX). There have been a - number of proposed markup formats and variations, and many tools - tied to these proposals, but without a standard docstring format - they have failed to gain a strong following and/or floundered - half-finished. - - The adoption of a standard will, at the very least, benefit - docstring processing tools by preventing further "reinventing the - wheel". + The lack of a standard syntax for docstrings has hampered the + development of standard tools for extracting and converting + docstrings into documentation in standard formats (e.g., HTML, + DocBook, TeX). There have been a number of proposed markup + formats and variations, and many tools tied to these proposals, + but without a standard docstring format they have failed to gain a + strong following and/or floundered half-finished. Throughout the existence of the Doc-SIG, consensus on a single standard docstring format has never been reached. A lightweight, @@ -188,7 +222,8 @@ Rationale requirements. - STexts have been sometimes surprising. Bits of text are - marked up unexpectedly, leading to user frustration. + unexpectedly interpreted as being marked up, leading to user + frustration. - SText implementations have been buggy. @@ -216,8 +251,8 @@ Features - An Introduction to reStructuredText [13]_ - - Problems With StructuredText [14]_ (optional, if you've used - StructuredText; it explains many markup decisions made) + - Problems With StructuredText [14]_ (optional for those who have + used StructuredText; it explains many markup decisions made) - reStructuredText Markup Specification [15]_ @@ -288,6 +323,8 @@ Features class Keeper(Storer): """ + Keep data fresher longer. + Extend `Storer`. Class attribute `instances` keeps track of the number of `Keeper` objects instantiated. """ @@ -358,11 +395,7 @@ Features Standard RFC 2822 header syntax cannot be used for this construct because it is ambiguous. A word followed by a colon - at the beginning of a line is common in written text. However, - with the addition of a well-defined context, such as when a - field list invariably occurs at the beginning of a document - (e.g., PEPs and email messages), standard RFC 2822 header syntax - can be used. + at the beginning of a line is common in written text. - Markup extensibility: directives and substitutions. @@ -381,7 +414,7 @@ Features The |biohazard| symbol must be used on containers used to dispose of medical waste. - + .. |biohazard| image:: biohazard.png - Section structure markup. @@ -405,203 +438,249 @@ Features Questions & Answers - Q: Is reStructuredText rich enough? - - A: Yes, it is for most people. If it lacks some construct that is - require for a specific application, it can be added via the - directive mechanism. If a common construct has been - overlooked and a suitably readable syntax can be found, it can - be added to the specification and parser. - - Q: Is reStructuredText *too* rich? - - A: No. - - Since the very beginning, whenever a markup syntax has been - proposed on the Doc-SIG, someone has complained about the lack - of support for some construct or other. The reply was often - something like, "These are docstrings we're talking about, and - docstrings shouldn't have complex markup." The problem is that - a construct that seems superfluous to one person may be - absolutely essential to another. - - reStructuredText takes the opposite approach: it provides a - rich set of implicit markup constructs (plus a generic - extension mechanism for explicit markup), allowing for all - kinds of documents. If the set of constructs is too rich for a - particular application, the unused constructs can either be - removed from the parser (via application-specific overrides) or - simply omitted by convention. - - Q: Why not use indentation for section structure, like - StructuredText does? Isn't it more "Pythonic"? - - A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG - post: - - I still think that using indentation to indicate sectioning - is wrong. If you look at how real books and other print - publications are laid out, you'll notice that indentation - is used frequently, but mostly at the intra-section level. - Indentation can be used to offset lists, tables, - quotations, examples, and the like. (The argument that - docstrings are different because they are input for a text - formatter is wrong: the whole point is that they are also - readable without processing.) - - I reject the argument that using indentation is Pythonic: - text is not code, and different traditions and conventions - hold. People have been presenting text for readability for - over 30 centuries. Let's not innovate needlessly. - - See "Section Structure via Indentation" in "Problems With - StructuredText" [14 ]_ for further elaboration. - - Q: Why use reStructuredText for PEPs? What's wrong with the - existing standard? - - A: The existing standard for PEPs is very limited in terms of - general expressibility, and referencing is especially lacking - for such a reference-rich document type. PEPs are currently - converted into HTML, but the results (mostly monospaced text) - are less than attractive, and most of the value-added potential - of HTML is untapped. - - Making reStructuredText the standard markup for PEPs will - enable much richer expression, including support for section - structure, inline markup, graphics, and tables. In several - PEPs there are ASCII graphics diagrams, which are all that - plaintext documents can support. Since PEPs are made available - in HTML form, the ability to include proper diagrams would be - immediately useful. - - Current PEP practices allow for reference markers in the form - "[1]" in the text, and the footnotes/references themselves are - listed in a section toward the end of the document. There is - currently no hyperlinking between the reference marker and the - footnote/reference itself (it would be possible to add this to - pep2html.py, but the "markup" as it stands is ambiguous and - mistakes would be inevitable). A PEP with many references - (such as this one ;-) requires a lot of flipping back and - forth. When revising a PEP, often new references are added or - unused references deleted. It is painful to renumber the - references, since it has to be done in two places and can have - a cascading effect (insert a single new reference 1, and every - other reference has to be renumbered; always adding new - references to the end is suboptimal). It is easy for - references to go out of sync. - - PEPs use references for two purposes: simple URL references and - footnotes. reStructuredText differentiates between the two. A - PEP might contain references like this:: - - Abstract - - This PEP proposes a adding frungible doodads [1] to the - core. It extends PEP 9876 [2] via the BCA [3] - mechanism. - - References and Footnotes - - [1] http://www.doodads.org/frungible.html - - [2] PEP 9876, Let's Hope We Never Get Here - http://www.python.org/peps/pep-9876.html - - [3] "Bogus Complexity Addition" - - Reference 1 is a simple URL reference. Reference 2 is a - footnote containing text and a URL. Reference 3 is a footnote - containing text only. Rewritten using reStructuredText, this - PEP could look like this:: - - Abstract - ======== - - This PEP proposes a adding `frungible doodads`_ to the - core. It extends PEP 9876 [#pep9876] via the BCA [#] - mechanism. - - .. _frungible doodads: - http://www.doodads.org/frungible.html - - .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here - - __ http://www.python.org/peps/pep-9876.html - - .. [#] "Bogus Complexity Addition" - - URLs and footnotes can be defined close to their references if - desired, making them easier to read in the source text, and - making the PEPs easier to revise. The "References and - Footnotes" section can be auto-generated with a document tree - transform. Footnotes from throughout the PEP would be gathered - and displayed under a standard header. If URL references - should likewise be written out explicitly (in citation form), - another tree transform could be used. - - URL references can be named ("frungible doodads"), and can be - referenced from multiple places in the document without - additional definitions. When converted to HTML, references - will be replaced with inline hyperlinks (HTML tags). The - two footnotes are automatically numbered, so they will always - stay in sync. The first footnote also contains an internal - reference name, "pep9876", so it's easier to see the connection - between reference and footnote in the source text. Named - footnotes can be referenced multiple times, maintaining - consistent numbering. - - The "#pep9876" footnote could also be written in the form of a - citation:: - - It extends PEP 9876 [PEP9876]_ ... - - .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here - - Footnotes are numbered, whereas citations use text for their - references. - - Q: Wouldn't it be better to keep the docstring and PEP proposals - separate? - - A: The PEP markup proposal is an option to this PEP. It may be - removed if it is deemed that there is no need for PEP markup. - The PEP markup proposal could be made into a separate PEP if - necessary. If accepted, PEP 1, PEP Purpose and Guidelines [19]_, - and PEP 9, Sample PEP Template [20]_ will be updated. - - It seems natural to adopt a single consistent markup standard - for all uses of plaintext in Python. - - Q: The existing pep2html.py script converts the existing PEP - format to HTML. How will the new-format PEPs be converted to - HTML? + Q1: Is reStructuredText rich enough? + + A1: Yes, it is for most people. If it lacks some construct that + is required for a specific application, it can be added via + the directive mechanism. If a common construct has been + overlooked and a suitably readable syntax can be found, it can + be added to the specification and parser. + + Q2: Is reStructuredText *too* rich? + + A2: For specific applications or individuals, perhaps. In + general, no. + + Since the very beginning, whenever a markup syntax has been + proposed on the Doc-SIG, someone has complained about the lack + of support for some construct or other. The reply was often + something like, "These are docstrings we're talking about, and + docstrings shouldn't have complex markup." The problem is + that a construct that seems superfluous to one person may be + absolutely essential to another. + + reStructuredText takes the opposite approach: it provides a + rich set of implicit markup constructs (plus a generic + extension mechanism for explicit markup), allowing for all + kinds of documents. If the set of constructs is too rich for + a particular application, the unused constructs can either be + removed from the parser (via application-specific overrides) + or simply omitted by convention. + + Q3: Why not use indentation for section structure, like + StructuredText does? Isn't it more "Pythonic"? + + A3: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG + post: + + I still think that using indentation to indicate + sectioning is wrong. If you look at how real books and + other print publications are laid out, you'll notice that + indentation is used frequently, but mostly at the + intra-section level. Indentation can be used to offset + lists, tables, quotations, examples, and the like. (The + argument that docstrings are different because they are + input for a text formatter is wrong: the whole point is + that they are also readable without processing.) + + I reject the argument that using indentation is Pythonic: + text is not code, and different traditions and conventions + hold. People have been presenting text for readability + for over 30 centuries. Let's not innovate needlessly. + + See "Section Structure via Indentation" in "Problems With + StructuredText" [14]_ for further elaboration. + + Q4: Why use reStructuredText for PEPs? What's wrong with the + existing standard? + + A4: The existing standard for PEPs is very limited in terms of + general expressibility, and referencing is especially lacking + for such a reference-rich document type. PEPs are currently + converted into HTML, but the results (mostly monospaced text) + are less than attractive, and most of the value-added + potential of HTML is untapped. + + Making reStructuredText the standard markup for PEPs will + enable much richer expression, including support for section + structure, inline markup, graphics, and tables. In several + PEPs there are ASCII graphics diagrams, which are all that + plaintext documents can support. Since PEPs are made + available in HTML form, the ability to include proper diagrams + would be immediately useful. + + Current PEP practices allow for reference markers in the form + "[1]" in the text, and the footnotes/references themselves are + listed in a section toward the end of the document. There is + currently no hyperlinking between the reference marker and the + footnote/reference itself (it would be possible to add this to + pep2html.py, but the "markup" as it stands is ambiguous and + mistakes would be inevitable). A PEP with many references + (such as this one ;-) requires a lot of flipping back and + forth. When revising a PEP, often new references are added or + unused references deleted. It is painful to renumber the + references, since it has to be done in two places and can have + a cascading effect (insert a single new reference 1, and every + other reference has to be renumbered; always adding new + references to the end is suboptimal). It is easy for + references to go out of sync. + + PEPs use references for two purposes: simple URL references + and footnotes. reStructuredText differentiates between the + two. A PEP might contain references like this:: + + Abstract + + This PEP proposes adding frungible doodads [1] to the + core. It extends PEP 9876 [2] via the BCA [3] + mechanism. + + References and Footnotes + + [1] http://www.example.org/ + + [2] PEP 9876, Let's Hope We Never Get Here + http://www.python.org/peps/pep-9876.html + + [3] "Bogus Complexity Addition" + + Reference 1 is a simple URL reference. Reference 2 is a + footnote containing text and a URL. Reference 3 is a footnote + containing text only. Rewritten using reStructuredText, this + PEP could look like this:: + + Abstract + ======== + + This PEP proposes adding `frungible doodads`_ to the + core. It extends PEP 9876 [#pep9876]_ via the BCA [#]_ + mechanism. + + .. _frungible doodads: http://www.example.org/ + + .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here + + __ http://www.python.org/peps/pep-9876.html + + .. [#] "Bogus Complexity Addition" + + URLs and footnotes can be defined close to their references if + desired, making them easier to read in the source text, and + making the PEPs easier to revise. The "References and + Footnotes" section can be auto-generated with a document tree + transform. Footnotes from throughout the PEP would be + gathered and displayed under a standard header. If URL + references should likewise be written out explicitly (in + citation form), another tree transform could be used. + + URL references can be named ("frungible doodads"), and can be + referenced from multiple places in the document without + additional definitions. When converted to HTML, references + will be replaced with inline hyperlinks (HTML tags). The + two footnotes are automatically numbered, so they will always + stay in sync. The first footnote also contains an internal + reference name, "pep9876", so it's easier to see the + connection between reference and footnote in the source text. + Named footnotes can be referenced multiple times, maintaining + consistent numbering. + + The "#pep9876" footnote could also be written in the form of a + citation:: + + It extends PEP 9876 [PEP9876]_ ... + + .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here + + Footnotes are numbered, whereas citations use text for their + references. + + Q5: Wouldn't it be better to keep the docstring and PEP proposals + separate? + + A5: The PEP markup proposal may be removed if it is deemed that + there is no need for PEP markup, or it could be made into a + separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines + [19]_, and PEP 9, Sample PEP Template [20]_ will be updated. + + It seems natural to adopt a single consistent markup standard + for all uses of structured plaintext in Python, and to propose + it all in one place. + + Q6: The existing pep2html.py script converts the existing PEP + format to HTML. How will the new-format PEPs be converted to + HTML? + + A6: One of the deliverables of the Docutils project [21]_ will be + a new version of pep2html.py with integrated reStructuredText + parsing. The Docutils project will support PEPs with a "PEP + Reader" component, including all functionality currently in + pep2html.py (auto-recognition of PEP & RFC references). + + Q7: Who's going to convert the existing PEPs to reStructuredText? + + A7: A call for volunteers will be put out to the Doc-SIG and + greater Python communities. If insufficient volunteers are + forthcoming, I (David Goodger) will convert the documents + myself, perhaps with some level of automation. A transitional + system whereby both old and new standards can coexist will be + easy to implement (and I pledge to implement it if necessary). - A: One of the deliverables of the Docutils project [21]_ will be a - new version of pep2html.py with integrated reStructuredText - parsing. The Docutils project will support PEPs with a "PEP - Reader" component, including all functionality currently in - pep2html.py (auto-recognition of PEP & RFC references). + Q8: Why use reStructuredText for README and other ancillary files? - Q: Who's going to convert the existing PEPs to reStructuredText? + A8: The reasoning given for PEPs in A4 above also applies to + README and other ancillary files. By adopting a standard + markup, these files can be converted to attractive + cross-referenced HTML and put up on python.org. Developers of + Python projects can also take advantage of this facility for + their own documentation. - A: A call for volunteers will be put out to the Doc-SIG and - greater Python communities. If insufficient volunteers are - forthcoming, I (David Goodger) will convert the documents - myself, perhaps with some level of automation. A transitional - system whereby both old and new standards can coexist will be - easy to implement (and I pledge to implement it if necessary). - - Q: Why use reStructuredText for README and other ancillary files? - - A: The same reasoning used for PEPs above applies to README and - other ancillary files. By adopting a standard markup, these - files can be converted to attractive cross-referenced HTML and - put up on python.org. Developers of Python projects can also - take advantage of this facility for their own documentation. - - -References and Footnotes + Q9: Won't the superficial similarity to existing markup + conventions cause problems, and result in people writing + invalid markup (and not noticing, because the plaintext looks + natural)? How forgiving is reStructuredText of "not quite + right" markup? + + A9: There will be some mis-steps, as there would be when moving + from one programming language to another. As with any + language, proficiency grows with experience. Luckily, + reStructuredText is a very little language indeed. + + As with any syntax, there is the possibility of syntax errors. + It is expected that a user will run the processing system over + their input and check the output for correctness. + + In a strict sense, the reStructuredText parser is very + unforgiving (as it should be; "In the face of ambiguity, + refuse the temptation to guess" [22]_ applies to parsing + markup as well as computer languages). Here's a design goal + from "An Introduction to reStructuredText" [13]_: + + 3. Unambiguous. The rules for markup must not be open for + interpretation. For any given input, there should be + one and only one possible output (including error + output). + + While unforgiving, at the same time the parser does try to be + helpful by producing useful diagnostic output ("system + messages"). The parser reports problems, indicating their + level of severity (from least to most: debug, info, warning, + error, severe). The user or the client software can decide on + reporting thresholds; they can ignore low-level problems or + cause high-level problems to bring processing to an immediate + halt. Problems are reported during the parse as well as + included in the output, often with two-way links between the + source of the problem and the system message explaining it. + + Q10: Will the docstrings in the Python standard library modules be + converted to reStructuredText? + + A10: Over time, with the help of the developer community, many + modules will be converted. Some modules may never be + converted. A future toolset will have to allow for + incompleteness. + + +References & Footnotes [1] http://structuredtext.sourceforge.net/ @@ -653,7 +732,10 @@ References and Footnotes [21] http://docutils.sourceforge.net/ - [22] PEP 216, Docstring Format, Zadka + [22] From "The Zen of Python (by Tim Peters)", + http://www.python.org/doc/Humor.html#zen + + [23] PEP 216, Docstring Format, Zadka http://www.python.org/peps/pep-0216.html @@ -664,8 +746,8 @@ Copyright Acknowledgements - Some text is borrowed from PEP 216, Docstring Format, by Moshe - Zadka [22]_. + Some text is borrowed from PEP 216, Docstring Format [23]_, by + Moshe Zadka. Special thanks to all members past & present of the Python Doc-SIG. -- cgit v1.2.1 From 937dd4cba2a71f56d703dea76578f080cbc65ef8 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 4 Apr 2002 05:55:26 +0000 Subject: responding to feedback git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@10 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index a61a40253..f886d94c2 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -166,22 +166,23 @@ Rationale 4. Implicit markup is aesthetically compatible with the clean and minimalist Python syntax. - Proposed alternatives have included: + Many alternative markups have been proposed on the Doc-SIG, + including: - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_ XML and SGML are explicit, well-formed meta-languages suitable for all kinds of documentation. XML is a variant of SGML. They - are best used behind the scenes, because they are verbose, - difficult to type, and too cluttered to read comfortably as - source. DocBook, HTML, and XHTML are all applications of SGML - and/or XML, and all share the same basic syntax and the same - shortcomings. + are best used behind the scenes, because to untrained eyes they + are verbose, difficult to type, and too cluttered to read + comfortably as source. DocBook, HTML, and XHTML are all + applications of SGML and/or XML, and all share the same basic + syntax and the same shortcomings. - TeX [8]_ - TeX is similar to XML/SGML in that it's explicit, not very easy - to write, and not easy for the uninitiated to read. + TeX is similar to XML/SGML in that it's explicit, but not very + easy to write, and not easy for the uninitiated to read. - Perl POD [9]_ @@ -197,10 +198,9 @@ Rationale Special comments before Java classes and functions serve to document the code. A program to extract these, and turn them into HTML documentation is called javadoc, and is part of the - standard Java distribution. However, the only output format - that is supported is HTML, and JavaDoc has a very intimate - relationship with HTML, using HTML tags for most markup. Thus - it shares the readability problems of HTML. + standard Java distribution. However, JavaDoc has a very + intimate relationship with HTML, using HTML tags for most + markup. Thus it shares the readability problems of HTML. - Setext [11]_, StructuredText [12]_ @@ -234,6 +234,10 @@ Rationale - There has been no mechanism to get around the SText markup rules when a markup character is used in a non-markup context. + (Please note that this is not an exclusive list of all existing + markup systems, just a sample of those seriously proposed for + docstring use, on the Doc-SIG.) + Proponents of implicit STexts have vigorously opposed proposals for explicit markup (XML, HTML, TeX, POD, etc.), and the debates have continued off and on since 1996 or earlier. @@ -679,6 +683,13 @@ Questions & Answers converted. A future toolset will have to allow for incompleteness. + Q11: I want to write all my strings in Unicode. Will anything + break? + + A11: The parser will fully support Unicode. It may not yet, but + only because nobody's gotten around to implementing or + testing Unicode support. Contributions are always welcome! + References & Footnotes -- cgit v1.2.1 From 6b6fa81523b8fd785994f7bf20dc3f12594d467c Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 13 Apr 2002 17:17:35 +0000 Subject: Preliminary post-initial-posting edit; incomplete. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@11 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 150 +++++++++++++++++++++++++++++-------------------- 1 file changed, 89 insertions(+), 61 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index f886d94c2..74496d412 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -16,7 +16,7 @@ Abstract When plaintext hasn't been expressive enough for inline documentation, Python programmers have sought out a format for docstrings. This PEP proposes that the reStructuredText markup - [1]_ be adopted as the standard markup format for structured + [1]_ be adopted as a standard markup format for structured plaintext documentation in Python docstrings, and for PEPs and ancillary documents as well. reStructuredText is a rich and extensible yet easy-to-read, what-you-see-is-what-you-get @@ -41,11 +41,19 @@ Benefits systems can be extracted in context and processed into useful, high-quality documentation for multiple purposes. - The proposed format (reStructuredText) is entirely readable in - plaintext format, and many of the markup forms match common usage - (e.g., ``*emphasis*``), so it reads quite naturally. Yet it is - rich enough to produce complex documents, and extensible so that - there are few limits. + Document markup languages have three groups of customers: the + authors who write the documents, the software systems that process + the data, and the readers, who are the final consumers and the + most important group. Most markups are designed for the authors + and software systems; readers are only meant to see the processed + form, either on paper or via browser software. ReStructuredText + is different: it is intended to be easily readable in source form, + without prior knowledge of the markup. ReStructuredText) is + entirely readable in plaintext format, and many of the markup + forms match common usage (e.g., ``*emphasis*``), so it reads quite + naturally. Yet it is rich enough to produce complex documents, + and extensible so that there are few limits. Of course, to write + reStructuredText documents prior knowledge is required. The reStructuredText parser is available now. The Docutils project is at the point where standalone reStructuredText @@ -94,13 +102,18 @@ Goals The goals of this PEP are as follows: - 1. To establish reStructuredText as a standard docstring format by - attaining "accepted" status (Python community consensus; BDFL - pronouncement). Once reStructuredText is a Python standard, - effort can be focused on tools instead of arguing for a - standard. Python needs a standard set of documentation tools. + 1. To establish reStructuredText as a standard structured + plaintext format for docstrings (inline documentation of Python + modules and packages), PEPs, README-type files and other + standalone documents. "Accepted" status will be sought through + Python community consensus and eventual BDFL pronouncement. - 2. To address any related concerns raised by the Python community. + Please note that reStructuredText is being proposed as *a* + standard, not *the only* standard. Its use will be entirely + optional. Those who don't want to use it need not. + + 2. To solicit and address any related concerns raised by the + Python community. 3. To encourage community support. As long as multiple competing markups are out there, the development community remains @@ -111,29 +124,29 @@ Goals projects. It is hoped that interested developers will join forces and work on a joint/merged/common implementation. - 5. To adopt reStructuredText as the standard markup for PEPs. One - or both of the following strategies may be applied: + Once reStructuredText is a Python standard, effort can be focused + on tools instead of arguing for a standard. Python needs a + standard set of documentation tools. - a) Keep the existing PEP section structure constructs (one-line - section headers, indented body text). Subsections can - either be forbidden or supported with underlined headers in - the indented body text. + With regard to PEPs, one or both of the following strategies may + be applied: - b) Replace the PEP section structure constructs with the - reStructuredText syntax. Section headers will require - underlines, subsections will be supported out of the box, - and body text need not be indented (except for block - quotes). + a) Keep the existing PEP section structure constructs (one-line + section headers, indented body text). Subsections can + either be forbidden or supported with underlined headers in + the indented body text. - Support for RFC 2822 headers will be added to the - reStructuredText parser (unambiguous given a specific context: - the first contiguous block of a PEP document). It may be - desired to concretely specify what over/underline styles are - allowed for PEP section headers, for uniformity. + b) Replace the PEP section structure constructs with the + reStructuredText syntax. Section headers will require + underlines, subsections will be supported out of the box, + and body text need not be indented (except for block + quotes). - 6. To adopt reStructuredText as the standard markup for - README-type files and other standalone documents in the Python - distribution. + Support for RFC 2822 headers will be added to the reStructuredText + parser for PEPs (unambiguous given a specific context: the first + contiguous block of the document). It may be desired to + concretely specify what over/underline styles are allowed for PEP + section headers, for uniformity. Rationale @@ -166,8 +179,12 @@ Rationale 4. Implicit markup is aesthetically compatible with the clean and minimalist Python syntax. - Many alternative markups have been proposed on the Doc-SIG, - including: + Many alternative markups for docstrings have been proposed on the + Doc-SIG over the years; a representative sample is listed below. + Each is briefly analyzed in terms of the goals stated above. + Please note that this is *not* intended to be an exclusive list of + all existing markup systems; there are many other markups + (Texinfo, Doxygen, TIM, YODL, AFT, ...) which are not mentioned. - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_ @@ -234,10 +251,6 @@ Rationale - There has been no mechanism to get around the SText markup rules when a markup character is used in a non-markup context. - (Please note that this is not an exclusive list of all existing - markup systems, just a sample of those seriously proposed for - docstring use, on the Doc-SIG.) - Proponents of implicit STexts have vigorously opposed proposals for explicit markup (XML, HTML, TeX, POD, etc.), and the debates have continued off and on since 1996 or earlier. @@ -248,24 +261,26 @@ Rationale Features - Rather than repeating or summarizing the extensive - reStructuredText spec, please read the originals available from - http://structuredtext.sourceforge.net/spec/ (.txt & .html files). - Reading the documents in following order is recommended: + The specification and user documentaton for reStructuredText is + quite extensive. Rather than repeating or summarizing it all + here, links to the originals are provided. - - An Introduction to reStructuredText [13]_ + Please first take a look at "A ReStructuredText Primer" []_, a + short and gentle introduction. The "Quick reStructuredText" user + reference [18]_ quickly summarizes all of the markup constructs. + For complete and extensive details, the following documents + contain the full specification itself: - - Problems With StructuredText [14]_ (optional for those who have - used StructuredText; it explains many markup decisions made) + - An Introduction to reStructuredText [13]_ - reStructuredText Markup Specification [15]_ - - A Record of reStructuredText Syntax Alternatives [16]_ (explains - markup decisions made independently of StructuredText) - - reStructuredText Directives [17]_ - There is also a "Quick reStructuredText" user reference [18]_. + In addition, "Problems With StructuredText" [14]_ explains many + markup decisions made with regards to StructuredText, and "A + Record of reStructuredText Syntax Alternatives" [16]_ records + markup decisions made independently. A summary of features addressing often-raised docstring markup concerns follows: @@ -622,12 +637,11 @@ Questions & Answers Q7: Who's going to convert the existing PEPs to reStructuredText? - A7: A call for volunteers will be put out to the Doc-SIG and - greater Python communities. If insufficient volunteers are - forthcoming, I (David Goodger) will convert the documents - myself, perhaps with some level of automation. A transitional - system whereby both old and new standards can coexist will be - easy to implement (and I pledge to implement it if necessary). + A7: PEP authors or volunteers may convert existing PEPs if they + like, but there is no requirement to do so. The + reStructuredText-based PEPs will coexist with the old PEP + standard. The pep2html.py mentioned in A6 will process both + old and new standards. Q8: Why use reStructuredText for README and other ancillary files? @@ -678,10 +692,12 @@ Questions & Answers Q10: Will the docstrings in the Python standard library modules be converted to reStructuredText? - A10: Over time, with the help of the developer community, many - modules will be converted. Some modules may never be - converted. A future toolset will have to allow for - incompleteness. + A10: No. Python's library reference documentation is maintained + separately from the source. Docstrings in the Python + standard library should not try to duplicate the library + reference documentation. The current policy for docstrings + in the Python standard library is that they should be no more + than concise hints. Q11: I want to write all my strings in Unicode. Will anything break? @@ -690,6 +706,15 @@ Questions & Answers only because nobody's gotten around to implementing or testing Unicode support. Contributions are always welcome! + Q12: Why does the community need a new structured text design? + What is wrong with existing markup methodologies? + + A12: The existing structured text designs are deficient. + @@@ + + For Python docstrings, there is no official standard. + @@@ + References & Footnotes @@ -717,6 +742,12 @@ References & Footnotes [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage + [] A ReStructuredText Primer + http://structuredtext.sourceforge.net/docs/quickstart.html + + [18] Quick reStructuredText + http://structuredtext.sourceforge.net/docs/quickref.html + [13] An Introduction to reStructuredText http://structuredtext.sourceforge.net/spec/introduction.txt @@ -732,9 +763,6 @@ References & Footnotes [17] reStructuredText Directives http://structuredtext.sourceforge.net/spec/directives.txt - [18] Quick reStructuredText - http://structuredtext.sourceforge.net/docs/quickref.html - [19] PEP 1, PEP Guidelines, Warsaw, Hylton http://www.python.org/peps/pep-0001.html -- cgit v1.2.1 From ae4f07d30c23b941eb03e5ad59fb6600e74012a2 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 13 Apr 2002 17:18:52 +0000 Subject: Docstring Semantics -- notes initially git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@12 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/dev/semantics.txt (limited to 'docs') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt new file mode 100644 index 000000000..96d2d5644 --- /dev/null +++ b/docs/dev/semantics.txt @@ -0,0 +1,38 @@ +===================== + Docstring Semantics +===================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +These are notes for a possible future PEP providing the final piece of +the Python docstring puzzle. + +PythonDoc +========= + +A Python version of the JavaDoc semantics (not syntax). A set of +conventions which are understood by the Docutils. + +- 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 + +- Use field lists or definition lists for "tagged blocks". + +- Frederic Giacometti's "iPhrase Python documentation conventions" is + an attachment to his Doc-SIG post of 2001-05-30 + (http://mail.python.org/pipermail/doc-sig/2001-May/001840.html). -- cgit v1.2.1 From 3522fa4da8a8aec1e7da46cf4eb4a5239ed17bfd Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Apr 2002 02:50:09 +0000 Subject: More editing progress. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@16 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 73 +++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 36 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 74496d412..3f0536231 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -259,31 +259,31 @@ Rationale the SText idea, addressing all of the problems listed above. -Features +Specification The specification and user documentaton for reStructuredText is quite extensive. Rather than repeating or summarizing it all here, links to the originals are provided. - Please first take a look at "A ReStructuredText Primer" []_, a + Please first take a look at "A ReStructuredText Primer" [13]_, a short and gentle introduction. The "Quick reStructuredText" user - reference [18]_ quickly summarizes all of the markup constructs. + reference [14]_ quickly summarizes all of the markup constructs. For complete and extensive details, the following documents contain the full specification itself: - - An Introduction to reStructuredText [13]_ + - An Introduction to reStructuredText [15]_ - - reStructuredText Markup Specification [15]_ + - reStructuredText Markup Specification [16]_ - reStructuredText Directives [17]_ - In addition, "Problems With StructuredText" [14]_ explains many + In addition, "Problems With StructuredText" [18]_ explains many markup decisions made with regards to StructuredText, and "A - Record of reStructuredText Syntax Alternatives" [16]_ records + Record of reStructuredText Syntax Alternatives" [19]_ records markup decisions made independently. - A summary of features addressing often-raised docstring markup - concerns follows: + +Docstring-Significant Features - A markup escaping mechanism. @@ -396,9 +396,10 @@ Features These are mostly used for extension syntax, such as "bibliographic field lists" (representing document metadata such as author, date, and version) and extension attributes for - directives (see below). They may be used to implement docstring - semantics, such as identifying parameters, exceptions raised, - etc.; such usage is beyond the scope of this PEP. + directives (see below). They may be used to implement + methodologies (docstring semantics), such as identifying + parameters, exceptions raised, etc.; such usage is beyond the + scope of this PEP. A modified RFC 2822 syntax is used, with a colon *before* as well as *after* the field name. Field bodies are more versatile @@ -508,7 +509,7 @@ Questions & Answers for over 30 centuries. Let's not innovate needlessly. See "Section Structure via Indentation" in "Problems With - StructuredText" [14]_ for further elaboration. + StructuredText" [18 ]_ for further elaboration. Q4: Why use reStructuredText for PEPs? What's wrong with the existing standard? @@ -520,8 +521,8 @@ Questions & Answers are less than attractive, and most of the value-added potential of HTML is untapped. - Making reStructuredText the standard markup for PEPs will - enable much richer expression, including support for section + Making reStructuredText a standard markup for PEPs will enable + much richer expression, including support for section structure, inline markup, graphics, and tables. In several PEPs there are ASCII graphics diagrams, which are all that plaintext documents can support. Since PEPs are made @@ -619,7 +620,7 @@ Questions & Answers A5: The PEP markup proposal may be removed if it is deemed that there is no need for PEP markup, or it could be made into a separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines - [19]_, and PEP 9, Sample PEP Template [20]_ will be updated. + [20]_, and PEP 9, Sample PEP Template [21]_ will be updated. It seems natural to adopt a single consistent markup standard for all uses of structured plaintext in Python, and to propose @@ -629,7 +630,7 @@ Questions & Answers format to HTML. How will the new-format PEPs be converted to HTML? - A6: One of the deliverables of the Docutils project [21]_ will be + A6: One of the deliverables of the Docutils project [22]_ will be a new version of pep2html.py with integrated reStructuredText parsing. The Docutils project will support PEPs with a "PEP Reader" component, including all functionality currently in @@ -669,9 +670,9 @@ Questions & Answers In a strict sense, the reStructuredText parser is very unforgiving (as it should be; "In the face of ambiguity, - refuse the temptation to guess" [22]_ applies to parsing + refuse the temptation to guess" [23]_ applies to parsing markup as well as computer languages). Here's a design goal - from "An Introduction to reStructuredText" [13]_: + from "An Introduction to reStructuredText" [15 ]_: 3. Unambiguous. The rules for markup must not be open for interpretation. For any given input, there should be @@ -742,39 +743,39 @@ References & Footnotes [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage - [] A ReStructuredText Primer + [13] A ReStructuredText Primer http://structuredtext.sourceforge.net/docs/quickstart.html - [18] Quick reStructuredText + [14] Quick reStructuredText http://structuredtext.sourceforge.net/docs/quickref.html - [13] An Introduction to reStructuredText + [15] An Introduction to reStructuredText http://structuredtext.sourceforge.net/spec/introduction.txt - [14] Problems with StructuredText - http://structuredtext.sourceforge.net/spec/problems.txt - - [15] reStructuredText Markup Specification + [16] reStructuredText Markup Specification http://structuredtext.sourceforge.net/spec/reStructuredText.txt - [16] A Record of reStructuredText Syntax Alternatives - http://structuredtext.sourceforge.net/spec/alternatives.txt - [17] reStructuredText Directives http://structuredtext.sourceforge.net/spec/directives.txt - [19] PEP 1, PEP Guidelines, Warsaw, Hylton + [18] Problems with StructuredText + http://structuredtext.sourceforge.net/spec/problems.txt + + [19] A Record of reStructuredText Syntax Alternatives + http://structuredtext.sourceforge.net/spec/alternatives.txt + + [20] PEP 1, PEP Guidelines, Warsaw, Hylton http://www.python.org/peps/pep-0001.html - [20] PEP 9, Sample PEP Template, Warsaw + [21] PEP 9, Sample PEP Template, Warsaw http://www.python.org/peps/pep-0009.html - [21] http://docutils.sourceforge.net/ + [22] http://docutils.sourceforge.net/ - [22] From "The Zen of Python (by Tim Peters)", - http://www.python.org/doc/Humor.html#zen + [23] From "The Zen of Python (by Tim Peters)", + http://www.python.org/doc/Humor.html#zen (or ``import this``) - [23] PEP 216, Docstring Format, Zadka + [24] PEP 216, Docstring Format, Zadka http://www.python.org/peps/pep-0216.html @@ -785,7 +786,7 @@ Copyright Acknowledgements - Some text is borrowed from PEP 216, Docstring Format [23]_, by + Some text is borrowed from PEP 216, Docstring Format [24]_, by Moshe Zadka. Special thanks to all members past & present of the Python Doc-SIG. -- cgit v1.2.1 From 101671ae44e1686680c80cd07b452aabeb88fb63 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 03:01:52 +0000 Subject: Initial revision git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@18 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 212 ++++ docs/dev/pysource.txt | 173 +++ docs/dev/rst/alternatives.txt | 1239 +++++++++++++++++++ docs/dev/rst/problems.txt | 761 ++++++++++++ docs/dev/todo.txt | 385 ++++++ docs/peps/pep-0256.txt | 253 ++++ docs/peps/pep-0257.txt | 248 ++++ docs/peps/pep-0258.txt | 662 ++++++++++ docs/ref/doctree.txt | 344 ++++++ docs/ref/docutils.dtd | 514 ++++++++ docs/ref/rst/directives.txt | 360 ++++++ docs/ref/rst/introduction.txt | 307 +++++ docs/ref/rst/restructuredtext.txt | 2344 ++++++++++++++++++++++++++++++++++++ docs/ref/soextblx.dtd | 312 +++++ docs/user/rst/images/ball1.gif | Bin 0 -> 4361 bytes docs/user/rst/images/biohazard.bmp | Bin 0 -> 406 bytes docs/user/rst/images/biohazard.gif | Bin 0 -> 949 bytes docs/user/rst/images/biohazard.png | Bin 0 -> 179 bytes docs/user/rst/images/title.png | Bin 0 -> 1171 bytes docs/user/rst/quickref.html | 1096 +++++++++++++++++ docs/user/rst/quickstart.txt | 301 +++++ 21 files changed, 9511 insertions(+) create mode 100644 docs/dev/pysource.dtd create mode 100644 docs/dev/pysource.txt create mode 100644 docs/dev/rst/alternatives.txt create mode 100644 docs/dev/rst/problems.txt create mode 100644 docs/dev/todo.txt create mode 100644 docs/peps/pep-0256.txt create mode 100644 docs/peps/pep-0257.txt create mode 100644 docs/peps/pep-0258.txt create mode 100644 docs/ref/doctree.txt create mode 100644 docs/ref/docutils.dtd create mode 100644 docs/ref/rst/directives.txt create mode 100644 docs/ref/rst/introduction.txt create mode 100644 docs/ref/rst/restructuredtext.txt create mode 100644 docs/ref/soextblx.dtd create mode 100644 docs/user/rst/images/ball1.gif create mode 100644 docs/user/rst/images/biohazard.bmp create mode 100644 docs/user/rst/images/biohazard.gif create mode 100644 docs/user/rst/images/biohazard.png create mode 100644 docs/user/rst/images/title.png create mode 100644 docs/user/rst/quickref.html create mode 100644 docs/user/rst/quickstart.txt (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd new file mode 100644 index 000000000..463844a68 --- /dev/null +++ b/docs/dev/pysource.dtd @@ -0,0 +1,212 @@ + + + + + + + + + + + + + +%docutils; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt new file mode 100644 index 000000000..a75fd1d4d --- /dev/null +++ b/docs/dev/pysource.txt @@ -0,0 +1,173 @@ +====================== + Python Source Reader +====================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +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:: + + +Python Source Reader +==================== + +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`_ above. + +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 spec/ppdi.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. + +In Python docstrings, interpreted text is used to classify and mark up +program identifiers, such as the names of variables, functions, +classes, and modules. If the identifier alone is given, its role is +inferred implicitly according to the Python namespace lookup rules. +For functions and methods (even when dynamically assigned), +parentheses ('()') may be included:: + + This function uses `another()` to do its work. + +For class, instance and module attributes, dotted identifiers are used +when necessary:: + + class Keeper(Storer): + + """ + Extend `Storer`. Class attribute `instances` keeps track of + the number of `Keeper` objects instantiated. + """ + + instances = 0 + """How many `Keeper` objects are there?""" + + def __init__(self): + """ + Extend `Storer.__init__()` to keep track of instances. + + Keep count in `self.instances` and data in `self.data`. + """ + Storer.__init__(self) + self.instances += 1 + + self.data = [] + """Store data in a list, most recent last.""" + + def storedata(self, data): + """ + Extend `Storer.storedata()`; append new `data` to a list + (in `self.data`). + """ + self.data = data + +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. + +.. _reStructuredText Markup Specification: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _Docutils: http://docutils.sourceforge.net/ +.. _pysource.dtd: http://docutils.sourceforge.net/spec/pysource.dtd +.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + fill-column: 70 + End: diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt new file mode 100644 index 000000000..9bbe9a2f1 --- /dev/null +++ b/docs/dev/rst/alternatives.txt @@ -0,0 +1,1239 @@ +================================================== + A Record of reStructuredText Syntax Alternatives +================================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +The following are ideas, alternatives, and justifications that were +considered for reStructuredText syntax, which did not originate with +Setext_ or StructuredText_. For an analysis of constructs which *did* +originate with StructuredText or Setext, please see `Problems With +StructuredText`_. See the `reStructuredText Markup Specification`_ +for full details of the established syntax. + +.. _Setext: http://docutils.sourceforge.net/mirror/setext.html +.. _StructuredText: + http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage +.. _Problems with StructuredText: problems.html +.. _reStructuredText Markup Specification: reStructuredText.html + + +.. contents:: + + +... Or Not To Do? +================= + +This is the realm of the possible but questionably probable. These +ideas are kept here as a record of what has been proposed, for +posterity and in case any of them prove to be useful. + + +Compound Enumerated Lists +------------------------- + +Allow for compound enumerators, such as '1.1.' or '1.a.' or '1(a)', to +allow for nested enumerated lists without indentation? + + +Auto-Numbered Enumerated Lists +------------------------------ + +Add these? Example:: + + #. Item 1. + #. Item 2. + #. Item 3. + +Arabic numerals only, or any sequence if first initialized? For +example:: + + a) Item a. + #) Item b. + #) Item c. + + +Sloppy Indentation of List Items +-------------------------------- + +Perhaps the indentation shouldn't be so strict. Currently, this is +required:: + + 1. First line, + second line. + +Anything wrong with this? :: + + 1. First line, + second line. + +Problem? + + 1. First para. + + Block quote. (no good: requires some indent relative to first + para) + + Second Para. + + 2. Have to carefully define where the literal block ends:: + + Literal block + + Literal block? + +Hmm... Non-strict indentation isn't such a good idea. + + +Lazy Indentation of List Items +------------------------------ + +Another approach: Going back to the first draft of reStructuredText +(2000-11-27 post to Doc-SIG):: + + - This is the fourth item of the main list (no blank line above). + The second line of this item is not indented relative to the + bullet, which precludes it from having a second paragraph. + +Change that to *require* a blank line above and below, to reduce +ambiguity. This "loosening" may be added later, once the parser's +been nailed down. However, a serious drawback of this approach is to +limit the content of each list item to a single paragraph. + + +David's Idea for Lazy Indentation +````````````````````````````````` + +Consider a paragraph in a word processor. It is a single logical line +of text which ends with a newline, soft-wrapped arbitrarily at the +right edge of the page or screen. We can think of a plaintext +paragraph in the same way, as a single logical line of text, ending +with two newlines (a blank line) instead of one, and which may contain +arbitrary line breaks (newlines) where it was accidentally +hard-wrapped by an application. We can compensate for the accidental +hard-wrapping by "unwrapping" every unindented second and subsequent +line. The indentation of the first line of a paragraph or list item +would determine the indentation for the entire element. Blank lines +would be required between list items when using lazy indentation. + +The following example shows the lazy indentation of multiple body +elements:: + + - This is the first paragraph + of the first list item. + + Here is the second paragraph + of the first list item. + + - This is the first paragraph + of the second list item. + + Here is the second paragraph + of the second list item. + +A more complex example shows the limitations of lazy indentation:: + + - This is the first paragraph + of the first list item. + + Next is a definition list item: + + Term + Definition. The indentation of the term is + required, as is the indentation of the definition's + first line. + + When the definition extends to more than + one line, lazy indentation may occur. (This is the second + paragraph of the definition.) + + - This is the first paragraph + of the second list item. + + - Here is the first paragraph of + the first item of a nested list. + + So this paragraph would be outside of the nested list, + but inside the second list item of the outer list. + + But this paragraph is not part of the list at all. + +And the ambiguity remains:: + + - Look at the hyphen at the beginning of the next line + - is it a second list item marker, or a dash in the text? + + Similarly, we may want to refer to numbers inside enumerated + lists: + + 1. How many socks in a pair? There are + 2. How many pants in a pair? Exactly + 1. Go figure. + +Literal blocks and block quotes would still require consistent +indentation for all their lines. For block quotes, we might be able +to get away with only requiring that the first line of each contained +element be indented. For example:: + + Here's a paragraph. + + This is a paragraph inside a block quote. + Second and subsequent lines need not be indented at all. + + - A bullet list inside + the block quote. + + Second paragraph of the + bullet list inside the block quote. + +Although feasible, this form of lazy indentation has problems. The +document structure and hierarchy is not obvious from the indentation, +making the source plaintext difficult to read. This will also make +keeping track of the indentation while writing difficult and +error-prone. However, these problems may be acceptable for Wikis and +email mode, where we may be able to rely on less complex structure +(few nested lists, for example). + + +Field Lists +=========== + +Prior to the syntax for field lists being finalized, several +alternatives were proposed. + +1. Unadorned RFC822_ everywhere:: + + Author: Me + Version: 1 + + Advantages: clean, precedent (RFC822-compliant). Disadvantage: + ambiguous (these paragraphs are a prime example). + + Conclusion: rejected. + +2. Special case: use unadorned RFC822_ for the very first or very last + text block of a document:: + + """ + Author: Me + Version: 1 + + The rest of the document... + """ + + Advantages: clean, precedent (RFC822-compliant). Disadvantages: + special case, flat (unnested) field lists only, still ambiguous:: + + """ + Usage: cmdname [options] arg1 arg2 ... + + We obviously *don't* want the like above to be interpreted as a + field list item. Or do we? + """ + + Conclusion: rejected for the general case, accepted for specific + contexts (PEPs, email). + +3. Use a directive:: + + .. fields:: + + Author: Me + Version: 1 + + Advantages: explicit and unambiguous, RFC822-compliant. + Disadvantage: cumbersome. + + Conclusion: rejected for the general case (but such a directive + could certainly be written). + +4. Use Javadoc-style:: + + @Author: Me + @Version: 1 + @param a: integer + + Advantages: unambiguous, precedent, flexible. Disadvantages: + non-intuitive, ugly, not RFC822-compliant. + + Conclusion: rejected. + +5. Use leading colons:: + + :Author: Me + :Version: 1 + + Advantages: unambiguous, obvious (*almost* RFC822-compliant), + flexible, perhaps even elegant. Disadvantages: no precedent, not + quite RFC822-compliant. + + Conclusion: accepted! + +6. Use double colons:: + + Author:: Me + Version:: 1 + + Advantages: unambiguous, obvious? (*almost* RFC822-compliant), + flexible, similar to syntax already used for literal blocks and + directives. Disadvantages: no precedent, not quite + RFC822-compliant, similar to syntax already used for literal blocks + and directives. + + Conclusion: rejected because of the syntax similarity & conflicts. + +Why is RFC822 compliance important? It's a universal Internet +standard, and super obvious. Also, I'd like to support the PEP format +(ulterior motive: get PEPs to use reStructuredText as their standard). +But it *would* be easy to get used to an alternative (easy even to +convert PEPs; probably harder to convert python-deviants ;-). + +Unfortunately, without well-defined context (such as in email headers: +RFC822 only applies before any blank lines), the RFC822 format is +ambiguous. It is very common in ordinary text. To implement field +lists unambiguously, we need explicit syntax. + +The following question was posed in a footnote: + + Should "bibliographic field lists" be defined at the parser level, + or at the DPS transformation level? In other words, are they + reStructuredText-specific, or would they also be applicable to + another (many/every other?) syntax? + +The answer is that bibliographic fields are a +reStructuredText-specific markup convention. Other syntaxes may +implement the bibliographic elements explicitly. For example, there +would be no need for such a transformation for an XML-based markup +syntax. + +.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt + + +Interpreted Text "Roles" +======================== + +The original purpose of interpreted text was as a mechanism for +descriptive markup, to describe the nature or role of a word or +phrase. For example, in XML we could say "len" +to mark up "len" as a function. It is envisaged that within Python +docstrings (inline documentation in Python module source files, the +primary market for reStructuredText) the role of a piece of +interpreted text can be inferred implicitly from the context of the +docstring within the program source. For other applications, however, +the role may have to be indicated explicitly. + +Interpreted text is enclosed in single backquotes (`). + +1. Initially, it was proposed that an explicit role could be indicated + as a word or phrase within the enclosing backquotes: + + - As a prefix, separated by a colon and whitespace:: + + `role: interpreted text` + + - As a suffix, separated by whitespace and a colon:: + + `interpreted text :role` + + There are problems with the initial approach: + + - There could be ambiguity with interpreted text containing colons. + For example, an index entry of "Mission: Impossible" would + require a backslash-escaped colon. + + - The explicit role is descriptive markup, not content, and will + not be visible in the processed output. Putting it inside the + backquotes doesn't feel right; the *role* isn't being quoted. + +2. Tony Ibbs suggested that the role be placed outside the + backquotes:: + + role:`prefix` or `suffix`:role + + This removes the embedded-colons ambiguity, but limits the role + identifier to be a single word (whitespace would be illegal). + Since roles are not meant to be visible after processing, the lack + of whitespace support is not important. + + The suggested syntax remains ambiguous with respect to ratios and + some writing styles. For example, suppose there is a "signal" + identifier, and we write:: + + ...calculate the `signal`:noise ratio. + + "noise" looks like a role. + +3. As an improvement on #2, we can bracket the role with colons:: + + :role:`prefix` or `suffix`:role: + + This syntax is similar to that of field lists, which is fine since + both are doing similar things: describing. + + This is the syntax chosen for reStructuredText. + +4. Another alternative is two colons instead of one:: + + role::`prefix` or `suffix`::role + + But this is used for analogies ("A:B::C:D": "A is to B as C is to + D"). + + Both alternative #2 and #4 lack delimiters on both sides of the + role, making it difficult to parse (by the reader). + +5. Some kind of bracketing could be used: + + - Parentheses:: + + (role)`prefix` or `suffix`(role) + + - Braces:: + + {role}`prefix` or `suffix`{role} + + - Square brackets:: + + [role]`prefix` or `suffix`[role] + + - Angle brackets:: + + `prefix` or `suffix` + + (The overlap of \*ML tags with angle brackets would be too + confusing and precludes their use.) + +Syntax #3 was chosen for reStructuredText. + + +Comments +======== + +A problem with comments (actually, with all indented constructs) is +that they cannot be followed by an indented block -- a block quote -- +without swallowing it up. + +I thought that perhaps comments should be one-liners only. But would +this mean that footnotes, hyperlink targets, and directives must then +also be one-liners? Not a good solution. + +Tony Ibbs suggested a "comment" directive. I added that we could +limit a comment to a single text block, and that a "multi-block +comment" could use "comment-start" and "comment-end" directives. This +would remove the indentation incompatibility. A "comment" directive +automatically suggests "footnote" and (hyperlink) "target" directives +as well. This could go on forever! Bad choice. + +Garth Kidd suggested that an "empty comment", a ".." explicit markup +start with nothing on the first line (except possibly whitespace) and +a blank line immediately following, could serve as an "unindent". An +empty comment does **not** swallow up indented blocks following it, +so block quotes are safe. "A tiny but practical wart." Accepted. + + +Anonymous Hyperlinks +==================== + +Alan Jaffray came up with this idea, along with the following syntax:: + + Search the `Python DOC-SIG mailing list archives`{}_. + + .. _: http://mail.python.org/pipermail/doc-sig/ + +The idea is sound and useful. I suggested a "double underscore" +syntax:: + + Search the `Python DOC-SIG mailing list archives`__. + + .. __: http://mail.python.org/pipermail/doc-sig/ + +But perhaps single underscores are okay? The syntax looks better, but +the hyperlink itself doesn't explicitly say "anonymous":: + + Search the `Python DOC-SIG mailing list archives`_. + + .. _: http://mail.python.org/pipermail/doc-sig/ + +Mixing anonymous and named hyperlinks becomes confusing. The order of +targets is not significant for named hyperlinks, but it is for +anonymous hyperlinks:: + + Hyperlinks: anonymous_, named_, and another anonymous_. + + .. _named: named + .. _: anonymous1 + .. _: anonymous2 + +Without the extra syntax of double underscores, determining which +hyperlink references are anonymous may be difficult. We'd have to +check which references don't have corresponding targets, and match +those up with anonymous targets. Keeping to a simple consistent +ordering (as with auto-numbered footnotes) seems simplest. + +reStructuredText will use the explicit double-underscore syntax for +anonymous hyperlinks. An alternative (see `Reworking Explicit +Markup`_ below) for the somewhat awkward ".. __:" syntax is "__":: + + An anonymous__ reference. + + __ http://anonymous + + +Reworking Explicit Markup +========================= + +Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added +to reStructuredText. Subsequently it was asserted that hyperlinks +(especially anonymous hyperlinks) would play an increasingly important +role in reStructuredText documents, and therefore they require a +simpler and more concise syntax. This prompted a review of the +current and proposed explicit markup syntaxes with regards to +improving usability. + +1. Original syntax:: + + .. _blah: internal hyperlink target + .. _blah: http://somewhere external hyperlink target + .. _blah: blahblah_ indirect hyperlink target + .. __: anonymous internal target + .. __: http://somewhere anonymous external target + .. __: blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment + + .. Note:: + + The comment text was intentionally made to look like a hyperlink + target. + + Origins: + + * Except for the colon (a delimiter necessary to allow for + phrase-links), hyperlink target ``.. _blah:`` comes from Setext. + * Comment syntax from Setext. + * Footnote syntax from StructuredText ("named links"). + * Directives and anonymous hyperlinks original to reStructuredText. + + Advantages: + + + Consistent explicit markup indicator: "..". + + Consistent hyperlink syntax: ".. _" & ":". + + Disadvantages: + + - Anonymous target markup is awkward: ".. __:". + - The explicit markup indicator ("..") is excessively overloaded? + - Comment text is limited (can't look like a footnote, hyperlink, + or directive). But this is probably not important. + +2. Alan Jaffray's proposed syntax #1:: + + __ _blah internal hyperlink target + __ blah: http://somewhere external hyperlink target + __ blah: blahblah_ indirect hyperlink target + __ anonymous internal target + __ http://somewhere anonymous external target + __ blahblah_ anonymous indirect target + __ [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment + + The hyperlink-connoted underscores have become first-level syntax. + + Advantages: + + + Anonymous targets are simpler. + + All hyperlink targets are one character shorter. + + Disadvantages: + + - Inconsistent internal hyperlink targets. Unlike all other named + hyperlink targets, there's no colon. There's an extra leading + underscore, but we can't drop it because without it, "blah" looks + like a relative URI. Unless we restore the colon:: + + __ blah: internal hyperlink target + + - Obtrusive markup? + +3. Alan Jaffray's proposed syntax #2:: + + .. _blah internal hyperlink target + .. blah: http://somewhere external hyperlink target + .. blah: blahblah_ indirect hyperlink target + .. anonymous internal target + .. http://somewhere anonymous external target + .. blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + !! blah: http://somewhere directive + ## blah: http://somewhere comment + + Leading underscores have been (almost) replaced by "..", while + comments and directives have gained their own syntax. + + Advantages: + + + Anonymous hyperlinks are simpler. + + Unique syntax for comments. Connotation of "comment" from + some programming languages (including our favorite). + + Unique syntax for directives. Connotation of "action!". + + Disadvantages: + + - Inconsistent internal hyperlink targets. Again, unlike all other + named hyperlink targets, there's no colon. There's a leading + underscore, matching the trailing underscores of references, + which no other hyperlink targets have. We can't drop that one + leading underscore though: without it, "blah" looks like a + relative URI. Again, unless we restore the colon:: + + .. blah: internal hyperlink target + + - All (except for internal) hyperlink targets lack their leading + underscores, losing the "hyperlink" connotation. + + - Obtrusive syntax for comments. Alternatives:: + + ;; blah: http://somewhere + (also comment syntax in Lisp & others) + ,, blah: http://somewhere + ("comma comma": sounds like "comment"!) + + - Iffy syntax for directives. Alternatives? + +4. Tony Ibbs' proposed syntax:: + + .. _blah: internal hyperlink target + .. _blah: http://somewhere external hyperlink target + .. _blah: blahblah_ indirect hyperlink target + .. anonymous internal target + .. http://somewhere anonymous external target + .. blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment + + This is the same as the current syntax, except for anonymous + targets which drop their "__: ". + + Advantage: + + + Anonymous targets are simpler. + + Disadvantages: + + - Anonymous targets lack their leading underscores, losing the + "hyperlink" connotation. + - Anonymous targets are almost indistinguishable from comments. + (Better to know "up front".) + +5. David Goodger's proposed syntax: Perhaps going back to one of + Alan's earlier suggestions might be the best solution. How about + simply adding "__ " as a synonym for ".. __: " in the original + syntax? These would become equivalent:: + + .. __: anonymous internal target + .. __: http://somewhere anonymous external target + .. __: blahblah_ anonymous indirect target + + __ anonymous internal target + __ http://somewhere anonymous external target + __ blahblah_ anonymous indirect target + +Alternative 5 has been adopted. + + +Backquotes in Phrase-Links +========================== + +[From a 2001-06-05 Doc-SIG post in reply to questions from Doug +Hellmann.] + +The first draft of the spec, posted to the Doc-SIG in November 2000, +used square brackets for phrase-links. I changed my mind because: + +1. In the first draft, I had already decided on single-backquotes for + inline literal text. + +2. However, I wanted to minimize the necessity for backslash escapes, + for example when quoting Python repr-equivalent syntax that uses + backquotes. + +3. The processing of identifiers (funtion/method/attribute/module/etc. + names) into hyperlinks is a useful feature. PyDoc recognizes + identifiers heuristically, but it doesn't take much imagination to + come up with counter-examples where PyDoc's heuristics would result + in embarassing failure. I wanted to do it deterministically, and + that called for syntax. I called this construct 'interpreted + text'. + +4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the + idea of using double-backquotes as syntax. + +5. I worked out some rules for inline markup recognition. + +6. In combination with #5, double backquotes lent themselves to inline + literals, neatly satisfying #2, minimizing backslash escapes. In + fact, the spec says that no interpretation of any kind is done + within double-backquote inline literal text; backslashes do *no* + escaping within literal text. + +7. Single backquotes are then freed up for interpreted text. + +8. I already had square brackets required for footnote references. + +9. Since interpreted text will typically turn into hyperlinks, it was + a natural fit to use backquotes as the phrase-quoting syntax for + trailing-underscore hyperlinks. + +The original inspiration for the trailing underscore hyperlink syntax +was Setext. But for phrases Setext used a very cumbersome +``underscores_between_words_like_this_`` syntax. + +The underscores can be viewed as if they were right-pointing arrows: +``-->``. So ``hyperlink_`` points away from the reference, and +``.. _hyperlink:`` points toward the target. + + +Substitution Mechanism +====================== + +Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by +Alan Jaffray, "reStructuredText inline markup". It reminded me of a +missing piece of the reStructuredText puzzle, first referred to in my +contribution to "Documentation markup & processing / PEPs" (Doc-SIG +2001-06-21). + +Substitutions allow the power and flexibility of directives to be +shared by inline text. They are a way to allow arbitrarily complex +inline objects, while keeping the details out of the flow of text. +They are the equivalent of SGML/XML's named entities. For example, an +inline image (using reference syntax alternative 4d (vertical bars) +and definition alternative 3, the alternatives chosen for inclusion in +the spec):: + + The |biohazard| symbol must be used on containers used to dispose + of medical waste. + + .. |biohazard| image:: biohazard.png + [height=20 width=20] + +The ``|biohazard|`` substitution reference will be replaced in-line by +whatever the ``.. |biohazard|`` substitution definition generates (in +this case, an image). A substitution definition contains the +substitution text bracketed with vertical bars, followed by a an +embedded inline-compatible directive, such as "image". A transform is +required to complete the substitution. + +Syntax alternatives for the reference: + +1. Use the existing interpreted text syntax, with a predefined role + such as "sub":: + + The `biohazard`:sub: symbol... + + Advantages: existing syntax, explicit. Disadvantages: verbose, + obtrusive. + +2. Use a variant of the interpreted text syntax, with a new suffix + akin to the underscore in phrase-link references:: + + (a) `name`@ + (b) `name`# + (c) `name`& + (d) `name`/ + (e) `name`< + (f) `name`:: + (g) `name`: + + + Due to incompatibility with other constructs and ordinary text + usage, (f) and (g) are not possible. + +3. Use interpreted text syntax with a fixed internal format:: + + (a) `:name:` + (b) `name:` + (c) `name::` + (d) `::name::` + (e) `%name%` + (f) `#name#` + (g) `/name/` + (h) `&name&` + (i) `|name|` + (j) `[name]` + (k) `` + (l) `&name;` + (m) `'name'` + + To avoid ML confusion (k) and (l) are definitely out. Square + brackets (j) won't work in the target (the substitution definition + would be indistinguishable from a footnote). + + The ```/name/``` syntax (g) is reminiscent of "s/find/sub" + substitution syntax in ed-like languages. However, it may have a + misleading association with regexps, and looks like an absolute + POSIX path. (i) is visually equivalent and lacking the + connotations. + + A disadvantage of all of these is that they limit interpreted text, + albeit only slightly. + +4. Use specialized syntax, something new:: + + (a) #name# + (b) @name@ + (c) /name/ + (d) |name| + (e) <> + (f) //name// + (g) ||name|| + (h) ^name^ + (i) [[name]] + (j) ~name~ + (k) !name! + (l) =name= + (m) ?name? + (n) >name< + + "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes + looks just like a POSIX path; it is likely for such usage to appear + in text. + + "|" (d) and "^" (h) are feasible. + +5. Redefine the trailing underscore syntax. See definition syntax + alternative 4, below. + +Syntax alternatives for the definition: + +1. Use the existing directive syntax, with a predefined directive such + as "sub". It contains a further embedded directive resolving to an + inline-compatible object:: + + .. sub:: biohazard + .. image:: biohazard.png + [height=20 width=20] + + .. sub:: parrot + That bird wouldn't *voom* if you put 10,000,000 volts + through it! + + The advantages and disadvantages are the same as in inline + alternative 1. + +2. Use syntax as in #1, but with an embedded directivecompressed:: + + .. sub:: biohazard image:: biohazard.png + [height=20 width=20] + + This is a bit better than alternative 1, but still too much. + +3. Use a variant of directive syntax, incorporating the substitution + text, obviating the need for a special "sub" directive name. If we + assume reference alternative 4d (vertical bars), the matching + definition would look like this:: + + .. |biohazard| image:: biohazard.png + [height=20 width=20] + +4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) + + Instead of adding new syntax, redefine the trailing underscore + syntax to mean "substitution reference" instead of "hyperlink + reference". Alan's example:: + + I had lunch with Jonathan_ today. We talked about Zope_. + + .. _Jonathan: lj [user=jhl] + .. _Zope: http://www.zope.org/ + + A problem with the proposed syntax is that URIs which look like + simple reference names (alphanum plus ".", "-", "_") would be + indistinguishable from substitution directive names. A more + consistent syntax would be:: + + I had lunch with Jonathan_ today. We talked about Zope_. + + .. _Jonathan: lj:: user=jhl + .. _Zope: http://www.zope.org/ + + (``::`` after ``.. _Jonathan: lj``.) + + The "Zope" target is a simple external hyperlink, but the + "Jonathan" target contains a directive. Alan proposed is that the + reference text be replaced by whatever the referenced directive + (the "directive target") produces. A directive reference becomes a + hyperlink reference if the contents of the directive target resolve + to a hyperlink. If the directive target resolves to an icon, the + reference is replaced by an inline icon. If the directive target + resolves to a hyperlink, the directive reference becomes a + hyperlink reference. + + This seems too indirect and complicated for easy comprehension. + + The reference in the text will sometimes become a link, sometimes + not. Sometimes the reference text will remain, sometimes not. We + don't know *at the reference*:: + + This is a `hyperlink reference`_; its text will remain. + This is an `inline icon`_; its text will disappear. + + That's a problem. + +The syntax that has been incorporated into the spec and parser is +reference alternative 4d with definition alternative 3:: + + The |biohazard| symbol... + + .. |biohazard| image:: biohazard.png + [height=20 width=20] + +We can also combine substitution references with hyperlink references, +by appending a "_" (named hyperlink reference) or "__" (anonymous +hyperlink reference) suffix to the substitution reference. This +allows us to click on an image-link:: + + The |biohazard|_ symbol... + + .. |biohazard| image:: biohazard.png + [height=20 width=20] + .. _biohazard: http://www.cdc.gov/ + +There have been several suggestions for the naming of these +constructs, originally called "substitution references" and +"substitutions". + +1. Candidate names for the reference construct: + + (a) substitution reference + (b) tagging reference + (c) inline directive reference + (d) directive reference + (e) indirect inline directive reference + (f) inline directive placeholder + (g) inline directive insertion reference + (h) directive insertion reference + (i) insertion reference + (j) directive macro reference + (k) macro reference + (l) substitution directive reference + +2. Candidate names for the definition construct: + + (a) substitution + (b) substitution directive + (c) tag + (d) tagged directive + (e) directive target + (f) inline directive + (g) inline directive definition + (h) referenced directive + (i) indirect directive + (j) indirect directive definition + (k) directive definition + (l) indirect inline directive + (m) named directive definition + (n) inline directive insertion definition + (o) directive insertion definition + (p) insertion definition + (q) insertion directive + (r) substitution definition + (s) directive macro definition + (t) macro definition + (u) substitution directive definition + (v) substitution definition + +"Inline directive reference" (1c) seems to be an appropriate term at +first, but the term "inline" is redundant in the case of the +reference. Its counterpart "inline directive definition" (2g) is +awkward, because the directive definition itself is not inline. + +"Directive reference" (1d) and "directive definition" (2k) are too +vague. "Directive definition" could be used to refer to any +directive, not just those used for inline substitutions. + +One meaning of the term "macro" (1k, 2s, 2t) is too +programming-language-specific. Also, macros are typically simple text +substitution mechanisms: the text is substituted first and evaluated +later. reStructuredText substitution definitions are evaluated in +place at parse time and substituted afterwards. + +"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that +something new is getting added rather than one construct being +replaced by another. + +Which brings us back to "substitution". The overall best names are +"substitution reference" (1a) and "substitution definition" (2v). A +long way to go to add one word! + + +Reworking Footnotes +=================== + +As a further wrinkle (see `Reworking Explicit Markup`_ above), in the +wee hours of 2002-02-28 I posted several ideas for changes to footnote +syntax: + + - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... + - Differentiate (with new DTD elements) author-date "citations" + (``[GVR2002]``) from numbered footnotes? ... + - Render footnote references as superscripts without "[]"? ... + +These ideas are all related, and suggest changes in the +reStructuredText syntax as well as the docutils tree model. + +The footnote has been used for both true footnotes (asides expanding +on points or defining terms) and for citations (references to external +works). Rather than dealing with one amalgam construct, we could +separate the current footnote concept into strict footnotes and +citations. Citations could be interpreted and treated differently +from footnotes. Footnotes would be limited to numerical labels: +manual ("1") and auto-numbered (anonymous "#", named "#label"). + +The footnote is the only explicit markup construct (starts with ".. ") +that directly translates to a visible body element. I've always been +a little bit uncomfortable with the ".. " marker for footnotes because +of this; ".. " has a connotation of "special", but footnotes aren't +especially "special". Printed texts often put footnotes at the bottom +of the page where the reference occurs (thus "foot note"). Some HTML +designs would leave footnotes to be rendered the same positions where +they're defined. Other online and printed designs will gather +footnotes into a section near the end of the document, converting them +to "endnotes" (perhaps using a directive in our case); but this +"special processing" is not an intrinsic property of the footnote +itself, but a decision made by the document author or processing +system. + +Citations are almost invariably collected in a section at the end of a +document or section. Citations "disappear" from where they are +defined and are magically reinserted at some well-defined point. +There's more of a connection to the "special" connotation of the ".. " +syntax. The point at which the list of citations is inserted could be +defined manually by a directive (e.g., ".. citations::"), and/or have +default behavior (e.g., a section automatically inserted at the end of +the document) that might be influenced by options to the Writer. + +Syntax proposals: + ++ Footnotes: + + - Current syntax:: + + .. [1] Footnote 1 + .. [#] Auto-numbered footnote. + .. [#label] Auto-labeled footnote. + + - The syntax proposed in the original 2002-02-28 Doc-SIG post: + remove the ".. ", prefix a "_":: + + _[1] Footnote 1 + _[#] Auto-numbered footnote. + _[#label] Auto-labeled footnote. + + The leading underscore syntax (earlier dropped because + ``.. _[1]:`` was too verbose) is a useful reminder that footnotes + are hyperlink targets. + + - Minimal syntax: remove the ".. [" and "]", prefix a "_", and + suffix a ".":: + + _1. Footnote 1. + _#. Auto-numbered footnote. + _#label. Auto-labeled footnote. + + ``_1.``, ``_#.``, and ``_#label.`` are markers, + like list markers. + + Footnotes could be rendered something like this in HTML + + | 1. This is a footnote. The brackets could be dropped + | from the label, and a vertical bar could set them + | off from the rest of the document in the HTML. + + Two-way hyperlinks on the footnote marker ("1." above) would also + help to differentiate footnotes from enumerated lists. + + If converted to endnotes (by a directive/transform), a horizontal + half-line might be used instead. Page-oriented output formats + would typically use the horizontal line for true footnotes. + ++ Footnote references: + + - Current syntax:: + + [1]_, [#]_, [#label]_ + + - Minimal syntax to match the minimal footnote syntax above:: + + 1_, #_, #label_ + + As a consequence, pure-numeric hyperlink references would not be + possible; they'd be interpreted as footnote references. + ++ Citation references: no change is proposed from the current footnote + reference syntax:: + + [GVR2001]_ + ++ Citations: + + - Current syntax (footnote syntax):: + + .. [GVR2001] Python Documentation; van Rossum, Drake, et al.; + http://www.python.org/doc/ + + - Possible new syntax:: + + _[GVR2001] Python Documentation; van Rossum, Drake, et al.; + http://www.python.org/doc/ + + _[DJG2002] + Docutils: Python Documentation Utilities project; Goodger + et al.; http://docutils.sourceforge.net/ + + Without the ".. " marker, subsequent lines would either have to + align as in one of the above, or we'd have to allow loose + alignment (I'd rather not):: + + _[GVR2001] Python Documentation; van Rossum, Drake, et al.; + http://www.python.org/doc/ + +I proposed adopting the "minimal" syntax for footnotes and footnote +references, and adding citations and citation references to +reStructuredText's repertoire. The current footnote syntax for +citations is better than the alternatives given. + +From a reply by Tony Ibbs on 2002-03-01: + + However, I think easier with examples, so let's create one:: + + Fans of Terry Pratchett are perhaps more likely to use + footnotes [1]_ in their own writings than other people + [2]_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style [4]_, particularly in emails (not a medium that + lends itself to footnotes). + + .. [1] That is, little bits of referenced text at the + bottom of the page. + .. [2] Because Terry himself does, of course [3]_. + .. [3] Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + .. [4] Presumably because it detracts from linear + reading of the text - this is, of course, the point. + + and look at it with the second syntax proposal:: + + Fans of Terry Pratchett are perhaps more likely to use + footnotes [1]_ in their own writings than other people + [2]_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style [4]_, particularly in emails (not a medium that + lends itself to footnotes). + + _[1] That is, little bits of referenced text at the + bottom of the page. + _[2] Because Terry himself does, of course [3]_. + _[3] Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + _[4] Presumably because it detracts from linear + reading of the text - this is, of course, the point. + + (I note here that if I have gotten the indentation of the + footnotes themselves correct, this is clearly not as nice. And if + the indentation should be to the left margin instead, I like that + even less). + + and the third (new) proposal:: + + Fans of Terry Pratchett are perhaps more likely to use + footnotes 1_ in their own writings than other people + 2_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style 4_, particularly in emails (not a medium that + lends itself to footnotes). + + _1. That is, little bits of referenced text at the + bottom of the page. + _2. Because Terry himself does, of course 3_. + _3. Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + _4. Presumably because it detracts from linear + reading of the text - this is, of course, the point. + + I think I don't, in practice, mind the targets too much (the use + of a dot after the number helps a lot here), but I do have a + problem with the body text, in that I don't naturally separate out + the footnotes as different than the rest of the text - instead I + keep wondering why there are numbers interspered in the text. The + use of brackets around the numbers ([ and ]) made me somehow parse + the footnote references as "odd" - i.e., not part of the body text + - and thus both easier to skip, and also (paradoxically) easier to + pick out so that I could follow them. + + Thus, for the moment (and as always susceptable to argument), I'd + say -1 on the new form of footnote reference (i.e., I much prefer + the existing ``[1]_`` over the proposed ``1_``), and ambivalent + over the proposed target change. + + That leaves David's problem of wanting to distinguish footnotes + and citations - and the only thing I can propose there is that + footnotes are numeric or # and citations are not (which, as a + human being, I can probably cope with!). + +From a reply by Paul Moore on 2002-03-01: + + I think the current footnote syntax ``[1]_`` is *exactly* the + right balance of distinctness vs unobtrusiveness. I very + definitely don't think this should change. + + On the target change, it doesn't matter much to me. + +From a further reply by Tony Ibbs on 2002-03-01, referring to the +"[1]" form and actual usage in email: + + Clearly this is a form people are used to, and thus we should + consider it strongly (in the same way that the usage of ``*..*`` + to mean emphasis was taken partly from email practise). + + Equally clearly, there is something "magical" for people in the + use of a similar form (i.e., ``[1]``) for both footnote reference + and footnote target - it seems natural to keep them similar. + + ... + + I think that this established plaintext usage leads me to strongly + believe we should retain square brackets at both ends of a + footnote. The markup of the reference end (a single trailing + underscore) seems about as minimal as we can get away with. The + markup of the target end depends on how one envisages the thing - + if ".." means "I am a target" (as I tend to see it), then that's + good, but one can also argue that the "_[1]" syntax has a neat + symmetry with the footnote reference itself, if one wishes (in + which case ".." presumably means "hidden/special" as David seems + to think, which is why one needs a ".." *and* a leading underline + for hyperlink targets. + +Given the persuading arguments voiced, we'll leave footnote & footnote +reference syntax alone. Except that these discussions gave rise to +the "auto-symbol footnote" concept, which has been added. Citations +and citation references have also been added. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt new file mode 100644 index 000000000..f366bdf3f --- /dev/null +++ b/docs/dev/rst/problems.txt @@ -0,0 +1,761 @@ +============================== + Problems With StructuredText +============================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +There are several problems, unresolved issues, and areas of +controversy within StructuredText_ (Classic and Next Generation). In +order to resolve all these issues, this analysis brings all of the +issues out into the open, enumerates all the alternatives, and +proposes solutions to be incorporated into the reStructuredText_ +specification. + + +.. contents:: + + +Formal Specification +==================== + +The description in the original StructuredText.py has been criticized +for being vague. For practical purposes, "the code *is* the spec." +Tony Ibbs has been working on deducing a `detailed description`_ from +the documentation and code of StructuredTextNG_. Edward Loper's +STMinus_ is another attempt to formalize a spec. + +For this kind of a project, the specification should always precede +the code. Otherwise, the markup is a moving target which can never be +adopted as a standard. Of course, a specification may be revised +during lifetime of the code, but without a spec there is no visible +control and thus no confidence. + + +Understanding and Extending the Code +==================================== + +The original StructuredText_ is a dense mass of sparsely commented +code and inscrutable regular expressions. It was not designed to be +extended and is very difficult to understand. StructuredTextNG_ has +been designed to allow input (syntax) and output extensions, but its +documentation (both internal [comments & docstrings], and external) is +inadequate for the complexity of the code itself. + +For reStructuredText to become truly useful, perhaps even part of +Python's standard library, it must have clear, understandable +documentation and implementation code. For the implementation of +reStructuredText to be taken seriously, it must be a sterling example +of the potential of docstrings; the implementation must practice what +the specification preaches. + + +Section Structure via Indentation +================================= + +Setext_ required that body text be indented by 2 spaces. The original +StructuredText_ and StructuredTextNG_ require that section structure +be indicated through indentation, as "inspired by Python". For +certain structures with a very limited, local extent (such as lists, +block quotes, and literal blocks), indentation naturally indicates +structure or hierarchy. For sections (which may have a very large +extent), structure via indentation is unnecessary, unnatural and +ambiguous. Rather, the syntax of the section title *itself* should +indicate that it is a section title. + +The original StructuredText states that "A single-line paragraph whose +immediately succeeding paragraphs are lower level is treated as a +header." Requiring indentation in this way is: + +- Unnecessary. The vast majority of docstrings and standalone + documents will have no more than one level of section structure. + Requiring indentation for such docstrings is unnecessary and + irritating. + +- Unnatural. Most published works use title style (type size, face, + weight, and position) and/or section/subsection numbering rather + than indentation to indicate hierarchy. This is a tradition with a + very long history. + +- Ambiguous. A StructuredText header is indistinguishable from a + one-line paragraph followed by a block quote (precluding the use of + block quotes). Enumerated section titles are ambiguous (is it a + header? is it a list item?). Some additional adornment must be + required to confirm the line's role as a title, both to a parser and + to the human reader of the source text. + +Python's use of significant whitespace is a wonderful (if not +original) innovation, however requiring indentation in ordinary +written text is hypergeneralization. + +reStructuredText_ indicates section structure through title adornment +style (as exemplified by this document). This is far more natural. +In fact, it is already in widespread use in plain text documents, +including in Python's standard distribution (such as the toplevel +README_ file). + + +Character Escaping Mechanism +============================ + +No matter what characters are chosen for markup, some day someone will +want to write documentation *about* that markup or using markup +characters in a non-markup context. Therefore, any complete markup +language must have an escaping or encoding mechanism. For a +lightweight markup system, encoding mechanisms like SGML/XML's '*' +are out. So an escaping mechanism is in. However, with carefully +chosen markup, it should be necessary to use the escaping mechanism +only infrequently. + +reStructuredText_ needs an escaping mechanism: a way to treat +markup-significant characters as the characters themselves. Currently +there is no such mechanism (although ZWiki uses '!'). What are the +candidates? + +1. ``!`` (http://dev.zope.org/Members/jim/StructuredTextWiki/NGEscaping) +2. ``\`` +3. ``~`` +4. doubling of characters + +The best choice for this is the backslash (``\``). It's "the single +most popular escaping character in the world!", therefore familiar and +unsurprising. Since characters only need to be escaped under special +circumstances, which are typically those explaining technical +programming issues, the use of the backslash is natural and +understandable. Python docstrings can be raw (prefixed with an 'r', +as in 'r""'), which would obviate the need for gratuitous doubling-up +of backslashes. + +(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash +escapes, saying, "'nuff said. Backslash it is." Although neither +legally binding nor irrevocable nor any kind of guarantee of anything, +it is a good sign.) + +The rule would be: An unescaped backslash followed by any markup +character escapes the character. The escaped character represents the +character itself, and is prevented from playing a role in any markup +interpretation. The backslash is removed from the output. A literal +backslash is represented by an "escaped backslash," two backslashes in +a row. + +A carefully constructed set of recognition rules for inline markup +will obviate the need for backslash-escapes in almost all cases; see +`Delimitation of Inline Markup`_ below. + +When an expression (requiring backslashes and other characters used +for markup) becomes too complicated and therefore unreadable, a +literal block may be used instead. Inside literal blocks, no markup +is recognized, therefore backslashes (for the purpose of escaping +markup) become unnecessary. + +We could allow backslashes preceding non-markup characters to remain +in the output. This would make describing regular expressions and +other uses of backslashes easier. However, this would complicate the +markup rules and would be confusing. + + +Blank Lines in Lists +==================== + +Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13) +is the ability to write lists without requiring blank lines between +items. In docstrings, space is at a premium. Authors want to convey +their API or usage information in as compact a form as possible. +StructuredText_ requires blank lines between all body elements, +including list items, even when boundaries are obvious from the markup +itself. + +In reStructuredText, blank lines are optional between list items. +However, in order to eliminate ambiguity, a blank line is required +before the first list item and after the last. Nested lists also +require blank lines before the list start and after the list end. + + +Bullet List Markup +================== + +StructuredText_ includes 'o' as a bullet character. This is dangerous +and counter to the language-independent nature of the markup. There +are many languages in which 'o' is a word. For example, in Spanish:: + + Llamame a la casa + o al trabajo. + + (Call me at home or at work.) + +And in Japanese (when romanized):: + + Senshuu no doyoubi ni tegami + o kakimashita. + + ([I] wrote a letter on Saturday last week.) + +If a paragraph containing an 'o' word wraps such that the 'o' is the +first text on a line, or if a paragraph begins with such a word, it +could be misinterpreted as a bullet list. + +In reStructuredText_, 'o' is not used as a bullet character. '-', +'*', and '+' are the possible bullet characters. + + +Enumerated List Markup +====================== + +StructuredText enumerated lists are allowed to begin with numbers and +letters followed by a period or right-parenthesis, then whitespace. +This has surprising consequences for writing styles. For example, +this is recognized as an enumerated list item by StructuredText:: + + Mr. Creosote. + +People will write enumerated lists in all different ways. It is folly +to try to come up with the "perfect" format for an enumerated list, +and limit the docstring parser's recognition to that one format only. + +Rather, the parser should recognize a variety of enumerator styles, +marking each block as a potential enumerated list item (PELI), and +interpret the enumerators of adjacent PELIs to decide whether they +make up a consistent enumerated list. + +If a PELI is labeled with a "1.", and is immediately followed by a +PELI labeled with a "2.", we've got an enumerated list. Or "(A)" +followed by "(B)". Or "i)" followed by "ii)", etc. The chances of +accidentally recognizing two adjacent and consistently labeled PELIs, +are acceptably small. + +For an enumerated list to be recognized, the following must be true: + +- the list must consist of multiple adjacent list items (2 or more) +- the enumerators must all have the same format +- the enumerators must be sequential + +It is also recommended that the enumerator of the first list item be +ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be +able to begin a list at an arbitrary enumeration. + + +Definition List Markup +====================== + +StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on +the first line of a paragraph to indicate a definition list item. The +' -- ' serves to separate the term (on the left) from the definition +(on the right). + +Many people use ' -- ' as an em-dash in their text, conflicting with +the StructuredText usage. Although the Chicago Manual of Style says +that spaces should not be used around an em-dash, Peter Funk pointed +out that this is standard usage in German (according to the Duden, the +official German reference), and possibly in other languages as well. +The widespread use of ' -- ' precludes its use for definition lists; +it would violate the "unsurprising" criterion. + +A simpler, and at least equally visually distinctive construct +(proposed by Guido van Rossum, who incidentally is a frequent user of +' -- ') would do just as well:: + + term 1 + Definition. + + term 2 + Definition 2, paragraph 1. + + Definition 2, paragraph 2. + +A reStructuredText definition list item consists of a term and a +definition. A term is a simple one-line paragraph. A definition is a +block indented relative to the term, and may contain multiple +paragraphs and other body elements. No blank line precedes a +definition (this distinguishes definition lists from block quotes). + + +Literal Blocks +============== +The StructuredText_ specification has literal blocks indicated by +'example', 'examples', or '::' ending the preceding paragraph. STNG +only recognizes '::'; 'example'/'examples' are not implemented. This +is good; it fixes an unnecessary language dependency. The problem is +what to do with the sometimes- unwanted '::'. + +In reStructuredText_ '::' at the end of a paragraph indicates that +subsequent *indented* blocks are treated as literal text. No further +markup interpretation is done within literal blocks (not even +backslash-escapes). If the '::' is preceded by whitespace, '::' is +omitted from the output; if '::' was the sole content of a paragraph, +the entire paragraph is removed (no 'empty' paragraph remains). If +'::' is preceded by a non-whitespace character, '::' is replaced by +':' (i.e., the extra colon is removed). + +Thus, a section could begin with a literal block as follows:: + + Section Title + ------------- + + :: + + print "this is example literal" + + +Tables +====== + +The table markup scheme in classic StructuredText was horrible. Its +omission from StructuredTextNG is welcome, and its markup will not be +repeated here. However, tables themselves are useful in +documentation. Alternatives: + +1. This format is the most natural and obvious. It was independently + invented (no great feat of creation!), and later found to be the + format supported by the `Emacs table mode`_:: + + +------------+------------+------------+--------------+ + | Header 1 | Header 2 | Header 3 | Header 4 | + +============+============+============+==============+ + | Column 1 | Column 2 | Column 3 & 4 span (Row 1) | + +------------+------------+------------+--------------+ + | Column 1 & 2 span | Column 3 | - Column 4 | + +------------+------------+------------+ - Row 2 & 3 | + | 1 | 2 | 3 | - span | + +------------+------------+------------+--------------+ + + Tables are described with a visual outline made up of the + characters '-', '=', '|', and '+': + + - The hyphen ('-') is used for horizontal lines (row separators). + - The equals sign ('=') is optionally used as a header separator + (as of version 1.5.24, this is not supported by the Emacs table + mode). + - The vertical bar ('|') is used for for vertical lines (column + separators). + - The plus sign ('+') is used for intersections of horizontal and + vertical lines. + + Row and column spans are possible simply by omitting the column or + row separators, respectively. The header row separator must be + complete; in other words, a header cell may not span into the table + body. Each cell contains body elements, and may have multiple + paragraphs, lists, etc. Initial spaces for a left margin are + allowed; the first line of text in a cell determines its left + margin. + +2. Below is a minimalist possibility. It may be better suited to + manual input than alternative #1, but there is no Emacs editing + mode available. One disadvantage is that it resembles section + titles; a one-column table would look exactly like section & + subsection titles. :: + + ============ ============ ============ ============== + Header 1 Header 2 Header 3 Header 4 + ============ ============ ============ ============== + Column 1 Column 2 Column 3 & 4 span (Row 1) + ------------ ------------ --------------------------- + Column 1 & 2 span Column 3 - Column 4 + ------------------------- ------------ - Row 2 & 3 + 1 2 3 - span + ============ ============ ============ ============== + + The table begins with a top border of equals signs with a space at + each column boundary (regardless of spans). Each row is + underlined. Internal row separators are underlines of '-', with + spaces at column boundaries. The last of the optional head rows is + underlined with '=', again with spaces at column boundaries. + Column spans have no spaces in their underline. Row spans simply + lack an underline at the row boundary. The bottom boundary of the + table consists of '=' underlines. A blank line is required + following a table. + +Alternative #1 is the choice adopted by reStructuredText. + + +Delimitation of Inline Markup +============================= + +StructuredText specifies that inline markup must begin with +whitespace, precluding such constructs as parenthesized or quoted +emphatic text:: + + "**What?**" she cried. (*exit stage left*) + +The `reStructuredText markup specification`_ allows for such +constructs and disambiguates inline markup through a set of +recognition rules. These recognition rules define the context of +markup start-strings and end-strings, allowing markup characters to be +used in most non-markup contexts without a problem (or a backslash). +So we can say, "Use asterisks (*) around words or phrases to +*emphasisze* them." The '(*)' will not be recognized as markup. This +reduces the need for markup escaping to the point where an escape +character is *almost* (but not quite!) unnecessary. + + +Underlining +=========== + +StructuredText uses '_text_' to indicate underlining. To quote David +Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring +grammar: a very revised proposal": + + The tagging of underlined text with _'s is suboptimal. Underlines + shouldn't be used from a typographic perspective (underlines were + designed to be used in manuscripts to communicate to the + typesetter that the text should be italicized -- no well-typeset + book ever uses underlines), and conflict with double-underscored + Python variable names (__init__ and the like), which would get + truncated and underlined when that effect is not desired. Note + that while *complete* markup would prevent that truncation + ('__init__'), I think of docstring markups much like I think of + type annotations -- they should be optional and above all do no + harm. In this case the underline markup does harm. + +Underlining is not part of the reStructuredText specification. + + +Inline Literals +=============== + +StructuredText's markup for inline literals (text left as-is, +verbatim, usually in a monospaced font; as in HTML ) is single +quotes ('literals'). The problem with single quotes is that they are +too often used for other purposes: + +- Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'."; + +- Quoting text: + + First Bruce: "Well Bruce, I heard the prime minister use it. + 'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he + said, and she smiled quietly to herself." + + In the UK, single quotes are used for dialogue in published works. + +- String literals: s = '' + +Alternatives:: + + 'text' \'text\' ''text'' "text" \"text\" ""text"" + #text# @text@ `text` ^text^ ``text'' ``text`` + +The examples below contain inline literals, quoted text, and +apostrophes. Each example should evaluate to the following HTML:: + + Some code, with a 'quote', "double", ain't it grand? + Does a[b] = 'c' + "d" + `2^3` work? + + 0. Some code, with a quote, double, ain't it grand? + Does a[b] = 'c' + "d" + `2^3` work? + 1. Some 'code', with a \'quote\', "double", ain\'t it grand? + Does 'a[b] = \'c\' + "d" + `2^3`' work? + 2. Some \'code\', with a 'quote', "double", ain't it grand? + Does \'a[b] = 'c' + "d" + `2^3`\' work? + 3. Some ''code'', with a 'quote', "double", ain't it grand? + Does ''a[b] = 'c' + "d" + `2^3`'' work? + 4. Some "code", with a 'quote', \"double\", ain't it grand? + Does "a[b] = 'c' + "d" + `2^3`" work? + 5. Some \"code\", with a 'quote', "double", ain't it grand? + Does \"a[b] = 'c' + "d" + `2^3`\" work? + 6. Some ""code"", with a 'quote', "double", ain't it grand? + Does ""a[b] = 'c' + "d" + `2^3`"" work? + 7. Some #code#, with a 'quote', "double", ain't it grand? + Does #a[b] = 'c' + "d" + `2^3`# work? + 8. Some @code@, with a 'quote', "double", ain't it grand? + Does @a[b] = 'c' + "d" + `2^3`@ work? + 9. Some `code`, with a 'quote', "double", ain't it grand? + Does `a[b] = 'c' + "d" + \`2^3\`` work? + 10. Some ^code^, with a 'quote', "double", ain't it grand? + Does ^a[b] = 'c' + "d" + `2\^3`^ work? + 11. Some ``code'', with a 'quote', "double", ain't it grand? + Does ``a[b] = 'c' + "d" + `2^3`'' work? + 12. Some ``code``, with a 'quote', "double", ain't it grand? + Does ``a[b] = 'c' + "d" + `2^3\``` work? + +Backquotes (#9 & #12) are the best choice. They are unobtrusive and +relatviely rarely used (more rarely than ' or ", anyhow). Backquotes +have the connotation of 'quotes', which other options (like carets, +#10) don't. + +Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12) +could be used for inline literals. If single-backquotes are used for +'interpreted text' (context-sensitive domain-specific descriptive +markup) such as function name hyperlinks in Python docstrings, then +double-backquotes could be used for absolute-literals, wherein no +processing whatsoever takes place. An advantage of double-backquotes +would be that backslash-escaping would no longer be necessary for +embedded single-backquotes; however, embedded double-backquotes (in an +end-string context) would be illegal. See `Backquotes in +Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__. + +__ alternatives.html#backquotes-in-phrase-links +__ alternatives.html + +Alternative choices are carets (#10) and TeX-style quotes (#11). For +examples of TeX-style quoting, see +http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor. + +Some existing uses of backquotes: + +1. As a synonym for repr() in Python. +2. For command-interpolation in shell scripts. +3. Used as open-quotes in TeX code (and carried over into plaintext + by TeXies). + +The inline markup start-string and end-string recognition rules +defined by the `reStructuredText markup specification`_ would allow +all of these cases inside inline literals, with very few exceptions. +As a fallback, literal blocks could handle all cases. + +Outside of inline literals, the above uses of backquotes would require +backslash-escaping. However, these are all prime examples of text +that should be marked up with inline literals. + +If either backquotes or straight single-quotes are used as markup, +TeX-quotes are too troublesome to support, so no special-casing of +TeX-quotes should be done (at least at first). If TeX-quotes have to +be used outside of literals, a single backslash-escaped would suffice: +\``TeX quote''. Ugly, true, but very infrequently used. + +Using literal blocks is a fallback option which removes the need for +backslash-escaping:: + + like this:: + + Here, we can do ``absolutely'' anything `'`'\|/|\ we like! + +No mechanism for inline literals is perfect, just as no escaping +mechanism is perfect. No matter what we use, complicated inline +expressions involving the inline literal quote and/or the backslash +will end up looking ugly. We can only choose the least often ugly +option. + +reStructuredText will use double backquotes for inline literals, and +single backqoutes for interpreted text. + + +Hyperlinks +========== + +There are three forms of hyperlink currently in StructuredText_: + +1. (Absolute & relative URIs.) Text enclosed by double quotes + followed by a colon, a URI, and concluded by punctuation plus white + space, or just white space, is treated as a hyperlink:: + + "Python":http://www.python.org/ + +2. (Absolute URIs only.) Text enclosed by double quotes followed by a + comma, one or more spaces, an absolute URI and concluded by + punctuation plus white space, or just white space, is treated as a + hyperlink:: + + "mail me", mailto:me@mail.com + +3. (Endnotes.) Text enclosed by brackets link to an endnote at the + end of the document: at the beginning of the line, two dots, a + space, and the same text in brackets, followed by the end note + itself:: + + Please refer to the fine manual [GVR2001]. + + .. [GVR2001] Python Documentation, Release 2.1, van Rossum, + Drake, et al., http://www.python.org/doc/ + +The problem with forms 1 and 2 is that they are neither intuitive nor +unobtrusive (they break design goals 5 & 2). They overload +double-quotes, which are too often used in ordinary text (potentially +breaking design goal 4). The brackets in form 3 are also too common +in ordinary text (such as [nested] asides and Python lists like [12]). + +Alternatives: + +1. Have no special markup for hyperlinks. + +2. A. Interpret and mark up hyperlinks as any contiguous text + containing '://' or ':...@' (absolute URI) or '@' (email + address) after an alphanumeric word. To de-emphasize the URI, + simply enclose it in parentheses: + + Python (http://www.python.org/) + + B. Leave special hyperlink markup as a domain-specific extension. + Hyperlinks in ordinary reStructuredText documents would be + required to be standalone (i.e. the URI text inline in the + document text). Processed hyperlinks (where the URI text is + hidden behind the link) are important enough to warrant syntax. + +3. The original Setext_ introduced a mechanism of indirect hyperlinks. + A source link word ('hot word') in the text was given a trailing + underscore:: + + Here is some text with a hyperlink_ built in. + + The hyperlink itself appeared at the end of the document on a line + by itself, beginning with two dots, a space, the link word with a + leading underscore, whitespace, and the URI itself:: + + .. _hyperlink http://www.123.xyz + + Setext used ``underscores_instead_of_spaces_`` for phrase links. + +With some modification, alternative 3 best satisfies the design goals. +It has the advantage of being readable and relatively unobtrusive. +Since each source link must match up to a target, the odd variable +ending in an underscore can be spared being marked up (although it +should generate a "no such link target" warning). The only +disadvantage is that phrase-links aren't possible without some +obtrusive syntax. + +We could achieve phrase-links if we enclose the link text: + +1. in double quotes:: + + "like this"_ + +2. in brackets:: + + [like this]_ + +3. or in backquotes:: + + `like this`_ + +Each gives us somewhat obtrusive markup, but that is unavoidable. The +bracketed syntax (#2) is reminiscent of links on many web pages +(intuitive), although it is somewhat obtrusive. Alternative #3 is +much less obtrusive, and is consistent with interpreted text: the +trailing underscore indicates the interpretation of the phrase, as a +hyperlink. #3 also disambiguates hyperlinks from footnote references. +Alternative #3 wins. + +The same trailing underscore markup can also be used for footnote and +citation references, removing the problem with ordinary bracketed text +and Python lists:: + + Please refer to the fine manual [GVR2000]_. + + .. [GVR2000] Python Documentation, van Rossum, Drake, et al., + http://www.python.org/doc/ + +The two-dots-and-a-space syntax was generalized by Setext for +comments, which are removed from the (visible) processed output. +reStructuredText uses this syntax for comments, footnotes, and link +target, collectively termed "explicit markup". For link targets, in +order to eliminate ambiguity with comments and footnotes, +reStructuredText specifies that a colon always follow the link target +word/phrase. The colon denotes 'maps to'. There is no reason to +restrict target links to the end of the document; they could just as +easily be interspersed. + +Internal hyperlinks (links from one point to another within a single +document) can be expressed by a source link as before, and a target +link with a colon but no URI. In effect, these targets 'map to' the +element immediately following. + +As an added bonus, we now have a perfect candidate for +reStructuredText directives, a simple extension mechanism: explicit +markup containing a single word followed by two colons and whitespace. +The interpretation of subsequent data on the directive line or +following is directive-dependent. + +To summarize:: + + .. This is a comment. + + .. The line below is an example of a directive. + .. version:: 1 + + This is a footnote [1]_. + + This internal hyperlink will take us to the footnotes_ area below. + + Here is a one-word_ external hyperlink. + + Here is `a hyperlink phrase`_. + + .. _footnotes: + .. [1] Footnote text goes here. + + .. external hyperlink target mappings: + .. _one-word: http://www.123.xyz + .. _a hyperlink phrase: http://www.123.xyz + +The presence or absence of a colon after the target link +differentiates an indirect hyperlink from a footnote, respectively. A +footnote requires brackets. Backquotes around a target link word or +phrase are required if the phrase contains a colon, optional +otherwise. + +Below are examples using no markup, the two StructuredText hypertext +styles, and the reStructuredText hypertext style. Each example +contains an indirect link, a direct link, a footnote/endnote, and +bracketed text. In HTML, each example should evaluate to:: + +

A URI, see + [eggs2000] (in Bacon [Publisher]). Also see + http://eggs.org.

+ +

[eggs2000] "Spam, Spam, Spam, Eggs, + Bacon, and Spam"

+ +1. No markup:: + + A URI http://spam.org, see eggs2000 (in Bacon [Publisher]). + Also see http://eggs.org. + + eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam" + +2. StructuredText absolute/relative URI syntax + ("text":http://www.url.org):: + + A "URI":http://spam.org, see [eggs2000] (in Bacon [Publisher]). + Also see "http://eggs.org":http://eggs.org. + + .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" + + Note that StructuredText does not recognize standalone URIs, + forcing doubling up as shown in the second line of the example + above. + +3. StructuredText absolute-only URI syntax + ("text", mailto:you@your.com):: + + A "URI", http://spam.org, see [eggs2000] (in Bacon + [Publisher]). Also see "http://eggs.org", http://eggs.org. + + .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" + +4. reStructuredText syntax:: + + 4. A URI_, see [eggs2000]_ (in Bacon [Publisher]). + Also see http://eggs.org. + + .. _URI: http:/spam.org + .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" + +The bracketed text '[Publisher]' may be problematic with +StructuredText (syntax 2 & 3). + +reStructuredText's syntax (#4) is definitely the most readable. The +text is separated from the link URI and the footnote, resulting in +cleanly readable text. + +.. _StructuredText: + http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage +.. _Setext: http://docutils.sourceforge.net/mirror/setext.html +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _detailed description: + http://www.tibsnjoan.demon.co.uk/STNG-format.html +.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html +.. _StructuredTextNG: + http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG +.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/ + python/python/dist/src/README +.. _Emacs table mode: http://table.sourceforge.net/ +.. _reStructuredText Markup Specification: reStructuredText.html + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt new file mode 100644 index 000000000..311751f37 --- /dev/null +++ b/docs/dev/todo.txt @@ -0,0 +1,385 @@ +================ + Docutils Notes +================ +:Date: $Date$ +:Revision: $Revision$ + +.. contents:: + +To Do +===== + +General +------- + +- Document! + + - Internal module documentation. + + - User docs. + + - Doctree nodes (DTD element) semantics: + + - External (public) attributes (node.attributes). + - Internal attributes (node.*). + - Linking mechanism. + +- Refactor + + - Rename methods & variables according to the `coding conventions`_ + below. + + - The name->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. + +- Add validation? See http://pytrex.sourceforge.net, RELAX NG. + +- 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. + +- Provide a mechanism to pass options to Readers, Writers, and Parsers + through docutils.core.publish/Publisher? Or create custom + Reader/Writer/Parser objects first, and pass *them* to + publish/Publisher? + +- In reader.get_reader_class (& parser & writer 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->id mapping file? This could be stored + permanently, read by subsequent processing runs, and updated with + new entries. ("Persistent ID mapping"?) + +- The "Docutils System Messages" section appears even if no actual + system messages are there. They must be below the threshold. The + transform should be fixed. + +- TOC transform: use alt-text for inline images. + + +Specification +------------- + +- 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.]). + +- Rework PEP 257, separating style from spec from tools, wrt Docutils? + See Doc-SIG from 2001-06-19/20. + +- Add layout component to framework? Or part of the formatter? + +- Once doctree.txt is fleshed out, how about breaking (most of) it up + and putting it into nodes.py as docstrings? + + +reStructuredText Parser +----------------------- + +- Add motivation sections for constructs in spec. + +- 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? + +- Allow hyperlink references to targets in other documents? Not in an + HTML-centric way, though (it's trivial to say + ``http://www.whatever.com/doc#name``, and useless in non-HTML + contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG + 2001-08-10. + +- Add character processing? For example: + + - ``--`` -> em-dash (or ``--`` -> en-dash, and ``---`` -> em-dash). + (Look for pre-existing conventions.) + - Convert quotes to curly quote entities. (Essentially impossible + for HTML? Unnecessary for TeX. An output issue?) + - Various forms of ``:-)`` to smiley icons. + - ``"\ "`` ->  . + - Escaped newlines ->
. + - Escaped period or quote as a disappearing catalyst to allow + character-level inline markup? + - Others? + + How to represent character entities in the text though? Probably as + Unicode. + + Which component is responsible for this, the parser, the reader, or + the writer? + +- 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. + +- Alan Jaffray suggested (and I agree) that it would be sensible to: + + - have a directive to specify a default role for interpreted text + - allow the reST processor to take an argument for the default role + - issue a warning when processing documents with no default role + which contain interpreted text with no explicitly specified role + +- 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 syntax constructs to be added or disabled at run-time. + +- Make footnotes two-way, GNU-style? What if there are multiple + references to a single footnote? + +- Add RFC-2822 header parsing (for PEP, email Readers). + +- Change ``.. meta::`` to use a "pending" element, only activated for + HTML writers. + +- 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. + + See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's + "Structuring: a summary; and an attempt at EBNF", item 4. + +- Produce a better system message when a list ends abruptly. Input:: + + -1 Option "1" + -2 + + Produces:: + + Reporter: WARNING (2) Unindent without blank line at line 2. + + But it should produce:: + + Reporter: WARNING (2) List ends without blank line at line 2. + + +Directives +`````````` + +- Allow directives to be added at run-time. + +- Use the language module for directive attribute names? + +- Add more attributes to the image directive: align, border? + +- Implement directives: + + - html.imagemap + + - components.endnotes, .citations, .topic, .sectnum (section + numbering; add support to .contents; could be cmdline option also) + + - misc.raw + + - misc.include: ``#include`` one file in another. But how to + parse wrt sections, reference names, conflicts? + + - misc.exec: Execute Python code & insert the results. Perhaps + dangerous? + + - misc.eval: Evaluate an expression & insert the text. At parse + time or at substitution time? + + - block.qa: Questions & Answers. Implement as a generic two-column + marked list? Or as a standalone construct? + + - block.columns: Multi-column table/list, with number of columns as + argument. + + - block.verse: Paragraphs with linebreaks preserved. A directive + would be easy; what about a literal-block-like prefix, perhaps + ';;'? E.g.:: + + Take it away, Eric the orchestra leader! ;; + + Half a bee, + Philosophically, + Must ipso-facto + Half not be. + You see? + + ... + + - 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? + + - text.date: Datestamp. For substitutions. + + - Combined with misc.include, implement canned macros? + + +Unimplemented Transforms +------------------------ + +- Footnote Gathering + + Collect and move footnotes to the end of a document. + +- 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. References will + have to be adjusted. + + (HTML only?) + +- Navigation + + If a document is split up, each segment will need navigation links: + parent, children (small TOC), previous (preorder), next (preorder). + +- Index + + +HTML Writer +----------- + +- Considerations for an HTML Writer [#]_: + + - Boolean attributes. ```` is good, ```` is bad. Use a special value in attribute + mappings, such as ``None``? + + - Escape double-dashes inside comments. + + - Put the language code into an appropriate element's LANG + attribute (?). + + - Docutils identifiers (the "class" and "id" attributes) will + conform to the regular expression ``[a-z][-a-z0-9]*``. See + ``docutils.utils.id()``. + + .. _HTML 4.01 spec: http://www.w3.org/TR/html401 + .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 + .. [#] Source: `HTML 4.0 in Netscape and Explorer`__. + __ http://www.webreference.com/dev/html4nsie/index.html + +- Allow for style sheet info to be passed in, either as a , or + as embedded style info. + +- Construct a templating system, as in ht2html/yaptu, using directives + and substitutions for dynamic stuff. + +- Improve the granularity of document parts in the HTML writer, so + that one could just grab the parts needed. + + +Coding Conventions +================== + +This project shall follow the generic coding conventions as specified +in the `Style Guide for Python Code`__ and `Docstring Conventions`__ +PEPs, with the following clarifications: + +- 4 spaces per indentation level. No tabs. +- 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 or 79 characters long. +- "CamelCase" shall be used for class names. +- Use "lowercase" or "lowercase_with_underscores" for function, + method, and variable names. For short names, maximum two joined + words, use lowercase (e.g. 'tagname'). For long names with three or + more joined words, or where it's hard to parse the split between two + words, use lowercase_with_underscores (e.g., 'note_explicit_target', + 'explicit_target'). + +__ http://www.python.org/peps/pep-0008.html +__ http://www.python.org/peps/pep-0257.html + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt new file mode 100644 index 000000000..92c8e7f61 --- /dev/null +++ b/docs/peps/pep-0256.txt @@ -0,0 +1,253 @@ +PEP: 256 +Title: Docstring Processing System Framework +Version: $Revision$ +Last-Modified: $Date$ +Author: goodger@users.sourceforge.net (David Goodger) +Discussions-To: doc-sig@python.org +Status: Draft +Type: Standards Track +Created: 01-Jun-2001 +Post-History: 13-Jun-2001 + + +Abstract + + Python lends itself to inline documentation. With its built-in + docstring syntax, a limited form of Literate Programming [1]_ is + easy to do in Python. However, there are no satisfactory standard + tools for extracting and processing Python docstrings. The lack + of a standard toolset is a significant gap in Python's + infrastructure; this PEP aims to fill the gap. + + The issues surrounding docstring processing have been contentious + and difficult to resolve. This PEP proposes a generic Docstring + Processing System (DPS) framework, which separates out the + components (program and conceptual), enabling the resolution of + individual issues either through consensus (one solution) or + through divergence (many). It promotes standard interfaces which + will allow a variety of plug-in components (input context readers, + markup parsers, and output format writers) to be used. + + The concepts of a DPS framework are presented independently of + implementation details. + + +Rationale + + There are standard inline documentation systems for some other + languages. For example, Perl has POD [2]_ and Java has Javadoc + [3]_, but neither of these mesh with the Pythonic way. POD syntax + is very explicit, but takes after Perl in terms of readability. + Javadoc is HTML-centric; except for '@field' tags, raw HTML is + used for markup. There are also general tools such as Autoduck + [4]_ and Web (Tangle & Weave) [5]_, useful for multiple languages. + + There have been many attempts to write auto-documentation systems + for Python (not an exhaustive list): + + - Marc-Andre Lemburg's doc.py [6]_ + + - Daniel Larsson's pythondoc & gendoc [7]_ + + - Doug Hellmann's HappyDoc [8]_ + + - Laurence Tratt's Crystal [9]_ + + - Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the + Python standard library; see below) + + - Tony Ibbs' docutils [11]_ + + - Edward Loper's STminus formalization and related efforts [12]_ + + These systems, each with different goals, have had varying degrees + of success. A problem with many of the above systems was + over-ambition combined with inflexibility. They provided a + self-contained set of components: a docstring extraction system, + a markup parser, an internal processing system and one or more + output format writers. Inevitably, one or more aspects of each + system had serious shortcomings, and they were not easily extended + or modified, preventing them from being adopted as standard tools. + + It has become clear (to this author, at least) that the "all or + nothing" approach cannot succeed, since no monolithic + self-contained system could possibly be agreed upon by all + interested parties. A modular component approach designed for + extension, where components may be multiply implemented, may be + the only chance for success. By separating out the issues, we can + form consensus more easily (smaller fights ;-), and accept + divergence more readily. + + Each of the components of a docstring processing system should be + developed independently. A 'best of breed' system should be + chosen, either merged from existing systems, and/or developed + anew. This system should be included in Python's standard + library. + + +PyDoc & Other Existing Systems + + PyDoc became part of the Python standard library as of release + 2.1. It extracts and displays docstrings from within the Python + interactive interpreter, from the shell command line, and from a + GUI window into a web browser (HTML). Although a very useful + tool, PyDoc has several deficiencies, including: + + - In the case of the GUI/HTML, except for some heuristic + hyperlinking of identifier names, no formatting of the + docstrings is done. They are presented within

+ tags to avoid unwanted line wrapping. Unfortunately, the result + is not attractive. + + - PyDoc extracts docstrings and structural information (class + identifiers, method signatures, etc.) from imported module + objects. There are security issues involved with importing + untrusted code. Also, information from the source is lost when + importing, such as comments, "additional docstrings" (string + literals in non-docstring contexts; see PEP 258 [13]_), and the + order of definitions. + + The functionality proposed in this PEP could be added to or used + by PyDoc when serving HTML pages. The proposed docstring + processing system's functionality is much more than PyDoc needs in + its current form. Either an independent tool will be developed + (which PyDoc may or may not use), or PyDoc could be expanded to + encompass this functionality and *become* the docstring processing + system (or one such system). That decision is beyond the scope of + this PEP. + + Similarly for other existing docstring processing systems, their + authors may or may not choose compatibility with this framework. + However, if this framework is accepted and adopted as the Python + standard, compatibility will become an important consideration in + these systems' future. + + +Specification + + The docstring processing system framework consists of components, + as follows:: + + 1. Docstring conventions. Documents issues such as: + + - What should be documented where. + + - First line is a one-line synopsis. + + PEP 257, Docstring Conventions [14]_, documents some of these + issues. + + 2. Docstring processing system design specification. Documents + issues such as: + + - High-level spec: what a DPS does. + + - Command-line interface for executable script. + + - System Python API. + + - Docstring extraction rules. + + - Readers, which encapsulate the input context . + + - Parsers. + + - Document tree: the intermediate internal data structure. The + output of the Parser and Reader, and the input to the Writer + all share the same data structure. + + - Transforms, which modify the document tree. + + - Writers for output formats. + + - Distributors, which handle output management (one file, many + files, or objects in memory). + + These issues are applicable to any docstring processing system + implementation. PEP 258, Docutils Design Specification [13 ]_, + documents these issues. + + 3. Docstring processing system implementation. + + 4. Input markup specifications: docstring syntax. PEP 2xx, + reStructuredText Standard Docstring Format [15]_, proposes a + standard syntax. + + 5. Input parser implementations. + + 6. Input context readers ("modes": Python source code, PEP, + standalone text file, email, etc.) and implementations. + + 7. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer + implementations. + + Components 1, 2/3, and 4/5 are the subject of individual companion + PEPs. If there is another implementation of the framework or + syntax/parser, additional PEPs may be required. Multiple + implementations of each of components 6 and 7 will be required; + the PEP mechanism may be overkill for these components. + + +Project Web Site + + A SourceForge project has been set up for this work at + http://docutils.sourceforge.net/. + + +References and Footnotes + + [1] http://www.literateprogramming.com/ + + [2] Perl "Plain Old Documentation" + http://www.perldoc.com/perl5.6/pod/perlpod.html + + [3] http://java.sun.com/j2se/javadoc/ + + [4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm + + [5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html + + [6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py + + [7] http://starship.python.net/crew/danilo/pythondoc/ + + [8] http://happydoc.sourceforge.net/ + + [9] http://www.btinternet.com/~tratt/comp/python/crystal/ + + [10] http://www.python.org/doc/current/lib/module-pydoc.html + + [11] http://homepage.ntlworld.com/tibsnjoan/docutils/ + + [12] http://www.cis.upenn.edu/~edloper/pydoc/ + + [13] PEP 258, Docutils Design Specification, Goodger + http://www.python.org/peps/pep-0258.html + + [14] PEP 257, Docstring Conventions, Goodger, Van Rossum + http://www.python.org/peps/pep-0257.html + + [15] PEP 287, reStructuredText Standard Docstring Format, Goodger + http://www.python.org/peps/pep-0287.html + + [16] http://www.python.org/sigs/doc-sig/ + + +Copyright + + This document has been placed in the public domain. + + +Acknowledgements + + This document borrows ideas from the archives of the Python + Doc-SIG [16]_. Thanks to all members past & present. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +fill-column: 70 +sentence-end-double-space: t +End: diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt new file mode 100644 index 000000000..48425d9cc --- /dev/null +++ b/docs/peps/pep-0257.txt @@ -0,0 +1,248 @@ +PEP: 257 +Title: Docstring Conventions +Version: $Revision$ +Last-Modified: $Date$ +Author: goodger@users.sourceforge.net (David Goodger), + guido@python.org (Guido van Rossum) +Discussions-To: doc-sig@python.org +Status: Active +Type: Informational +Created: 29-May-2001 +Post-History: 13-Jun-2001 + + +Abstract + + This PEP documents the semantics and conventions associated with + Python docstrings. + + +Rationale + + The aim of this PEP is to standardize the high-level structure of + docstrings: what they should contain, and how to say it (without + touching on any markup syntax within docstrings). The PEP + contains conventions, not laws or syntax. + + "A universal convention supplies all of maintainability, + clarity, consistency, and a foundation for good programming + habits too. What it doesn't do is insist that you follow it + against your will. That's Python!" + + --Tim Peters on comp.lang.python, 2001-06-16 + + If you violate the conventions, the worst you'll get is some dirty + looks. But some software (such as the Docutils docstring + processing system [1] [2]) will be aware of the conventions, so + following them will get you the best results. + + +Specification + + What is a Docstring? + -------------------- + + A docstring is a string literal that occurs as the first statement + in a module, function, class, or method definition. Such a + docstring becomes the __doc__ special attribute of that object. + + All modules should normally have docstrings, and all functions and + classes exported by a module should also have docstrings. Public + methods (including the __init__ constructor) should also have + docstrings. A package may be documented in the module docstring + of the __init__.py file in the package directory. + + String literals occurring elsewhere in Python code may also act as + documentation. They are not recognized by the Python bytecode + compiler and are not accessible as runtime object attributes + (i.e. not assigned to __doc__), but two types of extra docstrings + may be extracted by software tools: + + 1. String literals occurring immediately after a simple assignment + at the top level of a module, class, or __init__ method + are called "attribute docstrings". + + 2. String literals occurring immediately after another docstring + are called "additional docstrings". + + Please see PEP 258 "Docutils Design Specification" [2] for a + detailed description of attribute and additional docstrings. + + XXX Mention docstrings of 2.2 properties. + + For consistency, always use """triple double quotes""" around + docstrings. Use r"""raw triple double quotes""" if you use any + backslashes in your docstrings. For Unicode docstrings, use + u"""Unicode triple-quoted strings""". + + There are two forms of docstrings: one-liners and multi-line + docstrings. + + One-line Docstrings + -------------------- + + One-liners are for really obvious cases. They should really fit + on one line. For example:: + + def kos_root(): + """Return the pathname of the KOS root directory.""" + global _kos_root + if _kos_root: return _kos_root + ... + + Notes: + + - Triple quotes are used even though the string fits on one line. + This makes it easy to later expand it. + + - The closing quotes are on the same line as the opening quotes. + This looks better for one-liners. + + - There's no blank line either before or after the docstring. + + - The docstring is a phrase ending in a period. It prescribes the + function or method's effect as a command ("Do this", "Return + that"), not as a description: e.g. don't write "Returns the + pathname ..." + + - The one-line docstring should NOT be a "signature" reiterating + the function/method parameters (which can be obtained by + introspection). Don't do:: + + def function(a, b): + """function(a, b) -> list""" + + This type of docstring is only appropriate for C functions (such + as built-ins), where introspection is not possible. + + Multi-line Docstrings + ---------------------- + + Multi-line docstrings consist of a summary line just like a + one-line docstring, followed by a blank line, followed by a more + elaborate description. The summary line may be used by automatic + indexing tools; it is important that it fits on one line and is + separated from the rest of the docstring by a blank line. The + summary line may be on the same line as the opening quotes or on + the next line. + + The entire docstring is indented the same as the quotes at its + first line (see example below). Docstring processing tools will + strip an amount of indentation from the second and further lines + of the docstring equal to the indentation of the first non-blank + line after the first line of the docstring. Relative indentation + of later lines in the docstring is retained. + + Insert a blank line before and after all docstrings (one-line or + multi-line) that document a class -- generally speaking, the + class's methods are separated from each other by a single blank + line, and the docstring needs to be offset from the first method + by a blank line; for symmetry, put a blank line between the class + header and the docstring. Docstrings documenting functions or + methods generally don't have this requirement, unless the function + or method's body is written as a number of blank-line separated + sections -- in this case, treat the docstring as another section, + and precede it with a blank line. + + The docstring of a script (a stand-alone program) should be usable + as its "usage" message, printed when the script is invoked with + incorrect or missing arguments (or perhaps with a "-h" option, for + "help"). Such a docstring should document the script's function + and command line syntax, environment variables, and files. Usage + messages can be fairly elaborate (several screens full) and should + be sufficient for a new user to use the command properly, as well + as a complete quick reference to all options and arguments for the + sophisticated user. + + The docstring for a module should generally list the classes, + exceptions and functions (and any other objects) that are exported + by the module, with a one-line summary of each. (These summaries + generally give less detail than the summary line in the object's + docstring.) The docstring for a package (i.e., the docstring of + the package's __init__.py module) should also list the modules and + subpackages exported by the package. + + The docstring for a function or method should summarize its + behavior and document its arguments, return value(s), side + effects, exceptions raised, and restrictions on when it can be + called (all if applicable). Optional arguments should be + indicated. It should be documented whether keyword arguments are + part of the interface. + + The docstring for a class should summarize its behavior and list + the public methods and instance variables. If the class is + intended to be subclassed, and has an additional interface for + subclasses, this interface should be listed separately (in the + docstring). The class constructor should be documented in the + docstring for its __init__ method. Individual methods should be + documented by their own docstring. + + If a class subclasses another class and its behavior is mostly + inherited from that class, its docstring should mention this and + summarize the differences. Use the verb "override" to indicate + that a subclass method replaces a superclass method and does not + call the superclass method; use the verb "extend" to indicate that + a subclass method calls the superclass method (in addition to its + own behavior). + + *Do not* use the Emacs convention of mentioning the arguments of + functions or methods in upper case in running text. Python is + case sensitive and the argument names can be used for keyword + arguments, so the docstring should document the correct argument + names. It is best to list each argument on a separate line. For + example:: + + def complex(real=0.0, imag=0.0): + """Form a complex number. + + Keyword arguments: + real -- the real part (default 0.0) + imag -- the imaginary part (default 0.0) + + """ + if imag == 0.0 and real == 0.0: return complex_zero + ... + + The BDFL [3] recommends inserting a blank line between the last + paragraph in a multi-line docstring and its closing quotes, + placing the closing quotes on a line by themselves. This way, + Emacs' fill-paragraph command can be used on it. + + +References and Footnotes + + [1] PEP 256, Docstring Processing System Framework, Goodger + http://www.python.org/peps/pep-0256.html + + [2] PEP 258, Docutils Design Specification, Goodger + http://www.python.org/peps/pep-0258.html + + [3] Guido van Rossum, Python's creator and Benevolent Dictator For + Life. + + [4] http://www.python.org/doc/essays/styleguide.html + + [5] http://www.python.org/sigs/doc-sig/ + + +Copyright + + This document has been placed in the public domain. + + +Acknowledgements + + The "Specification" text comes mostly verbatim from the Python + Style Guide essay by Guido van Rossum [4]. + + This document borrows ideas from the archives of the Python + Doc-SIG [5]. Thanks to all members past and present. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +fill-column: 70 +sentence-end-double-space: t +End: diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt new file mode 100644 index 000000000..6a55e20de --- /dev/null +++ b/docs/peps/pep-0258.txt @@ -0,0 +1,662 @@ +PEP: 258 +Title: Docutils Design Specification +Version: $Revision$ +Last-Modified: $Date$ +Author: goodger@users.sourceforge.net (David Goodger) +Discussions-To: doc-sig@python.org +Status: Draft +Type: Standards Track +Requires: 256, 257 +Created: 31-May-2001 +Post-History: 13-Jun-2001 + + +Abstract + + This PEP documents design issues and implementation details for + Docutils, a Python Docstring Processing System (DPS). The + rationale and high-level concepts of a DPS are documented in PEP + 256, "Docstring Processing System Framework" [1]. + + No changes to the core Python language are required by this PEP. + Its deliverables consist of a package for the standard library and + its documentation. + + +Specification + + Docstring Extraction Rules + ========================== + + 1. What to examine: + + a) If the "__all__" variable is present in the module being + documented, only identifiers listed in "__all__" are + examined for docstrings. + + b) In the absense of "__all__", all identifiers are examined, + except those whose names are private (names begin with "_" + but don't begin and end with "__"). + + c) 1a and 1b can be overridden by a parameter or command-line + option. + + 2. Where: + + Docstrings are string literal expressions, and are recognized + in the following places within Python modules: + + a) At the beginning of a module, function definition, class + definition, or method definition, after any comments. This + is the standard for Python __doc__ attributes. + + b) Immediately following a simple assignment at the top level + of a module, class definition, or __init__ method + definition, after any comments. See "Attribute Docstrings" + below. + + c) Additional string literals found immediately after the + docstrings in (a) and (b) will be recognized, extracted, and + concatenated. See "Additional Docstrings" below. + + d) @@@ 2.2-style "properties" with attribute docstrings? + + 3. How: + + Whenever possible, Python modules should be parsed by Docutils, + not imported. There are security reasons for not importing + untrusted code. Information from the source is lost when using + introspection to examine an imported module, such as comments + and the order of definitions. Also, docstrings are to be + recognized in places where the bytecode compiler ignores string + literal expressions (2b and 2c above), meaning importing the + module will lose these docstrings. Of course, standard Python + parsing tools such as the "parser" library module may be used. + + When the Python source code for a module is not available + (i.e. only the .pyc file exists) or for C extension modules, to + access docstrings the module can only be imported, and any + limitations must be lived with. + + Since attribute docstrings and additional docstrings are ignored + by the Python bytecode compiler, no namespace pollution or runtime + bloat will result from their use. They are not assigned to + __doc__ or to any other attribute. The initial parsing of a + module may take a slight performance hit. + + + Attribute Docstrings + -------------------- + + (This is a simplified version of PEP 224 [2] by Marc-Andre + Lemberg.) + + A string literal immediately following an assignment statement is + interpreted by the docstring extration machinery as the docstring + of the target of the assignment statement, under the following + conditions: + + 1. The assignment must be in one of the following contexts: + + a) At the top level of a module (i.e., not nested inside a + compound statement such as a loop or conditional): a module + attribute. + + b) At the top level of a class definition: a class attribute. + + c) At the top level of the "__init__" method definition of a + class: an instance attribute. + + Since each of the above contexts are at the top level (i.e., in + the outermost suite of a definition), it may be necessary to + place dummy assignments for attributes assigned conditionally + or in a loop. + + 2. The assignment must be to a single target, not to a list or a + tuple of targets. + + 3. The form of the target: + + a) For contexts 1a and 1b above, the target must be a simple + identifier (not a dotted identifier, a subscripted + expression, or a sliced expression). + + b) For context 1c above, the target must be of the form + "self.attrib", where "self" matches the "__init__" method's + first parameter (the instance parameter) and "attrib" is a + simple indentifier as in 3a. + + Blank lines may be used after attribute docstrings to emphasize + the connection between the assignment and the docstring. + + Examples:: + + g = 'module attribute (module-global variable)' + """This is g's docstring.""" + + class AClass: + + c = 'class attribute' + """This is AClass.c's docstring.""" + + def __init__(self): + self.i = 'instance attribute' + """This is self.i's docstring.""" + + + Additional Docstrings + --------------------- + + (This idea was adapted from PEP 216, Docstring Format [3], by + Moshe Zadka.) + + Many programmers would like to make extensive use of docstrings + for API documentation. However, docstrings do take up space in + the running program, so some of these programmers are reluctant to + "bloat up" their code. Also, not all API documentation is + applicable to interactive environments, where __doc__ would be + displayed. + + The docstring processing system's extraction tools will + concatenate all string literal expressions which appear at the + beginning of a definition or after a simple assignment. Only the + first strings in definitions will be available as __doc__, and can + be used for brief usage text suitable for interactive sessions; + subsequent string literals and all attribute docstrings are + ignored by the Python bytecode compiler and may contain more + extensive API information. + + Example:: + + def function(arg): + """This is __doc__, function's docstring.""" + """ + This is an additional docstring, ignored by the bytecode + compiler, but extracted by the Docutils. + """ + pass + + Issue: This breaks "from __future__ import" statements in Python + 2.1 for multiple module docstrings. The Python Reference Manual + specifies: + + A future statement must appear near the top of the module. + The only lines that can appear before a future statement are: + + * the module docstring (if any), + * comments, + * blank lines, and + * other future statements. + + Resolution? + + 1. Should we search for docstrings after a __future__ statement? + Very ugly. + + 2. Redefine __future__ statements to allow multiple preceeding + string literals? + + 3. Or should we not even worry about this? There shouldn't be + __future__ statements in production code, after all. Will + modules with __future__ statements simply have to put up with + the single-docstring limitation? + + + Choice of Docstring Format + ========================== + + Rather than force everyone to use a single docstring format, + multiple input formats are allowed by the processing system. A + special variable, __docformat__, may appear at the top level of a + module before any function or class definitions. Over time or + through decree, a standard format or set of formats should emerge. + + The __docformat__ variable is a string containing the name of the + format being used, a case-insensitive string matching the input + parser's module or package name (i.e., the same name as required + to "import" the module or package), or a registered alias. If no + __docformat__ is specified, the default format is "plaintext" for + now; this may be changed to the standard format once determined. + + The __docformat__ string may contain an optional second field, + separated from the format name (first field) by a single space: a + case-insensitive language identifier as defined in RFC 1766 [4]. + A typical language identifier consists of a 2-letter language code + from ISO 639 [5] (3-letter codes used only if no 2-letter code + exists; RFC 1766 is currently being revised to allow 3-letter + codes). If no language identifier is specified, the default is + "en" for English. The language identifier is passed to the parser + and can be used for language-dependent markup features. + + + Docutils Project Model + ====================== + + :: + + +--------------------------+ + | Docutils: | + | docutils.core.Publisher, | + | docutils.core.publish() | + +--------------------------+ + / \ + / \ + 1,3,5 / \ 6,8 + +--------+ +--------+ + | READER | =======================> | WRITER | + +--------+ +--------+ + // \ / \ + // \ / \ + 2 // 4 \ 7 / 9 \ + +--------+ +------------+ +------------+ +--------------+ + | PARSER |...| reader | | writer |...| DISTRIBUTOR? | + +--------+ | transforms | | transforms | | | + | | | | | - one file | + | - docinfo | | - styling | | - many files | + | - titles | | - writer- | | - objects in | + | - linking | | specific | | memory | + | - lookups | | - etc. | +--------------+ + | - reader- | +------------+ + | specific | + | - parser- | + | specific | + | - layout | + | - etc. | + +------------+ + + The numbers indicate the path a document would take through the + code. Double-width lines between reader & parser and between + reader & writer, indicating that data sent along these paths + should be standard (pure & unextended) Docutils doc trees. + Single-width lines signify that internal tree extensions or + completely unrelated representations are possible, but they must + be supported internally at both ends. + + + Publisher + --------- + + The "docutils.core" module contains a "Publisher" facade class and + "publish" convenience function. Publisher encapsulates the + high-level logic of a Docutils system. The Publisher.publish() + method passes its input to its Reader, then passes the resulting + document tree through its Writer to its destination. + + + Readers + ------- + + Readers understand the input context (where the data is coming + from), send the whole input or discrete "chunks" to the parser, + and provide the context to bind the chunks together back into a + cohesive whole. Using transforms_, Readers also resolve + references, footnote numbers, interpreted text processing, and + anything else that requires context-sensitive computation. + + Each reader is a module or package exporting a "Reader" class with + a "read" method. The base "Reader" class can be found in the + docutils/readers/__init__.py module. + + Most Readers will have to be told what parser to use. So far (see + the list of examples below), only the Python Source Reader + (PySource) will be able to determine the syntax on its own. + + Responsibilities: + + - Do raw input on the source ("Reader.scan()"). + + - Pass the raw text to the parser, along with a fresh doctree + root ("Reader.parse()"). + + - Run transforms over the doctree(s) ("Reader.transform()"). + + Examples: + + - Standalone/Raw/Plain: Just read a text file and process it. The + reader needs to be told which parser to use. Parser-specific + readers? + + - Python Source: See `Python Source Reader`_ above. + + - Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. + + - PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to + URIs. Either interpret PEPs' indented sections or convert + existing PEPs to reStructuredText (or both?). + + - Wiki: Global reference lookups of "wiki links" incorporated into + transforms. (CamelCase only or unrestricted?) Lazy + indentation? + + - Web Page: As standalone, but recognize meta fields as meta tags. + Support for templates of some sort? (After , before + ?) + + - FAQ: Structured "question & answer(s)" constructs. + + - Compound document: Merge chapters into a book. Master TOC file? + + + Parsers + ------- + + Parsers analyze their input and produce a Docutils `document + tree`_. They don't know or care anything about the source or + destination of the data. + + Each input parser is a module or package exporting a "Parser" + class with a "parse" method. The base "Parser" class can be found + in the docutils/parsers/__init__.py module. + + Responsibilities: Given raw input text and a doctree root node, + populate the doctree by parsing the input text. + + Example: The only parser implemented so far is for the + reStructuredText markup. + + + Transforms + ---------- + + Transforms change the document tree from one form to another, add + to the tree, or prune it. Transforms are run by Reader and Writer + objects. Some transforms are Reader-specific, some are + Parser-specific, and others are Writer-specific. The choice and + order of transforms is specified in the Reader and Writer objects. + + Each transform is a class in a module in the docutils/transforms + package, a subclass of docutils.tranforms.Transform. + + Responsibilities: + + - Modify a doctree in-place, either purely transforming one + structure into another, or adding new structures based on the + doctree and/or external data. + + Examples (in "docutils.transforms"): + + - frontmatter.DocInfo: conversion of document metadata + (bibliographic information). + + - references.Hyperlinks: resolution of hyperlinks. + + - document.Merger: combining multiple populated doctrees into one. + + + Writers + ------- + + Writers produce the final output (HTML, XML, TeX, etc.). Writers + translate the internal document tree structure into the final data + format, possibly running output-specific transforms_ first. + + Each writer is a module or package exporting a "Writer" class with + a "write" method. The base "Writer" class can be found in the + docutils/writers/__init__.py module. + + Responsibilities: + + - Run transforms over the doctree(s). + + - Translate doctree(s) into specific output formats. + + - Transform references into format-native forms. + + - Write output to the destination (possibly via a "Distributor"). + + Examples: + + - XML: Various forms, such as DocBook. Also, raw doctree XML. + + - HTML + + - TeX + + - Plain text + + - reStructuredText? + + + Distributors + ------------ + + Distributors will exist for each method of storing the results of + processing: + + - In a single file on disk. + + - In a tree of directories and files on disk. + + - In a single tree-shaped data structure in memory. + + - Some other set of data structures in memory. + + @@@ Distributors are currently just an idea; they may or may not + be practical. Issues: + + Is it better for the writer to control the distributor, or + vice versa? Or should they be equals? + + Looking at the list of writers, it seems that only HTML would + require anything other than monolithic output. Perhaps merge + the HTML "distributor" into "writer" variants? + + Perhaps translator/writer instead of writer/distributor? + + Responsibilities: + + - Do raw output to the destination. + + - Transform references per incarnation (method of distribution). + + Examples: + + - Single file. + + - Multiple files & directories. + + - Objects in memory. + + + Docutils Package Structure + ========================== + + - Package "docutils". + + - Module "docutils.core" contains facade class "Publisher" and + convenience function "publish()". See `Publisher API`_ below. + + - Module "docutils.nodes" contains the Docutils document tree + element class library plus Visitor pattern base classes. See + `Document Tree`_ below. + + - Module "docutils.roman" contains Roman numeral conversion + routines. + + - Module "docutils.statemachine" contains a finite state machine + specialized for regular-expression-based text filters. The + reStructuredText parser implementation is based on this + module. + + - Module "docutils.urischemes" contains a mapping of known URI + schemes ("http", "ftp", "mail", etc.). + + - Module "docutils.utils" contains utility functions and + classes, including a logger class ("Reporter"; see `Error + Handling`_ below). + + - Package "docutils.parsers": markup parsers_. + + - Function "get_parser_class(parsername)" returns a parser + module by name. Class "Parser" is the base class of + specific parsers. (docutils/parsers/__init__.py) + + - Package "docutils.parsers.rst": the reStructuredText parser. + + - Alternate markup parsers may be added. + + - Package "docutils.readers": context-aware input readers. + + - Function "get_reader_class(readername)" returns a reader + module by name or alias. Class "Reader" is the base class + of specific readers. (docutils/readers/__init__.py) + + - Module "docutils.readers.standalone": reads independent + document files. + + - Readers to be added for: Python source code (structure & + docstrings), PEPs, email, FAQ, and perhaps Wiki and others. + + - Package "docutils.writers": output format writers. + + - Function "get_writer_class(writername)" returns a writer + module by name. Class "Writer" is the base class of + specific writers. (docutils/writers/__init__.py) + + - Module "docutils.writers.pprint" is a simple internal + document tree writer; it writes indented pseudo-XML. + + - Module "docutils.writers.html4css1" is a simple HyperText + Markup Language document tree writer for HTML 4.01 and CSS1. + + - Writers to be added: HTML 3.2 or 4.01-loose, XML (various + forms, such as DocBook and the raw internal doctree), TeX, + plaintext, reStructuredText, and perhaps others. + + - Package "docutils.transforms": tree transform classes. + + - Class "Transform" is the base class of specific transforms; + see `Transform API`_ below. + (docutils/transforms/__init__.py) + + - Each module contains related transform classes. + + - Package "docutils.languages": Language modules contain + language-dependent strings and mappings. They are named for + their language identifier (as defined in `Choice of Docstring + Format`_ above), converting dashes to underscores. + + - Function "getlanguage(languagecode)", returns matching + language module. (docutils/languages/__init__.py) + + - Module "docutils.languages.en" (English). + + - Other languages to be added. + + + Front-End Tools + =============== + + @@@ To be determined. + + @@@ Document tools & summarize their command-line interfaces. + + + Document Tree + ============= + + A single intermediate data structure is used internally by + Docutils, in the interfaces between components; it is defined in + the docutils.nodes module. It is not required that this data + structure be used *internally* by any of the components, just + *between* components. This data structure is similar to a DOM + tree whose schema is documented in an XML DTD (eXtensible Markup + Language Document Type Definition), which comes in two parts: + + - the Docutils Generic DTD, docutils.dtd [6], and + + - the OASIS Exchange Table Model, soextbl.dtd [7]. + + The DTD defines a rich set of elements, suitable for many input + and output formats. The DTD retains all information necessary to + reconstruct the original input text, or a reasonable facsimile + thereof. + + + Error Handling + ============== + + When the parser encounters an error in markup, it inserts a system + message (DTD element "system_message"). There are five levels of + system messages: + + - Level-0, "DEBUG": an internal reporting issue. There is no + effect on the processing. Level-0 system messages are + handled separately from the others. + + - Level-1, "INFO": a minor issue that can be ignored. There is + little or no effect on the processing. Typically level-1 system + messages are not reported. + + - Level-2, "WARNING": an issue that should be addressed. If + ignored, there may be unpredictable problems with the output. + Typically level-2 system messages are reported but do not halt + processing + + - Level-3, "ERROR": a major issue that should be addressed. If + ignored, the output will contain errors. Typically level-3 + system messages are reported but do not halt processing + + - Level-4, "SEVERE": a critical error that must be addressed. + Typically level-4 system messages are turned into exceptions + which halt processing. If ignored, the output will contain + severe errors. + + Although the initial message levels were devised independently, + they have a strong correspondence to VMS error condition severity + levels [8]; the names in quotes for levels 1 through 4 were + borrowed from VMS. Error handling has since been influenced by + the log4j project [9]. + + +References and Footnotes + + [1] PEP 256, Docstring Processing System Framework, Goodger + http://www.python.org/peps/pep-0256.html + + [2] PEP 224, Attribute Docstrings, Lemburg + http://www.python.org/peps/pep-0224.html + + [3] PEP 216, Docstring Format, Zadka + http://www.python.org/peps/pep-0216.html + + [4] http://www.rfc-editor.org/rfc/rfc1766.txt + + [5] http://lcweb.loc.gov/standards/iso639-2/englangn.html + + [6] http://docutils.sourceforge.net/spec/docutils.dtd + + [7] http://docstring.sourceforge.net/spec/soextblx.dtd + + [8] http://www.openvms.compaq.com:8000/73final/5841/ + 5841pro_027.html#error_cond_severity + + [9] http://jakarta.apache.org/log4j/ + + [10] http://www.python.org/sigs/doc-sig/ + + +Project Web Site + + A SourceForge project has been set up for this work at + http://docutils.sourceforge.net/. + + +Copyright + + This document has been placed in the public domain. + + +Acknowledgements + + This document borrows ideas from the archives of the Python + Doc-SIG [10]. Thanks to all members past & present. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +fill-column: 70 +sentence-end-double-space: t +End: diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt new file mode 100644 index 000000000..90aea7054 --- /dev/null +++ b/docs/ref/doctree.txt @@ -0,0 +1,344 @@ +================================== + Docutils Document Tree Structure +================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +This document describes the internal data structure representing +document trees in Docutils. The data structure is defined by the +hierarchy of classes in the ``docutils.nodes`` module. It is also +formally described by the `Docutils Generic DTD`_ XML document type +definition, docutils.dtd_, which is the definitive source for element +hierarchy details. + +Below is a simplified diagram of the hierarchy of element types in the +Docutils document tree structure. An element may contain any other +elements immediately below it in the diagram. Text in square brackets +are notes. Element types in parentheses indicate recursive or +one-to-many relationships; sections may contain (sub)sections, tables +contain further body elements, etc. :: + + +--------------------------------------------------------------------+ + | document [may begin with a title, subtitle, docinfo] | + | +--------------------------------------+ + | | sections [each begins with a title] | + +-----------------------------+-------------------------+------------+ + | [body elements:] | (sections) | + | | - literal | - lists | | - hyperlink +------------+ + | | blocks | - tables | | targets | + | para- | - doctest | - block | foot- | - sub. defs | + | graphs | blocks | quotes | notes | - comments | + +---------+-----------+----------+-------+--------------+ + | [text]+ | [text] | (body elements) | [text] | + | (inline +-----------+------------------+--------------+ + | markup) | + +---------+ + + +------------------- + Element Hierarchy +------------------- + +A class hierarchy has been implemented in nodes.py where the position +of the element (the level at which it can occur) is significant. +E.G., Root, Structural, Body, Inline classes etc. Certain +transformations will be easier because we can use isinstance() on +them. + +The elements making up Docutils document trees can be categorized into +the following groups: + +- _`Root element`: document_ + +- _`Title elements`: title_, subtitle_ + +- _`Bibliographic elements`: docinfo_, author_, authors_, + organization_, contact_, version_, revision_, status_, date_, + copyright_ + +- _`Structural elements`: document_, section_, topic_, transition_ + +- _`Body elements`: + + - _`General body elements`: paragraph_, literal_block_, + block_quote_, doctest_block_, table_, figure_, image_, footnote_ + + - _`Lists`: bullet_list_, enumerated_list_, definition_list_, + field_list_, option_list_ + + - _`Admonitions`: note_, tip_, warning_, error_, caution_, danger_, + important_ + + - _`Special body elements`: target_, substitution_definition_, + comment_, system_warning_ + +- _`Inline elements`: emphasis_, strong_, interpreted_, literal_, + reference_, target_, footnote_reference_, substitution_reference_, + image_, problematic_ + + +``Node`` +======== + + +``Text`` +======== + + +``Element`` +=========== + + +``TextElement`` +=============== + + +------------------- + Element Reference +------------------- + +``document`` +============ +description + +contents + +External attributes +------------------- +`Common external attributes`_. + + +Internal attributes +------------------- +- `Common internal attributes`_. +- ``explicittargets`` +- ``implicittargets`` +- ``externaltargets`` +- ``indirecttargets`` +- ``refnames`` +- ``anonymoustargets`` +- ``anonymousrefs`` +- ``autofootnotes`` +- ``autofootnoterefs`` +- ``reporter`` + + +--------------------- + Attribute Reference +--------------------- + +External Attributes +=================== + +Through the `%basic.atts;`_ parameter entity, all elements share the +following _`common external attributes`: id_, name_, dupname_, +source_. + + +``anonymous`` +------------- +The ``anonymous`` attribute + + +``auto`` +-------- +The ``auto`` attribute + + +``dupname`` +----------- +The ``dupname`` attribute + + +``id`` +------ +The ``id`` attribute + + +``name`` +-------- +The ``name`` attribute + + +``refid`` +--------- +The ``refid`` attribute + + +``refname`` +----------- +The ``refname`` attribute + + +``refuri`` +---------- +The ``refuri`` attribute + + +``source`` +---------- +The ``source`` attribute + + +``xml:space`` +------------- +The ``xml:space`` attribute + + +Internal Attributes +=================== + +All element objects share the following _`common internal attributes`: +rawsource_, children_, attributes_, tagname_. + + +------------------------ + DTD Parameter Entities +------------------------ + +``%basic.atts;`` +================ +The ``%basic.atts;`` parameter entity lists attributes common to all +elements. See `Common Attributes`_. + + +``%body.elements;`` +=================== +The ``%body.elements;`` parameter entity + + +``%inline.elements;`` +==================== +The ``%inline.elements;`` parameter entity + + +``%reference.atts;`` +==================== +The ``%reference.atts;`` parameter entity + + +``%structure.model;`` +===================== +The ``%structure.model;`` parameter entity + + +``%text.model;`` +================ +The ``%text.model;`` parameter entity + + +-------------------------------- + Appendix: Miscellaneous Topics +-------------------------------- + +Representation of Horizontal Rules +================================== + +Having added the "horizontal rule" construct to the reStructuredText_ +spec, a decision had to be made as to how to reflect the construct in +the implementation of the document tree. Given this source:: + + Document + ======== + + Paragraph + + -------- + + Paragraph + +The horizontal rule indicates a "transition" (in prose terms) or the +start of a new "division". Before implementation, the parsed document +tree would be:: + + +

+ + Document + <paragraph> + Paragraph + -------- <--- error here + <paragraph> + Paragraph + +There are several possibilities for the implementation. Solution 3 +was chosen. + +1. Implement horizontal rules as "divisions" or segments. A + "division" is a title-less, non-hierarchical section. The first + try at an implementation looked like this:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph + <division> + <paragraph> + Paragraph + + But the two paragraphs are really at the same level; they shouldn't + appear to be at different levels. There's really an invisible + "first division". The horizontal rule splits the document body + into two segments, which should be treated uniformly. + +2. Treating "divisions" uniformly brings us to the second + possibility:: + + <document> + <section name="document"> + <title> + Document + <division> + <paragraph> + Paragraph + <division> + <paragraph> + Paragraph + + With this change, documents and sections will directly contain + divisions and sections, but not body elements. Only divisions will + directly contain body elements. Even without a horizontal rule + anywhere, the body elements of a document or section would be + contained within a division element. This makes the document tree + deeper. This is similar to the way HTML treats document contents: + grouped within a <BODY> element. + +3. Implement them as "transitions", empty elements:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph + <transition> + <paragraph> + Paragraph + + A transition would be a "point element", not containing anything, + only identifying a point within the document structure. This keeps + the document tree flatter, but the idea of a "point element" like + "transition" smells bad. A transition isn't a thing itself, it's + the space between two divisions. + + This solution has been chosen for incorporation into the document + tree. + + +.. _Docutils Generic DTD: +.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _reStructuredText: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd new file mode 100644 index 000000000..d47238b4d --- /dev/null +++ b/docs/ref/docutils.dtd @@ -0,0 +1,514 @@ +<!-- +====================================================================== + Docutils Generic DTD +====================================================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This DTD has been placed in the public domain. +:Filename: docutils.dtd + +More information about this DTD (document type definition) 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/spec/docutils.dtd. + +The proposed formal public identifier for this DTD is:: + + +//IDN python.org//DTD Docutils Generic//EN//XML +--> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Parameter Entities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Parameter entities are used to simplify the DTD (reduce duplication) +and to allow the DTD to be customized by wrapper DTDs. Parameter +entities beginning with 'additional' are meant to allow easy extension +by wrapper DTDs. +--> + +<!-- Attributes +================================================================== --> + +<!-- Boolean: no if zero(s), yes if any other value. --> +<!ENTITY % yesorno "NMTOKEN"> + +<!ENTITY % additional.basic.atts ""> +<!-- +Attributes shared by all elements in this DTD: + +- `id` is a unique identifier, typically assigned by the system. +- `name` is an identifier assigned in the markup. +- `dupname` is the same as `name`, used when it's a duplicate. +- `source` is the name of the source of this document or fragment. +- `class` is used to transmit individuality information forward. +--> +<!ENTITY % basic.atts + " id ID #IMPLIED + name CDATA #IMPLIED + dupname CDATA #IMPLIED + source CDATA #IMPLIED + class CDATA #IMPLIED + %additional.basic.atts; "> + +<!-- External reference to a URI/URL. --> +<!ENTITY % refuri.att + " refuri CDATA #IMPLIED "> + +<!-- Internal reference to the `id` attribute of an element. --> +<!ENTITY % refid.att + " refid IDREF #IMPLIED "> + +<!-- Space-separated list of id references, for backlinks. --> +<!ENTITY % backrefs.att + " backrefs IDREFS #IMPLIED "> + +<!-- +Internal reference to the `name` attribute of an element. On a +'target' element, 'refname' indicates an indirect target which may +resolve to either an internal or external reference. +--> +<!ENTITY % refname.att + " refname CDATA #IMPLIED "> + +<!ENTITY % additional.reference.atts ""> +<!-- Collected hyperlink reference attributes. --> +<!ENTITY % reference.atts + " %refuri.att; + %refid.att; + %refname.att; + %additional.reference.atts; "> + +<!-- Unnamed hyperlink. --> +<!ENTITY % anonymous.att + " anonymous %yesorno; #IMPLIED "> + +<!-- Auto-numbered footnote. --> +<!ENTITY % auto.att + " auto %yesorno; #IMPLIED "> + +<!-- XML standard attribute for whitespace-preserving elements. --> +<!ENTITY % fixedspace.att + " xml:space (default | preserve) #FIXED 'preserve' "> + + +<!-- Element OR-Lists +============================================================= --> + +<!ENTITY % additional.bibliographic.elements ""> +<!ENTITY % bibliographic.elements + " author | authors | organization | contact + | version | revision | status | date | copyright + %additional.bibliographic.elements; "> + +<!ENTITY % additional.structural.elements ""> +<!ENTITY % structural.elements + " section + %additional.structural.elements; "> + +<!ENTITY % additional.body.elements ""> +<!ENTITY % body.elements + " paragraph | literal_block | block_quote | doctest_block| table + | figure | image | footnote | citation + | bullet_list | enumerated_list | definition_list | field_list + | option_list + | attention | caution | danger | error | hint | important | note + | tip | warning + | target | substitution_definition | comment | pending + | system_message | raw + %additional.body.elements; "> + +<!ENTITY % additional.inline.elements ""> +<!ENTITY % inline.elements + " emphasis | strong | interpreted | literal + | reference | footnote_reference | citation_reference + | substitution_reference | target | image | problematic | raw + %additional.inline.elements; "> + +<!-- Element Content Models +================================================================== --> + +<!ENTITY % structure.model + " ( ( (%body.elements; | topic)+, + (transition, (%body.elements; | topic)+ )*, + (%structural.elements;)* ) + | (%structural.elements;)+ ) "> + +<!ENTITY % text.model + " (#PCDATA | %inline.elements;)* "> + +<!-- Table Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This DTD uses the Exchange subset of the CALS-table model (OASIS +Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", +http://www.oasis-open.org/html/tm9901.htm). +--> + +<!ENTITY % calstblx PUBLIC + "-//OASIS//DTD XML Exchange Table Model 19990315//EN" + "soextblx.dtd"> + +<!-- These parameter entities customize the table model DTD. --> +<!ENTITY % bodyatt " %basic.atts; "> <!-- table elt --> +<!ENTITY % tbl.tgroup.att " %basic.atts; "> +<!ENTITY % tbl.thead.att " %basic.atts; "> +<!ENTITY % tbl.tbody.att " %basic.atts; "> +<!ENTITY % tbl.colspec.att " %basic.atts; "> +<!ENTITY % tbl.row.att " %basic.atts; "> +<!ENTITY % tbl.entry.mdl " (%body.elements;)* "> +<!ENTITY % tbl.entry.att + " %basic.atts; + morecols NMTOKEN #IMPLIED "> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Root Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Optional elements may be generated by internal processing. --> +<!ELEMENT document + ((title, subtitle?)?, docinfo?, %structure.model;)> +<!ATTLIST document %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Title Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT title %text.model;> +<!ATTLIST title + %basic.atts; + %refid.att;> + +<!ELEMENT subtitle %text.model;> +<!ATTLIST subtitle %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Bibliographic Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Container for bibliographic elements. May not be empty. --> +<!ELEMENT docinfo (%bibliographic.elements;)+> +<!ATTLIST docinfo %basic.atts;> + +<!ELEMENT author %text.model;> +<!ATTLIST author %basic.atts;> + +<!ELEMENT authors ((author, organization?, contact?)+)> +<!ATTLIST authors %basic.atts;> + +<!ELEMENT organization %text.model;> +<!ATTLIST organization %basic.atts;> + +<!ELEMENT contact %text.model;> +<!ATTLIST contact %basic.atts;> + +<!ELEMENT version %text.model;> +<!ATTLIST version %basic.atts;> + +<!ELEMENT revision %text.model;> +<!ATTLIST revision %basic.atts;> + +<!ELEMENT status %text.model;> +<!ATTLIST status %basic.atts;> + +<!ELEMENT date %text.model;> +<!ATTLIST date %basic.atts;> + +<!ELEMENT copyright %text.model;> +<!ATTLIST copyright %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Structural Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT section (title, %structure.model;)> +<!ATTLIST section %basic.atts;> + +<!ELEMENT topic (title?, (%body.elements;)+)> +<!ATTLIST topic %basic.atts;> + +<!ELEMENT transition EMPTY> +<!ATTLIST transition %basic.atts;> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Body Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT paragraph %text.model;> +<!ATTLIST paragraph %basic.atts;> + +<!ELEMENT bullet_list (list_item+)> +<!ATTLIST bullet_list + %basic.atts; + bullet CDATA #IMPLIED> + +<!ELEMENT enumerated_list (list_item+)> +<!ATTLIST enumerated_list + %basic.atts; + enumtype (arabic | loweralpha | upperalpha + | lowerroman | upperroman) + #IMPLIED + prefix CDATA #IMPLIED + suffix CDATA #IMPLIED + start NUMBER #IMPLIED> + +<!ELEMENT list_item (%body.elements;)+> +<!ATTLIST list_item %basic.atts;> + +<!ELEMENT definition_list (definition_list_item+)> +<!ATTLIST definition_list %basic.atts;> + +<!ELEMENT definition_list_item (term, classifier?, definition)> +<!ATTLIST definition_list_item %basic.atts;> + +<!ELEMENT term %text.model;> +<!ATTLIST term %basic.atts;> + +<!ELEMENT classifier %text.model;> +<!ATTLIST classifier %basic.atts;> + +<!ELEMENT definition (%body.elements;)+> +<!ATTLIST definition %basic.atts;> + +<!ELEMENT field_list (field+)> +<!ATTLIST field_list %basic.atts;> + +<!ELEMENT field (field_name, field_argument*, field_body)> +<!ATTLIST field %basic.atts;> + +<!ELEMENT field_name (#PCDATA)> +<!ATTLIST field_name %basic.atts;> + +<!-- Support for Javadoc-style tags with arguments. --> +<!ELEMENT field_argument (#PCDATA)> +<!ATTLIST field_argument %basic.atts;> + +<!ELEMENT field_body (%body.elements;)+> +<!ATTLIST field_body %basic.atts;> + +<!ELEMENT option_list (option_list_item+)> +<!ATTLIST option_list %basic.atts;> + +<!ELEMENT option_list_item (option_group, description)> +<!ATTLIST option_list_item %basic.atts;> + +<!ELEMENT option_group (option+)> +<!ATTLIST option_group %basic.atts;> + +<!ELEMENT option (option_string, option_argument*)> +<!ATTLIST option %basic.atts;> + +<!ELEMENT option_string (#PCDATA)> +<!ATTLIST option_string %basic.atts;> + +<!-- +`delimiter` contains the string preceding the `option_argument`: +either the string separating it from the `option` (typically either +"=" or " ") or the string between option arguments (typically either +"," or " "). +--> +<!ELEMENT option_argument (#PCDATA)> +<!ATTLIST option_argument + %basic.atts; + delimiter CDATA #IMPLIED> + +<!ELEMENT description (%body.elements;)+> +<!ATTLIST description %basic.atts;> + +<!ELEMENT literal_block (#PCDATA)> +<!ATTLIST literal_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT block_quote (%body.elements;)+> +<!ATTLIST block_quote %basic.atts;> + +<!ELEMENT doctest_block (#PCDATA)> +<!ATTLIST doctest_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT attention (%body.elements;)+> +<!ATTLIST attention %basic.atts;> + +<!ELEMENT caution (%body.elements;)+> +<!ATTLIST caution %basic.atts;> + +<!ELEMENT danger (%body.elements;)+> +<!ATTLIST danger %basic.atts;> + +<!ELEMENT error (%body.elements;)+> +<!ATTLIST error %basic.atts;> + +<!ELEMENT hint (%body.elements;)+> +<!ATTLIST hint %basic.atts;> + +<!ELEMENT important (%body.elements;)+> +<!ATTLIST important %basic.atts;> + +<!ELEMENT note (%body.elements;)+> +<!ATTLIST note %basic.atts;> + +<!ELEMENT tip (%body.elements;)+> +<!ATTLIST tip %basic.atts;> + +<!ELEMENT warning (%body.elements;)+> +<!ATTLIST warning %basic.atts;> + +<!ELEMENT footnote (label?, (%body.elements;)+)> +<!ATTLIST footnote + %basic.atts; + %backrefs.att; + %auto.att;> + +<!ELEMENT citation (label, (%body.elements;)+)> +<!ATTLIST citation + %basic.atts; + %backrefs.att;> + +<!ELEMENT label (#PCDATA)> +<!ATTLIST label %basic.atts;> + +<!-- Empty except when used as an inline element. --> +<!ELEMENT target (%text.model;)> +<!ATTLIST target + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT substitution_definition (%text.model;)> +<!ATTLIST substitution_definition %basic.atts;> + +<!ELEMENT comment (#PCDATA)> +<!ATTLIST comment + %basic.atts; + %fixedspace.att;> + +<!ELEMENT pending EMPTY> +<!ATTLIST pending %basic.atts;> + +<!ELEMENT figure (image, ((caption, legend?) | legend) > +<!ATTLIST figure %basic.atts;> + +<!-- Also an inline element. --> +<!ELEMENT image EMPTY> +<!ATTLIST image + %basic.atts; + uri CDATA #REQUIRED + alt CDATA #IMPLIED + height NMTOKEN #IMPLIED + width NMTOKEN #IMPLIED + scale NMTOKEN #IMPLIED> + +<!ELEMENT caption %text.model;> +<!ATTLIST caption %basic.atts;> + +<!ELEMENT legend (%body.elements;)+> +<!ATTLIST legend %basic.atts;> + +<!-- +Table elements: table, tgroup, colspec, thead, tbody, row, entry. +--> +%calstblx; + +<!-- Used to record processing information. --> +<!ELEMENT system_message (%body.elements;)+> +<!ATTLIST system_message + %basic.atts; + %backrefs.att; + level NMTOKEN #IMPLIED + type CDATA #IMPLIED> + +<!-- Used to pass raw data through the system. Also inline. --> +<!ELEMENT raw %text.model;> +<!ATTLIST raw + %basic.atts; + %fixedspace.att; + format CDATA #IMPLIED> + + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Inline Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inline elements occur within the text contents of body elements. Some +nesting of inline elements is allowed by these definitions, with the +following caveats: + +- An inline element may not contain a nested element of the same type + (e.g. <strong> may not contain another <strong>). +- Nested inline elements may or may not be supported by individual + applications using this DTD. +- The inline elements <footnote_reference>, <citation_reference>, + <literal>, and <image> do not support nesting. +--> + +<!ELEMENT emphasis (%text.model;)> +<!ATTLIST emphasis %basic.atts;> + +<!ELEMENT strong (%text.model;)> +<!ATTLIST strong %basic.atts;> + +<!ELEMENT interpreted (%text.model;)> +<!ATTLIST interpreted + %basic.atts; + type CDATA #IMPLIED> + +<!ELEMENT literal (#PCDATA)> +<!ATTLIST literal %basic.atts;> + +<!ELEMENT reference (%text.model;)> +<!ATTLIST reference + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT footnote_reference (#PCDATA)> +<!ATTLIST footnote_reference + %basic.atts; + %reference.atts; + %auto.att;> + +<!ELEMENT citation_reference (#PCDATA)> +<!ATTLIST citation_reference + %basic.atts; + %reference.atts;> + +<!ELEMENT substitution_reference (%text.model;)> +<!ATTLIST substitution_reference + %basic.atts; + %refname.att;> + +<!ELEMENT problematic (%text.model;)> +<!ATTLIST problematic + %basic.atts; + %refid.att;> + + +<!-- +Local Variables: +mode: sgml +indent-tabs-mode: nil +fill-column: 70 +End: +--> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt new file mode 100644 index 000000000..cbb8b4609 --- /dev/null +++ b/docs/ref/rst/directives.txt @@ -0,0 +1,360 @@ +============================= + reStructuredText Directives +============================= +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +This document describes the directives implemented in the reference +reStructuredText parser. + + +.. contents:: + + +------------- + Admonitions +------------- + +DTD elements: attention, caution, danger, error, hint, important, +note, tip, warning. + +Directive block: directive data and all following indented text +are interpreted as body elements. + +Admonitions are specially marked "topics" that can appear anywhere an +ordinary body element can. They contain arbitrary body elements. +Typically, an admonition is rendered as an offset block in a document, +sometimes outlined or shaded, with a title matching the admonition +type. For example:: + + .. DANGER:: + Beware killer rabbits! + +This directive might be rendered something like this:: + + +------------------------+ + | !DANGER! | + | | + | Beware killer rabbits! | + +------------------------+ + +The following admonition directives have been implemented: + +- attention +- caution +- danger +- error +- hint +- important +- note +- tip +- warning + +Any text immediately following the directive indicator (on the same +line and/or indented on following lines) is interpreted as a directive +block and is parsed for normal body elements. For example, the +following "note" admonition directive contains one paragraph and a +bullet list consisting of two list items:: + + .. note:: This is a note admonition. + This is the second line of the first paragraph. + + - The note contains all indented body elements + following. + - It includes this bullet list. + + +-------- + Images +-------- + +There are two image directives: "image" and "figure". + + +Image +===== + +DTD element: image. + +Directive block: directive data and following indented lines (up to +the first blank line) are interpreted as image URI and optional +attributes. + +An "image" is a simple picture:: + + .. image:: picture.png + +The URI for the image source file is specified in the directive data. +As with hyperlink targets, the image URI may begin on the same line as +the explicit markup start and target name, or it may begin in an +indented text block immediately following, with no intervening blank +lines. If there are multiple lines in the link block, they are +stripped of leading and trailing whitespace and joined together. + +Optionally, the image link block may end with a flat field list, the +_`image attributes`. For example:: + + .. image:: picture.png + :height: 100 + :width: 200 + :scale: 50 + :alt: alternate text + +The following attributes are recognized: + +``alt`` : text + Alternate text: a short description of the image, displayed by + applications that cannot display images, or spoken by applications + for visually impaired users. +``height`` : integer + The height of the image in pixels, used to reserve space or scale + the image vertically. +``width`` : integer + The width of the image in pixels, used to reserve space or scale + the image horizontally. +``scale`` : integer + The uniform scaling factor of the image, a percentage (but no "%" + symbol is required or allowed). "100" means full-size. + + +Figure +====== + +DTD elements: figure, image, caption, legend. + +Directive block: directive data and all following indented text are +interpreted as an image URI, optional attributes, a caption, and an +optional legend. + +A "figure" consists of image_ data (optionally including `image +attributes`_), an optional caption (a single paragraph), and an +optional legend (arbitrary body elements):: + + .. figure:: picture.png + :scale: 50 + :alt: map to buried treasure + + This is the caption of the figure (a simple paragraph). + + The legend consists of all elements after the caption. In this + case, the legend consists of this paragraph and the following + table: + + +-----------------------+-----------------------+ + | Symbol | Meaning | + +=======================+=======================+ + | .. image:: tent.png | Campground | + +-----------------------+-----------------------+ + | .. image:: waves.png | Lake | + +-----------------------+-----------------------+ + | .. image:: peak.png | Mountain | + +-----------------------+-----------------------+ + +There must be a blank line before the caption paragraph and before the +legend. To specify a legend without a caption, use an empty comment +("..") in place of the caption. + + +--------------------- + Document Components +--------------------- + +Table of Contents +================= + +DTD elements: pending, topic. + +Directive block: directive data and following indented lines (up to +the first blank line) are interpreted as the topic title and optional +attributes. + +The "contents" directive inserts a table of contents (TOC) in two +passes: initial parse and transform. During the initial parse, a +"pending" element is generated which acts as a placeholder, storing +the TOC title and any attributes internally. At a later stage in the +processing, the "pending" element is replaced by a "topic" element, a +title and the table of contents proper. + +The directive in its simplest form:: + + .. contents:: + +Language-dependent boilerplate text will be used for the title. The +English default title text is "Contents". + +An explicit title, may be specified:: + + .. contents:: Table of Contents + +The title may span lines, although it is not recommended:: + + .. contents:: Here's a very long Table of + Contents title + +Attributes may be specified for the directive, using a field list:: + + .. contents:: Table of Contents + :depth: 2 + +If the default title is to be used, the attribute field list may begin +on the same line as the directive marker:: + + .. contents:: :depth: 2 + +The following attributes are recognized: + +``depth`` : integer + The number of section levels that are collected in the table of + contents. +``local`` : empty + Generate a local table of contents. Entries will only include + subsections of the section in which the directive is given. If no + explicit title is given, the table of contents will not be titled. + + +Footnotes +========= + +DTD elements: pending, topic. + +@@@ + + +Citations +========= + +DTD elements: pending, topic. + +@@@ + + +Topic +===== + +DTD element: topic. + +@@@ + + +--------------- + HTML-Specific +--------------- + +Meta +==== + +Non-standard element: meta. + +Directive block: directive data and following indented lines (up to +the first blank line) are parsed for a flat field list. + +The "meta" directive is used to specify HTML metadata stored in HTML +META tags. "Metadata" is data about data, in this case data about web +pages. Metadata is used to describe and classify web pages in the +World Wide Web, in a form that is easy for search engines to extract +and collate. + +Within the directive block, a flat field list provides the syntax for +metadata. The field name becomes the contents of the "name" attribute +of the META tag, and the field body (interpreted as a single string +without inline markup) becomes the contents of the "content" +attribute. For example:: + + .. meta:: + :description: The reStructuredText plaintext markup language + :keywords: plaintext, markup language + +This would be converted to the following HTML:: + + <meta name="description" + content="The reStructuredText plaintext markup language"> + <meta name="keywords" content="plaintext, markup language"> + +Support for other META attributes ("http-equiv", "scheme", "lang", +"dir") are provided through field arguments, which must be of the form +"attr=value":: + + .. meta:: + :description lang=en: An amusing story + :description lang=fr: Un histoire amusant + +And their HTML equivalents:: + + <meta name="description" lang="en" content="An amusing story"> + <meta name="description" lang="fr" content="Un histoire amusant"> + +Some META tags use an "http-equiv" attribute instead of the "name" +attribute. To specify "http-equiv" META tags, simply omit the name:: + + .. meta:: + :http-equiv=Content-Type: text/html; charset=ISO-8859-1 + +HTML equivalent:: + + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1"> + + +Imagemap +======== + +Non-standard element: imagemap. + + +--------------- + Miscellaneous +--------------- + +Raw Data Pass-Through +===================== + +DTD element: pending. + +Directive block: the directive data is interpreted as an output format +type, and all following indented text is stored verbatim, +uninterpreted. + +The "raw" directive indicates non-reStructuredText data that is to be +passed untouched to the Writer. The name of the output format is +given in the directive data. During the initial parse, a "pending" +element is generated which acts as a placeholder, storing the format +and raw data internally. The interpretation of the code is up to the +Writer. A Writer may ignore any raw output not matching its format. + +For example, the following input would be passed untouched by an HTML +Writer:: + + .. raw:: html + <hr width=50 size=10> + +A LaTeX Writer could insert the following raw content into its +output stream:: + + .. raw:: latex + \documentclass[twocolumn]{article} + + +Restructuredtext-Test-Directive +=============================== + +DTD element: system_warning. + +Directive block: directive data is stored, and all following indented +text is interpreted as a literal block. + +This directive is provided for test purposes only. (Nobody is +expected to type in a name *that* long!) It is converted into a +level-1 (info) system message showing the directive data, possibly +followed by a literal block containing the rest of the directive +block. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt new file mode 100644 index 000000000..3d7cfc5f8 --- /dev/null +++ b/docs/ref/rst/introduction.txt @@ -0,0 +1,307 @@ +===================================== + An Introduction to reStructuredText +===================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get +plaintext markup syntax and parser system. It is useful for in-line +program documentation (such as Python docstrings), for quickly +creating simple web pages, and for standalone documents. +reStructuredText_ is a proposed revision and reinterpretation of the +StructuredText_ and Setext_ lightweight markup systems. + +reStructuredText is designed for extensibility for specific +application domains. Its parser is a component of Docutils_. + +This document defines the goals_ of reStructuredText and provides a +history_ of the project. It is written using the reStructuredText +markup, and therefore serves as an example of its use. Please also +see an analysis of the `problems with StructuredText`_ and the +`reStructuredText markup specification`_ itself at project's web page, +http://docutils.sourceforge.net/rst.html. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _StructuredText: + http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage +.. _Setext: http://docutils.sourceforge.net/mirror/setext.html +.. _Docutils: http://docutils.sourceforge.net/ +.. _Problems with StructuredText: problems.html +.. _reStructuredText Markup Specification: reStructuredText.html + + +Goals +===== + +The primary goal of reStructuredText_ is to define a markup syntax for +use in Python docstrings and other documentation domains, that is +readable and simple, yet powerful enough for non-trivial use. The +intended purpose of the reStructuredText markup is twofold: + +- the establishment of a set of standard conventions allowing the + expression of structure within plaintext, and + +- the conversion of such documents into useful structured data + formats. + +The secondary goal of reStructuredText is to be accepted by the Python +community (by way of being blessed by PythonLabs and the BDFL [#]_) as +a standard for Python inline documentation (possibly one of several +standards, to account for taste). + +.. [#] Python's creator and "Benevolent Dictator For Life", + Guido van Rossum. + +To clarify the primary goal, here are specific design goals, in order, +beginning with the most important: + +1. Readable. The marked-up text must be easy to read without any + prior knowledge of the markup language. It should be as easily + read in raw form as in processed form. + +2. Unobtrusive. The markup that is used should be as simple and + unobtrusive as possible. The simplicity of markup constructs + should be roughly proporional to their frequency of use. The most + common constructs, with natural and obvious markup, should be the + simplest and most unobtrusive. Less common contstructs, for which + there is no natural or obvious markup, should be distinctive. + +3. Unambiguous. The rules for markup must not be open for + interpretation. For any given input, there should be one and only + one possible output (including error output). + +4. Unsurprising. Markup constructs should not cause unexpected output + upon processing. As a fallback, there must be a way to prevent + unwanted markup processing when a markup construct is used in a + non-markup context (for example, when documenting the markup syntax + itself). + +5. Intuitive. Markup should be as obvious and easily remembered as + possible, for the author as well as for the reader. Constructs + should take their cues from such naturally occurring sources as + plaintext email messages, newsgroup postings, and text + documentation such as README.txt files. + +6. Easy. It should be easy to mark up text using any ordinary text + editor. + +7. Scalable. The markup should be applicable regardless of the length + of the text. + +8. Powerful. The markup should provide enough constructs to produce a + reasonably rich structured document. + +9. Language-neutral. The markup should apply to multiple natural (as + well as artificial) languages, not only English. + +10. Extensible. The markup should provide a simple syntax and + interface for adding more complex general markup, and custom + markup. + +11. Output-format-neutral. The markup will be appropriate for + processing to multiple output formats, and will not be biased + toward any particular format. + +The design goals above were used as criteria for accepting or +rejecting syntax, or selecting between alternatives. + +It is emphatically *not* the goal of reStructuredText to define +docstring semantics, such as docstring contents or docstring length. +These issues are orthogonal to the markup syntax and beyond the scope +of this specification. + +Also, it is not the goal of reStructuredText to maintain compatibility +with StructuredText_ or Setext_. reStructuredText shamelessly steals +their great ideas and ignores the not-so-great. + +Author's note: + + Due to the nature of the problem we're trying to solve (or, + perhaps, due to the nature of the proposed solution), the above + goals unavoidably conflict. I have tried to extract and distill + the wisdom accumulated over the years in the Python Doc-SIG_ + mailing list and elsewhere, to come up with a coherent and + consistent set of syntax rules, and the above goals by which to + measure them. + + There will inevitably be people who disagree with my particular + choices. Some desire finer control over their markup, others + prefer less. Some are concerned with very short docstrings, + others with full-length documents. This specification is an + effort to provide a reasonably rich set of markup constructs in a + reasonably simple form, that should satisfy a reasonably large + group of reasonable people. + + David Goodger (goodger@users.sourceforge.net), 2001-04-20 + +.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ + + +History +======= + +reStructuredText_, the specification, is based on StructuredText_ and +Setext_. StructuredText was developed by Jim Fulton of `Zope +Corporation`_ (formerly Digital Creations) and first released in 1996. +It is now released as a part of the open-source 'Z Object Publishing +Environment' (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ +specification was either an influence on StructuredText or, by their +similarities, at least evidence of the correctness of this approach. + +I discovered StructuredText_ in late 1999 while searching for a way to +document the Python modules in one of my projects. Version 1.1 of +StructuredText was included in Daniel Larsson's pythondoc_. Although +I was not able to get pythondoc to work for me, I found StructuredText +to be almost ideal for my needs. I joined the Python Doc-SIG_ +(Documentation Special Interest Group) mailing list and found an +ongoing discussion of the shortcomings of the StructuredText +'standard'. This discussion has been going on since the inception of +the mailing list in 1996, and possibly predates it. + +I decided to modify the original module with my own extensions and +some suggested by the Doc-SIG members. I soon realized that the +module was not written with extension in mind, so I embarked upon a +general reworking, including adapting it to the 're' regular +expression module (the original inspiration for the name of this +project). Soon after I completed the modifications, I discovered that +StructuredText.py was up to version 1.23 in the ZOPE distribution. +Implementing the new syntax extensions from version 1.23 proved to be +an exercise in frustration, as the complexity of the module had become +overwhelming. + +In 2000, development on StructuredTextNG_ ("Next Generation") began at +`Zope Corporation`_ (then Digital Creations). It seems to have many +improvements, but still suffers from many of the problems of classic +StructuredText. + +I decided that a complete rewrite was in order, and even started a +`reStructuredText SourceForge project`_ (now inactive). My +motivations (the 'itches' I aim to 'scratch') are as follows: + +- I need a standard format for inline documentation of the programs I + write. This inline documentation has to be convertible to other + useful formats, such as HTML. I believe many others have the same + need. + +- I believe in the Setext/StructuredText idea and want to help + formalize the standard. However, I feel the current specifications + and implementations have flaws that desperately need fixing. + +- reStructuredText could form part of the foundation for a + documentation extraction and processing system, greatly benefitting + Python. But it is only a part, not the whole. reStructuredText is + a markup language specification and a reference parser + implementation, but it does not aspire to be the entire system. I + don't want reStructuredText or a hypothetical Python documentation + processor to die stillborn because of overambition. + +- Most of all, I want to help ease the documentation chore, the bane + of many a programmer. + +Unfortunately I was sidetracked and stopped working on this project. +In November 2000 I made the time to enumerate the problems of +StructuredText and possible solutions, and complete the first draft of +a specification. This first draft was posted to the Doc-SIG in three +parts: + +- `A Plan for Structured Text`__ +- `Problems With StructuredText`__ +- `reStructuredText: Revised Structured Text Specification`__ + +__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html +__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html +__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html + +In March 2001 a flurry of activity on the Doc-SIG spurred me to +further revise and refine my specification, the result of which you +are now reading. An offshoot of the reStructuredText project has been +the realization that a single markup scheme, no matter how well +thought out, may not be enough. In order to tame the endless debates +on Doc-SIG, a flexible `Docstring Processing System framework`_ needed +to be constructed. This framework has become the more important of +the two projects; reStructuredText_ has found its place as one +possible choice for a single component of the larger framework. + +The project web site and the first project release were rolled out in +June 2001, including posting the second draft of the spec [#spec-2]_ +and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the +Doc-SIG. These documents and the project implementation proceeded to +evolve at a rapid pace. Implementation history details can be found +in the project file, HISTORY.txt_. + +In November 2001, the reStructuredText parser was nearing completion. +Development of the parser continued with the addition of small +convenience features, improvements to the syntax, the filling in of +gaps, and bug fixes. After a long holiday break, in early 2002 most +development moved over to the other Docutils components, the +"Readers", "Writers", and "Transforms". A "standalone" reader +(processes standalone text file documents) was completed in February, +and a basic HTML writer (producing HTML 4.01, using CSS-1) was +completed in early March. + +`PEP 287`_, "reStructuredText Standard Docstring Format", was created +to formally propose reStructuredText as a standard format for Python +docstrings, PEPs, and other files. It was first posted to +comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. + +Version 0.4 of the reStructuredText__ and `Docstring Processing +System`_ projects were released in April 2002. The two projects were +immediately merged, renamed to "Docutils_", and a 0.1 release soon +followed. + +.. __: `reStructuredText SourceForge project`_ + +.. [#spec-2] + - `An Introduction to reStructuredText`__ + - `Problems With StructuredText`__ + - `reStructuredText Markup Specification`__ + - `Python Extensions to the reStructuredText Markup + Specification`__ + + __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html + +.. [#peps-1] + - `PEP 256: Docstring Processing System Framework`__ + - `PEP 258: DPS Generic Implementation Details`__ + - `PEP 257: Docstring Conventions`__ + + Current working versions of the PEPs can be found in + http://docutils.sourceforge.net/spec/, and official versions can be + found in the `master PEP repository`_. + + __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html + __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html + + +.. _Zope Corporation: http://www.zope.com +.. _ZOPE: http://www.zope.org +.. _reStructuredText SourceForge project: + http://structuredtext.sourceforge.net/ +.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ +.. _StructuredTextNG: + http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG +.. _HISTORY.txt: + http://docutils.sourceforge.net/HISTORY.txt +.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.txt +.. _Docstring Processing System framework: + http://docutils.sourceforge.net/spec/pep-0256.txt +.. _comp.lang.python: news:comp.lang.python +.. _Python-dev: http://mail.python.org/pipermail/python-dev/ +.. _Docstring Processing System: http://docstring.sourceforge.net/ +.. _Docutils: http://docutils.sourceforge.net/ +.. _master PEP repository: http://www.python.org/peps/ + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt new file mode 100644 index 000000000..149ef3fd4 --- /dev/null +++ b/docs/ref/rst/restructuredtext.txt @@ -0,0 +1,2344 @@ +======================================= + reStructuredText Markup Specification +======================================= +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +reStructuredText_ is plain text that uses simple and intuitive +constructs to indicate the structure of a document. These constructs +are equally easy to read in raw and processed forms. This document is +itself an example of reStructuredText (raw, if you are reading the +text file, or processed, if you are reading an HTML document, for +example). The reStructuredText parser is a component of Docutils_. + +Simple, implicit markup is used to indicate special constructs, such +as section headings, bullet lists, and emphasis. The markup used is +as minimal and unobtrusive as possible. Less often-used constructs +and extensions to the basic reStructuredText syntax may have more +elaborate or explicit markup. + +reStructuredText is applicable to documents of any length, from the +very small (such as inline program documentation fragments, e.g. +Python docstrings) to the quite large (this document). + +The first section gives a quick overview of the syntax of the +reStructuredText markup by example. A complete specification is given +in the `Syntax Details`_ section. + +`Literal blocks`_ (in which no markup processing is done) are used for +examples throughout this document, to illustrate the plain text +markup. + + +.. contents:: + + +----------------------- + Quick Syntax Overview +----------------------- + +A reStructuredText document is made up of body or block-level +elements, and may be structured into sections. Sections_ are +indicated through title style (underlines & optional overlines). +Sections contain body elements and/or subsections. Some body elements +contain further elements, such as lists containing list items, which +in turn may contain paragraphs and other body elemens. Others, such +as paragraphs, contain text and `inline markup`_ elements. + +Here are examples of `body elements`_: + +- Paragraphs_ (and `inline markup`_):: + + Paragraphs contain text and may contain inline markup: + *emphasis*, **strong emphasis**, `interpreted text`, ``inline + literals``, standalone hyperlinks (http://www.python.org), + external hyperlinks (Python_), internal cross-references + (example_), footnote references ([1]_), citation references + ([CIT2002]_), substitution references (|example|), and _`inline + hyperlink targets`. + + Paragraphs are separated by blank lines and are left-aligned. + +- Five types of lists: + + 1. `Bullet lists`_:: + + - This is a bullet list. + + - Bullets can be "-", "*", or "+". + + 2. `Enumerated lists`_:: + + 1. This is an enumerated list. + + 2. Enumerators may be arabic numbers, letters, or roman + numerals. + + 3. `Definition lists`_:: + + what + Definition lists associate a term with a definition. + + how + The term is a one-line phrase, and the definition is one + or more paragraphs or body elements, indented relative to + the term. + + 4. `Field lists`_:: + + :what: Field lists map field names to field bodies, like + database records. They are often part of an extension + syntax. + + :how: The field marker is a colon, the field name, optional + field arguments, and a colon. + + The field body may contain one or more body elements, + indented relative to the field marker. + + 5. `Option lists`_, for listing command-line options:: + + -a command-line option "a" + -b file options can have arguments + and long descriptions + --long options can be long also + --input=file long options can also have + arguments + /V DOS/VMS-style options too + + There must be at least two spaces between the option and the + description. + +- `Literal blocks`_:: + + Literal blocks are indented, and indicated with a double-colon + ("::") at the end of the preceding paragraph (right here -->):: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +- `Block quotes`_:: + + Block quotes consist of indented body elements: + + This theory, that is mine, is mine. + + Anne Elk (Miss) + +- `Doctest blocks`_:: + + >>> print 'Python-specific usage examples; begun with ">>>"' + Python-specific usage examples; begun with ">>>" + >>> print '(cut and pasted from interactive Python sessions)' + (cut and pasted from interactive Python sessions) + +- Tables_:: + + +------------------------+------------+----------+ + | Header row, column 1 | Header 2 | Header 3 | + +========================+============+==========+ + | body row 1, column 1 | column 2 | column 3 | + +------------------------+------------+----------+ + | body row 2 | Cells may span | + +------------------------+-----------------------+ + +- `Explicit markup blocks`_ all begin with an explicit block marker, + two periods and a space: + + - Footnotes_:: + + .. [1] A footnote contains body elements, consistently + indented by at least 3 spaces. + + - Citations_:: + + .. [CIT2002] Just like a footnote, except the label is + textual. + + - `Hyperlink targets`_:: + + .. _Python: http://www.python.org + + .. _example: + + The "_example" target above points to this paragraph. + + - Directives_:: + + .. image:: mylogo.png + + - `Substitution definitions`_:: + + .. |symbol here| image:: symbol.png + + - Comments_:: + + .. Comments begin with two dots and a space. Anything may + follow, except for the syntax of footnotes/citations, + hyperlink targets, directives, or substitution definitions. + + +---------------- + Syntax Details +---------------- + +Descriptions below list "DTD elements" (XML "generic identifiers") +corresponding to syntax constructs. For details on the hierarchy of +elements, please see `Docutils Document Tree Structure`_ and the +`Generic Plaintext Document Interface DTD`_ XML document type +definition. + + +Whitespace +========== + +Spaces are recommended for indentation_, but tabs may also be used. +Tabs will be converted to spaces. Tab stops are at every 8th column. + +Other whitespace characters (form feeds [chr(12)] and vertical tabs +[chr(11)]) are converted to single spaces before processing. + + +Blank Lines +----------- + +Blank lines are used to separate paragraphs and other elements. +Multiple successive blank lines are equivalent to a single blank line, +except within literal blocks (where all whitespace is preserved). +Blank lines may be omitted when the markup makes element separation +unambiguous, in conjunction with indentation. The first line of a +document is treated as if it is preceded by a blank line, and the last +line of a document is treated as if it is followed by a blank line. + + +Indentation +----------- + +Indentation is used to indicate, and is only significant in +indicating: + +- multi-line contents of list items, +- multiple body elements within a list item (including nested lists), +- the definition part of a definition list item, +- block quotes, +- the extent of literal blocks, and +- the extent of explicit markup blocks. + +Any text whose indentation is less than that of the current level +(i.e., unindented text or "dedents") ends the current level of +indentation. + +Since all indentation is significant, the level of indentation must be +consistent. For example, indentation is the sole markup indicator for +`block quotes`_:: + + This is a top-level paragraph. + + This paragraph belongs to a first-level block quote. + + Paragraph 2 of the first-level block quote. + +Multiple levels of indentation within a block quote will result in +more complex structures:: + + This is a top-level paragraph. + + This paragraph belongs to a first-level block quote. + + This paragraph belongs to a second-level block quote. + + Another top-level paragraph. + + This paragraph belongs to a second-level block quote. + + This paragraph belongs to a first-level block quote. The + second-level block quote above is inside this first-level + block quote. + +When a paragraph or other construct consists of more than one line of +text, the lines must be left-aligned:: + + This is a paragraph. The lines of + this paragraph are aligned at the left. + + This paragraph has problems. The + lines are not left-aligned. In addition + to potential misinterpretation, warning + and/or error messages will be generated + by the parser. + +Several constructs begin with a marker, and the body of the construct +must be indented relative to the marker. For constructs using simple +markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_, +`hyperlink targets`_, directives_, and comments_), the level of +indentation of the body is determined by the position of the first +line of text, which begins on the same line as the marker. For +example, bullet list bodies must be indented by at least two columns +relative to the left edge of the bullet:: + + - This is the first line of a bullet list + item's paragraph. All lines must align + relative to the first line. [1]_ + + This indented paragraph is interpreted + as a block quote. + + Because it is not sufficiently indented, + this paragraph does not belong to the list + item. + + .. [1] Here's a footnote. The second line is aligned + with the beginning of the footnote label. The ".." + marker is what determines the indentation. + +For constructs using complex markers (`field lists`_ and `option +lists`_), where the marker may contain arbitrary text, the indentation +of the first line *after* the marker determines the left edge of the +body. For example, field lists may have very long markers (containing +the field names):: + + :Hello: This field has a short field name, so aligning the field + body with the first line is feasible. + + :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. It may even be preferable not to begin the + body on the same line as the marker. + + +Escaping Mechanism +================== + +The character set universally available to plain text documents, 7-bit +ASCII, is limited. No matter what characters are used for markup, +they will already have multiple meanings in written text. Therefore +markup characters *will* sometimes appear in text **without being +intended as markup**. Any serious markup system requires an escaping +mechanism to override the default meaning of the characters used for +the markup. In reStructuredText we use the backslash, commonly used +as an escaping character in other domains. + +A backslash followed by any character escapes that character. The +escaped character represents the character itself, and is prevented +from playing a role in any markup interpretation. The backslash is +removed from the output. A literal backslash is represented by two +backslashes in a row (the first backslash "escapes" the second, +preventing it being interpreted in an "escaping" role). + +There are two contexts in which backslashes have no special meaning: +literal blocks and inline literals. In these contexts, a single +backslash represents a literal backslash, without having to double up. + +Please note that the reStructuredText specification and parser do not +address the issue of the representation or extraction of text input +(how and in what form the text actually *reaches* the parser). +Backslashes and other characters may serve a character-escaping +purpose in certain contexts and must be dealt with appropriately. For +example, Python uses backslashes in strings to escape certain +characters, but not others. The simplest solution when backslashes +appear in Python docstrings is to use raw docstrings:: + + r"""This is a raw docstring. Backslashes (\) are not touched.""" + + +Reference Names +=============== + +Simple reference names are single words consisting of alphanumerics +plus internal hypens, underscores, and periods; no whitespace or other +characters are allowed. Footnote labels (Footnotes_ & `Footnote +References`_), citation labels (Citations_ & `Citation References`_), +`interpreted text`_ roles, and some `hyperlink references`_ use the +simple reference name syntax. + +Reference names using punctuation or whose names are phrases (two or +more space-separated words) are called "phrase-references". +Phrase-references are expressed by enclosing the phrase in backquotes +and treating the backquoted text as a reference name:: + + Want to learn about `my favorite programming language`_? + + .. _my favorite programming language: http://www.python.org + +Simple reference names may also optionally use backquotes. + +Reference names are whitespace-neutral and case-insensitive. When +resolving reference names internally: + +- whitespace is normalized (one or more spaces, horizontal or vertical + tabs, newlines, carriage returns, or form feeds, are interpreted as + a single space), and + +- case is normalized (all alphabetic characters are converted to + lowercase). + +For example, the following `hyperlink references`_ are equivalent:: + + - `A HYPERLINK`_ + - `a hyperlink`_ + - `A + Hyperlink`_ + +Hyperlinks_, footnotes_, and citations_ all share the same namespace +for reference names. The labels of citations (simple reference names) +and manually-numbered footnotes (numbers) are entered into the same +database as other hyperlink names. This means that a footnote +(defined as "``.. [1]``") which can be referred to by a footnote +reference (``[1]_``), can also be referred to by a plain hyperlink +reference (1_). Of course, each type of reference (hyperlink, +footnote, citation) may be processed and rendered differently. Some +care should be taken to avoid reference name conflicts. + + +Document Structure +================== + +Document +-------- + +DTD element: document. + +The top-level element of a parsed reStructuredText document is the +"document" element. After initial parsing, the document element is a +simple container for a document fragment, consisting of `body +elements`_, transitions_, and sections_, but lacking a document title +or other bibliographic elements. The code that calls the parser may +choose to run one or more optional post-parse transforms_, +rearranging the document fragment into a complete document with a +title and possibly other metadata elements (author, date, etc.; see +`Bibliographic Fields`_). + +Specifically, there is no way to specify a document title and subtitle +explicitly in reStructuredText. Instead, a lone top-level section +title (see Sections_ below) can be treated as the document +title. Similarly, a lone second-level section title immediately after +the "document title" can become the document subtitle. See the +`DocTitle transform`_ for details. + + +Sections +-------- + +DTD elements: section, title. + +Sections are identified through their titles, which are marked up with +adornment: "underlines" below the title text, and, in some cases, +matching "overlines" above the title. An underline/overline is a +single repeated punctuation character that begins in column 1 and +forms a line extending at least as far as the right edge of the title +text. Specifically, an underline/overline character may be any +non-alphanumeric printable 7-bit ASCII character [#]_. An +underline/overline must be at least 4 characters long (to avoid +mistaking ellipses ["..."] for overlines). When an overline is used, +the length and character used must match the underline. There may be +any number of levels of section titles, although some output formats +may have limits (HTML has 6 levels). + +.. [#] The following are all valid section title adornment + characters:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + Some characters are more suitable than others. The following are + recommended:: + + = - ` : ' " ~ ^ _ * + # < > + +Rather than imposing a fixed number and order of section title +adornment styles, the order enforced will be the order as encountered. +The first style encountered will be an outermost title (like HTML H1), +the second style will be a subtitle, the third will be a subsubtitle, +and so on. + +Below are examples of section title styles:: + + =============== + Section Title + =============== + + --------------- + Section Title + --------------- + + Section Title + ============= + + Section Title + ------------- + + Section Title + ````````````` + + Section Title + ''''''''''''' + + Section Title + ............. + + Section Title + ~~~~~~~~~~~~~ + + Section Title + ************* + + Section Title + +++++++++++++ + + Section Title + ^^^^^^^^^^^^^ + +When a title has both an underline and an overline, the title text may +be inset, as in the first two examples above. This is merely +aesthetic and not significant. Underline-only title text may *not* be +inset. + +A blank line after a title is optional. All text blocks up to the +next title of the same or higher level are included in a section (or +subsection, etc.). + +All section title styles need not be used, nor need any specific +section title style be used. However, a document must be consistent +in its use of section titles: once a hierarchy of title styles is +established, sections must use that hierarchy. + +Each section title automatically generates a hyperlink target pointing +to the section. The text of the hyperlink target (the "reference +name") is the same as that of the section title. See `Implicit +Hyperlink Targets`_ for a complete description. + +Sections may contain `body elements`_, transitions_, and nested +sections. + + +Transitions +----------- + +DTD element: transition. + + Instead of subheads, extra space or a type ornament between + paragraphs may be used to mark text divisions or to signal + changes in subject or emphasis. + + (The Chicago Manual of Style, 14th edition, section 1.80) + +Transitions are commonly seen in novels and short fiction, as a gap +spanning one or more lines, with or without a type ornament such as a +row of asterisks. Transitions separate other body elements. A +transition should not begin or end a section or document, nor should +two transitions be immediately adjacent. + +The syntax for a transition marker is a horizontal line of 4 or more +repeated punctuation characters. The syntax is the same as section +title underlines without title text. Transition markers require blank +lines before and after:: + + Para. + + ---------- + + Para. + +Unlike section title underlines, no hierarchy of transition markers is +enforced, nor do differences in transition markers accomplish +anything. It is recommended that a single consistent style be used. + +The processing system is free to render transitions in output in any +way it likes. For example, horizontal rules (``<HR>``) in HTML output +would be an obvious choice. + + +Body Elements +============= + +Paragraphs +---------- + +DTD element: paragraph. + +Paragraphs consist of blocks of left-aligned text with no markup +indicating any other body element. Blank lines separate paragraphs +from each other and from other body elements. Paragraphs may contain +`inline markup`_. + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | | + +------------------------------+ + + +------------------------------+ + | paragraph | + | | + +------------------------------+ + + +Bullet Lists +------------ + +DTD elements: bullet_list, list_item. + +A text block which begins with a "-", "*", or "+", followed by +whitespace, is a bullet list item (a.k.a. "unordered" list item). +List item bodies must be left-aligned and indented relative to the +bullet; the text immediately after the bullet determines the +indentation. For example:: + + - This is the first bullet list item. The blank line above the + first list item is required; blank lines between list items + (such as below this paragraph) are optional. + + - This is the first paragraph in the second item in the list. + + This is the second paragraph in the second item in the list. + The blank line above this paragraph is required. The left edge + of this paragraph lines up with the paragraph above, both + indented relative to the bullet. + + - This is a sublist. The bullet lines up with the left edge of + the text blocks above. A sublist is a new list so requires a + blank line above and below. + + - This is the third item of the main list. + + This paragraph is not part of the list. + +Here are examples of **incorrectly** formatted bullet lists:: + + - This first line is fine. + A blank line is required between list items and paragraphs. + (Warning) + + - The following line appears to be a new sublist, but it is not: + - This is a paragraph contination, not a sublist (since there's + no blank line). This line is also incorrectly indented. + - Warnings may be issued by the implementation. + +Syntax diagram:: + + +------+-----------------------+ + | "- " | list item | + +------| (body elements)+ | + +-----------------------+ + + +Enumerated Lists +---------------- + +DTD elements: enumerated_list, list_item. + +Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, +but use enumerators instead of bullets. An enumerator consists of an +enumeration sequence member and formatting, followed by whitespace. +The following enumeration sequences are recognized: + +- arabic numerals: 1, 2, 3, ... (no upper limit). +- uppercase alphabet characters: A, B, C, ..., Z. +- lower-case alphabet characters: a, b, c, ..., z. +- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). +- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). + +The following formatting types are recognized: + +- suffixed with a period: "1.", "A.", "a.", "I.", "i.". +- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". +- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". + +A system message will be generated for each of the following cases: + +- The enumerators do not all have the same format and sequence type. + +- The enumerators are not in sequence (i.e., "1.", "3." generates a + level-1 [info] system message and produces two separate lists). + +It is recommended that the enumerator of the first list item be +ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values +will be recognized, they may not be supported by the output format. + +Lists using Roman numerals must begin with "I"/"i" or a +multi-character value, such as "II" or "XV". Any other +single-character Roman numeral ("V", "X", etc.) will be interpreted as +a letter of the alphabet, not as a Roman numeral. Likewise, lists +using letters of the alphabet may not begin with "I"/"i", since these +are recognized as Roman numeral 1. + +Nested enumerated lists must be created with indentation. For +example:: + + 1. Item 1. + + a) Item 1a. + b) Item 1b. + +Example syntax diagram:: + + +-------+----------------------+ + | "1. " | list item | + +-------| (body elements)+ | + +----------------------+ + + +Definition Lists +---------------- + +DTD elements: definition_list, definition_list_item, term, classifier, +definition. + +Each definition list item contains a term, an optional classifier, and +a definition. A term is a simple one-line word or phrase. An +optional classifier may follow the term on the same line, after " : " +(space, colon, space). A definition is a block indented relative to +the term, and may contain multiple paragraphs and other body elements. +There may be no blank line between a term and a definition (this +distinguishes definition lists from `block quotes`_). Blank lines are +required before the first and after the last definition list item, but +are optional in-between. For example:: + + term 1 + Definition 1. + + term 2 + Definition 2, paragraph 1. + + Definition 2, paragraph 2. + + term 3 : classifier + Definition 3. + +A definition list may be used in various ways, including: + +- As a dictionary or glossary. The term is the word itself, a + classifier may be used to indicate the usage of the term (noun, + verb, etc.), and the definition follows. + +- To describe program variables. The term is the variable name, a + classifier may be used to indicate the type of the variable (string, + integer, etc.), and the definition describes the variable's use in + the program. This usage of definition lists supports the classifier + syntax of Grouch_, a system for describing and enforcing a Python + object schema. + +Syntax diagram:: + + +---------------------------+ + | term [ " : " classifier ] | + +--+------------------------+--+ + | definition | + | (body elements)+ | + +---------------------------+ + + +Field Lists +----------- + +DTD elements: field_list, field, field_name, field_argument, +field_body. + +Field lists are mappings from field names to field bodies, modeled on +RFC822_ headers. A field name is made up of one or more letters, +numbers, and punctuation, except colons (":") and whitespace. Field +names are case-insensitive. There may be additional data separated +from the field name, called field arguments. The field name and +optional field argument(s), along with a single colon prefix and +suffix, together form the field marker. The field marker is followed +by whitespace and the field body. The field body may contain multiple +body elements, indented relative to the field marker. The first line +after the field name marker determines the indentation of the field +body. For example:: + + :Date: 2001-08-16 + :Version: 1 + :Authors: - Me + - Myself + - I + :Indentation: Since the field marker may be quite long, the second + and subsequent lines of the field body do not have to line up + with the first line, but they must be indented relative to the + field name marker, and they must line up with each other. + :Parameter i: integer + +Field arguments are separated from the field name and each other by +whitespace, and may not contain colons (":"). The interpretation of +field arguments is up to the application. For example:: + + :name1 word number=1: + Both "word" and "number=1" are single words. + +The syntax for field arguments may be extended in the future. For +example, quoted phrases may be treated as a single argument, and +direct support for the "name=value" syntax may be added. + +Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts; they are often +used as part of an extension syntax. See `Bibliographic Fields`_ +below for one example, or the "image" directive in `reStructuredText +Directives`_ for another. + +Standard RFC822 headers cannot be used for this construct because they +are ambiguous. A word followed by a colon at the beginning of a line +is common in written text. However, in well-defined contexts such as +when a field list invariably occurs at the beginning of a document +(PEPs and email messages), standard RFC822 headers could be used. + +Syntax diagram (simplified):: + + +------------------------------+------------+ + | ":" name (" " argument)* ":" | field body | + +-------+----------------------+ | + | (body elements)+ | + +-----------------------------------+ + + +Bibliographic Fields +```````````````````` + +DTD elements: docinfo, author, authors, organization, contact, +version, status, date, copyright, topic. + +When a field list is the first non-comment element in a document +(after the document title, if there is one), it may have certain +specific fields transformed to document bibliographic data. This +bibliographic data corresponds to the front matter of a book, such as +the title page and copyright page. + +Certain field names (listed below) are recognized and transformed to +the corresponding DTD elements, most becoming child elements of the +"docinfo" element. No ordering is required of these fields, although +they may be rearranged to fit the document structure, as noted. +Unless otherwise indicated in the list below, each of the +bibliographic elements' field bodies may contain a single paragraph +only. Field bodies may be checked for `RCS keywords`_ and cleaned up. +Any unrecognized fields will remain in a generic field list in the +document body. + +The registered bibliographic field names and their corresponding DTD +elements are as follows: + +- Field name "Author": author element. +- "Authors": authors. May contain either: a single paragraph + consisting of a list of authors, separated by ";" or ","; or a + bullet list whose elements each contain a single paragraph per + author. +- "Organization": organization. +- "Contact": contact. +- "Version": version. +- "Status": status. +- "Date": date. +- "Copyright": copyright. +- "Abstract": topic. May contain arbitrary body elements. Only one + abstract is allowed. The abstract becomes a topic element with + title "Abstract" (or language equivalent) immediately following the + docinfo element. + +This field-name-to-element mapping can be extended, or replaced for +other languages. See the `DocInfo transform`_ implementation +documentation for details. + + +RCS Keywords +```````````` + +`Bibliographic fields`_ recognized by the parser are normally checked +for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be +entered into source files as "$keyword$", and once stored under RCS or +CVS [#]_, they are expanded to "$keyword: expansion text $". For +example, a "Status" field will be transformed to a "status" element:: + + :Status: $keyword: expansion text $ + +.. [#] Revision Control System. +.. [#] RCS keyword processing can be turned off (unimplemented). +.. [#] Concurrent Versions System. CVS uses the same keywords as RCS. + +Processed, the "status" element's text will become simply "expansion +text". The dollar sign delimiters and leading RCS keyword name are +removed. + +The RCS keyword processing only kicks in when all of these conditions +hold: + +1. The field list is in bibliographic context (first non-comment + contstruct in the document, after a document title if there is + one). + +2. The field name is a recognized bibliographic field name. + +3. The sole contents of the field is an expanded RCS keyword, of the + form "$Keyword: data $". + + +Option Lists +------------ + +DTD elements: option_list, option_list_item, option_group, option, +option_string, option_argument, description. + +Option lists are two-column lists of command-line options and +descriptions, documenting a program's options. For example:: + + -a Output all. + -b Output both (this description is + quite long). + -c arg Output just arg. + --long Output all day long. + + -p This option has two paragraphs in the description. + This is the first. + + This is the second. Blank lines may be omitted between + options (as above) or left in (as here and below). + + --very-long-option A VMS-syle option. Note the adjustment for + the required two spaces. + + --an-even-longer-option + The description can also start on the next line. + + -2, --two This option has two variants. + + -f FILE, --file=FILE These two options are synonyms; both have + arguments. + + /V A VMS/DOS-style option. + +There are several types of options recognized by reStructuredText: + +- Short POSIX options consist of one dash and an option letter. +- Long POSIX options consist of two dashes and an option word; some + systems use a single dash. +- Old GNU-style "plus" options consist of one plus and an option + letter ("plus" options are deprecated now, their use discouraged). +- DOS/VMS options consist of a slash and an option letter or word. + +Please note that both POSIX-style and DOS/VMS-style options may be +used by DOS or Windows software. These and other variations are +sometimes used mixed together. The names above have been chosen for +convenience only. + +The syntax for short and long POSIX options is based on the syntax +supported by Python's getopt.py_ module, which implements an option +parser similar to the `GNU libc getopt_long()`_ function but with some +restrictions. There are many variant option systems, and +reStructuredText option lists do not support all of them. + +Although long POSIX and DOS/VMS option words may be allowed to be +truncated by the operating system or the application when used on the +command line, reStructuredText option lists do not show or support +this with any special syntax. The complete option word should be +given, supported by notes about truncation if and when applicable. + +Options may be followed by an argument placeholder, whose role and +syntax should be explained in the description text. Either a space or +an equals sign may be used as a delimiter between options and option +argument placeholders. + +Multiple option "synonyms" may be listed, sharing a single +description. They must be separated by comma-space. + +There must be at least two spaces between the option(s) and the +description. The description may contain multiple body elements. The +first line after the option marker determines the indentation of the +description. As with other types of lists, blank lines are required +before the first option list item and after the last, but are optional +between option entries. + +Syntax diagram (simplified):: + + +----------------------------+-------------+ + | option [" " argument] " " | description | + +-------+--------------------+ | + | (body elements)+ | + +----------------------------------+ + + +Literal Blocks +-------------- + +DTD element: literal_block. + +A paragraph consisting of two colons ("::") signifies that all +following **indented** text blocks comprise a literal block. No +markup processing is done within a literal block. It is left as-is, +and is typically rendered in a monospaced typeface:: + + This is a typical paragraph. A literal block follows. + + :: + + for a in [5,4,3,2,1]: # this is program code, shown as-is + print a + print "it's..." + # a literal block continues until the indentation ends + + This text has returned to the indentation of the first paragraph, + is outside of the literal block, and is therefore treated as an + ordinary paragraph. + +The paragraph containing only "::" will be completely removed from the +output; no empty paragraph will remain. + +As a convenience, the "::" is recognized at the end of any paragraph. +If immediately preceded by whitespace, both colons will be removed +from the output (this is the "partially minimized" form). When text +immediately precedes the "::", *one* colon will be removed from the +output, leaving only one colon visible (i.e., "::" will be replaced by +":"; this is the "fully minimized" form). + +In other words, these are all equivalent (please pay attention to the +colons after "Paragraph"): + +1. Expanded form:: + + Paragraph: + + :: + + Literal block + +2. Partially minimized form:: + + Paragraph: :: + + Literal block + +3. Fully minimized form:: + + Paragraph:: + + Literal block + +The minimum leading whitespace will be removed from each line of the +literal block. Other than that, all whitespace (including line +breaks) is preserved. Blank lines are required before and after a +literal block, but these blank lines are not included as part of the +literal block. + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | (ends with "::") | + +------------------------------+ + +---------------------------+ + | literal block | + +---------------------------+ + + +Block Quotes +------------ + +DTD element: block_quote. + +A text block that is indented relative to the preceding text, without +markup indicating it to be a literal block, is a block quote. All +markup processing (for body elements and inline markup) continues +within the block quote:: + + This is an ordinary paragraph, introducing a block quote. + + "It is my business to know things. That is my trade." + + -- Sherlock Holmes + +Blank lines are required before and after a block quote, but these +blank lines are not included as part of the block quote. + +Syntax diagram:: + + +------------------------------+ + | (current level of | + | indentation) | + +------------------------------+ + +---------------------------+ + | block quote | + | (body elements)+ | + +---------------------------+ + + +Doctest Blocks +-------------- + +DTD element: doctest_block. + +Doctest blocks are interactive Python sessions cut-and-pasted into +docstrings. They are meant to illustrate usage by example, and +provide an elegant and powerful testing environment via the `doctest +module`_ in the Python standard library. + +Doctest blocks are text blocks which begin with ``">>> "``, the Python +interactive interpreter main prompt, and end with a blank line. +Doctest blocks are treated as a special case of literal blocks, +without requiring the literal block syntax. If both are present, the +literal block syntax takes priority over Doctest block syntax:: + + This is an ordinary paragraph. + + >>> print 'this is a Doctest block' + this is a Doctest block + + The following is a literal block:: + + >>> This is not recognized as a doctest block by + reStructuredText. It *will* be recognized by the doctest + module, though! + +Indentation is not required for doctest blocks. + + +Tables +------ + +DTD elements: table, tgroup, colspec, thead, tbody, row, entry. + +Tables are described with a visual outline made up of the characters +"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines +(row separators). The equals sign ("=") may be used to separate +optional header rows from the table body. The vertical bar ("|") is +used for vertical lines (column separators). The plus sign ("+") is +used for intersections of horizontal and vertical lines. + +Each table cell is treated as a miniature document; the top and bottom +cell boundaries act as delimiting blank lines. Each cell contains +zero or more body elements. Cell contents may include left and/or +right margins, which are removed before processing. Example:: + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | Cells may span columns. | + +------------------------+------------+---------------------+ + | body row 3 | Cells may | - Table cells | + +------------------------+ span rows. | - contain | + | body row 4 | | - body elements. | + +------------------------+------------+---------------------+ + +As with other body elements, blank lines are required before and after +tables. Tables' left edges should align with the left edge of +preceding text blocks; otherwise, the table is considered to be part +of a block quote. + +Some care must be taken with tables to avoid undesired interactions +with cell text in rare cases. For example, the following table +contains a cell in row 2 spanning from column 2 to column 4:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +If a vertical bar is used in the text of that cell, it could have +unintended effects if accidentally aligned with column boundaries:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +Several solutions are possible. All that is needed is to break the +continuity of the cell outline rectangle. One possibility is to shift +the text by adding an extra space before:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + +Another possibility is to add an extra line to row 2:: + + +--------------+----------+-----------+-----------+ + | row 1, col 1 | column 2 | column 3 | column 4 | + +--------------+----------+-----------+-----------+ + | row 2 | Use the command ``ls | more``. | + | | | + +--------------+----------+-----------+-----------+ + | row 3 | | | | + +--------------+----------+-----------+-----------+ + + +Explicit Markup Blocks +---------------------- + +An explicit markup block is a text block: + +- whose first line begins with ".." followed by whitespace (the + "explicit markup start"), +- whose second and subsequent lines (if any) are indented relative to + the first, and +- which ends before an unindented line. + +Explicit markup blocks are analogous to bullet list items, with ".." +as the bullet. The text immediately after the explicit markup start +determines the indentation of the block body. Blank lines are +required between explicit markup blocks and other elements, but are +optional between explicit markup blocks where unambiguous. + +The explicit markup syntax is used for footnotes, citations, hyperlink +targets, directives, and comments. + + +Footnotes +````````` + +DTD elements: footnote, label. + +Each footnote consists of an explicit markup start (".. "), a left +square bracket, the footnote label, a right square bracket, and +whitespace, followed by indented body elements. A footnote label can +be: + +- a whole decimal number consisting of one or more digits, + +- a single "#" (denoting `auto-numbered footnotes`_), + +- a "#" followed by a simple reference name (an `autonumber label`_), + or + +- a single "*" (denoting `auto-symbol footnotes`_). + +If the first body element within a footnote is a simple paragraph, it +may begin on the same line as the footnote label. Other elements must +begin on a new line, consistently indented (by at least 3 spaces) and +left-aligned. + +Footnotes may occur anywhere in the document, not only at the end. +Where or how they appear in the processed output depends on the +processing system. + +Here is a manually numbered footnote:: + + .. [1] Body elements go here. + +Each footnote automatically generates a hyperlink target pointing to +itself. The text of the hyperlink target name is the same as that of +the footnote label. `Auto-numbered footnotes`_ generate a number as +their footnote label and reference name. See `Implicit Hyperlink +Targets`_ for a complete description of the mechanism. + +Syntax diagram:: + + +-------+-------------------------+ + | ".. " | "[" label "]" footnote | + +-------+ | + | (body elements)+ | + +-------------------------+ + + +Auto-Numbered Footnotes +....................... + +A number sign ("#") may be used as the first character of a footnote +label to request automatic numbering of the footnote or footnote +reference. + +The first footnote to request automatic numbering is assigned the +label "1", the second is assigned the label "2", and so on (assuming +there are no manually numbered footnotes present; see `Mixed Manual +and Auto-Numbered Footnotes`_ below). A footnote which has +automatically received a label "1" generates an implicit hyperlink +target with name "1", just as if the label was explicitly specified. + +.. _autonumber label: `autonumber labels`_ + +A footnote may specify a label explicitly while at the same time +requesting automatic numbering: ``[#label]``. These labels are called +_`autonumber labels`. Autonumber labels do two things: + +- On the footnote itself, they generate a hyperlink target whose name + is the autonumber label (doesn't include the "#"). + +- They allow an automatically numbered footnote to be referred to more + than once, as a footnote reference or hyperlink reference. For + example:: + + If [#note]_ is the first footnote reference, it will show up as + "[1]". We can refer to it again as [#note]_ and again see + "[1]". We can also refer to it as note_ (an ordinary internal + hyperlink reference). + + .. [#note] This is the footnote labeled "note". + +The numbering is determined by the order of the footnotes, not by the +order of the references. For footnote references without autonumber +labels (``[#]_``), the footnotes and footnote references must be in +the same relative order but need not alternate in lock-step. For +example:: + + [#]_ is a reference to footnote 1, and [#]_ is a reference to + footnote 2. + + .. [#] This is footnote 1. + .. [#] This is footnote 2. + .. [#] This is footnote 3. + + [#]_ is a reference to footnote 3. + +Special care must be taken if footnotes themselves contain +auto-numbered footnote references, or if multiple references are made +in close proximity. Footnotes and references are noted in the order +they are encountered in the document, which is not necessarily the +same as the order in which a person would read them. + + +Auto-Symbol Footnotes +..................... + +An asterisk ("*") may be used for footnote labels to request automatic +symbol generation for footnotes and footnote references. The asterisk +may be the only character in the label. For example:: + + Here is a symbolic footnote reference: [*]_. + + .. [*] This is the footnote. + +A transform will insert symbols as labels into corresponding footnotes +and footnote references. + +The standard Docutils system uses the following symbols for footnote +marks [#]_: + +- asterisk/star ("*") +- dagger (HTML character entity "†") +- double dagger ("‡") +- section mark ("§") +- pilcrow or paragraph mark ("¶") +- number sign ("#") +- spade suit ("♠") +- heart suit ("♥") +- diamond suit ("♦") +- club suit ("♣") + +.. [#] This list was inspired by the list of symbols for "Note + Reference Marks" in The Chicago Manual of Style, 14th edition, + section 12.51. "Parallels" ("\|\|") were given in CMoS instead of + the pilcrow. The last four symbols (the card suits) were added + arbitrarily. + +If more than ten symbols are required, the same sequence will be +reused, doubled and then tripled, and so on ("**" etc.). + + +Mixed Manual and Auto-Numbered Footnotes +........................................ + +Manual and automatic footnote numbering may both be used within a +single document, although the results may not be expected. Manual +numbering takes priority. Only unused footnote numbers are assigned +to auto-numbered footnotes. The following example should be +illustrative:: + + [2]_ will be "2" (manually numbered), + [#]_ will be "3" (anonymous auto-numbered), and + [#label]_ will be "1" (labeled auto-numbered). + + .. [2] This footnote is labeled manually, so its number is fixed. + + .. [#label] This autonumber-labeled footnote will be labeled "1". + It is the first auto-numbered footnote and no other footnote + with label "1" exists. The order of the footnotes is used to + determine numbering, not the order of the footnote references. + + .. [#] This footnote will be labeled "3". It is the second + auto-numbered footnote, but footnote label "2" is already used. + + +Citations +````````` + +Citations are identical to footnotes except that they use only +non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation +labels are simple `reference names`_ (case-insensitive single words +consisting of alphanumerics plus internal hyphens, underscores, and +periods; no whitespace). Citations may be rendered separately and +differently from footnotes. For example:: + + Here is a citation reference: [CIT2002]_. + + .. [CIT2002] This is the citation. It's just like a footnote, + except the label is textual. + + +.. _hyperlinks: + +Hyperlink Targets +````````````````` + +DTD element: target. + +These are also called _`explicit hyperlink targets`, to differentiate +them from `implicit hyperlink targets`_ defined below. + +Hyperlink targets identify a location within or outside of a document, +which may be linked to by `hyperlink references`_. + +Hyperlink targets may be named or anonymous. Named hyperlink targets +consist of an explicit markup start (".. "), an underscore, the +reference name (no trailing underscore), a colon, whitespace, and a +link block:: + + .. _hyperlink-name: link-block + +Reference names are whitespace-neutral and case-insensitive. See +`Reference Names`_ for details and examples. + +Anonymous hyperlink targets consist of an explicit markup start +(".. "), two underscores, a colon, whitespace, and a link block; there +is no reference name:: + + .. __: anonymous-hyperlink-target-link-block + +An alternate syntax for anonymous hyperlinks consists of two +underscores, a space, and a link block:: + + __ anonymous-hyperlink-target-link-block + +See `Anonymous Hyperlinks`_ below. + +There are three types of hyperlink targets: internal, external, and +indirect. + +1. _`Internal hyperlink targets` have empty link blocks. They provide + an end point allowing a hyperlink to connect one place to another + within a document. An internal hyperlink target points to the + element following the target. For example:: + + Clicking on this internal hyperlink will take us to the target_ + below. + + .. _target: + + The hyperlink target above points to this paragraph. + + Internal hyperlink targets may be "chained". Multiple adjacent + internal hyperlink targets all point to the same element:: + + .. _target1: + .. _target2: + + The targets "target1" and "target2" are synonyms; they both + point to this paragraph. + + If the element "pointed to" is an external hyperlink target (with a + URI in its link block; see #2 below) the URI from the external + hyperlink target is propagated to the internal hyperlink targets; + they will all "point to" the same URI. There is no need to + duplicate a URI. For example, all three of the following hyperlink + targets refer to the same URI:: + + .. _Python DOC-SIG mailing list archive: + .. _archive: + .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ + + An inline form of internal hyperlink target is available; see + `Inline Hyperlink Targets`_. + +2. _`External hyperlink targets` have an absolute or relative URI in + their link blocks. For example, take the following input:: + + See the Python_ home page for info. + + .. _Python: http://www.python.org + + After processing into HTML, the hyperlink might be expressed as:: + + See the <A HREF="http://www.python.org">Python</A> home page + for info. + + An external hyperlink's URI may begin on the same line as the + explicit markup start and target name, or it may begin in an + indented text block immediately following, with no intervening + blank lines. If there are multiple lines in the link block, they + are stripped of leading and trailing whitespace and concatenated. + The following external hyperlink targets are equivalent:: + + .. _one-liner: http://docutils.sourceforge.net/rst.html + + .. _starts-on-this-line: http:// + docutils.sourceforge.net/rst.html + + .. _entirely-below: + http://docutils. + sourceforge.net/rst.html + + If an external hyperlink target's URI contains an underscore as its + last character, it must be escaped to avoid being mistaken for an + indirect hyperlink target:: + + This link_ refers to a file called ``underscore_``. + + .. _link: underscore\_ + +3. _`Indirect hyperlink targets` have a hyperlink reference in their + link blocks. In the following example, target "one" indirectly + references whatever target "two" references, and target "two" + references target "three", an internal hyperlink target. In + effect, all three reference the same thing:: + + .. _one: two_ + .. _two: three_ + .. _three: + + Just as with `hyperlink references`_ anywhere else in a document, + if a phrase-reference is used in the link block it must be enclosed + in backquotes. As with `external hyperlink targets`_, the link + block of an indirect hyperlink target may begin on the same line as + the explicit markup start or the next line. It may also be split + over multiple lines, in which case the lines are joined with + whitespace before being normalized. + + For example, the following indirect hyperlink targets are + equivalent:: + + .. _one-liner: `A HYPERLINK`_ + .. _entirely-below: + `a hyperlink`_ + .. _split: `A + Hyperlink`_ + +If a reference name contains a colon followed by whitespace, either: + +- the phrase must be enclosed in backquotes:: + + .. _`FAQTS: Computers: Programming: Languages: Python`: + http://python.faqts.com/ + +- or the colon(s) must be backslash-escaped in the link target:: + + .. _Chapter One\: "Tadpole Days": + + It's not easy being green... + +See `Implicit Hyperlink Targets`_ below for the resolution of +duplicate reference names. + +Syntax diagram:: + + +-------+----------------------+ + | ".. " | "_" name ":" link | + +-------+ block | + | | + +----------------------+ + + +Anonymous Hyperlinks +.................... + +The `World Wide Web Consortium`_ recommends in its `HTML Techniques +for Web Content Accessibility Guidelines`_ that authors should +"clearly identify the target of each link." Hyperlink references +should be as verbose as possible, but duplicating a verbose hyperlink +name in the target is onerous and error-prone. Anonymous hyperlinks +are designed to allow convenient verbose hyperlink references, and are +analogous to `Auto-Numbered Footnotes`_. They are particularly useful +in short or one-off documents. + +Anonymous `hyperlink references`_ are specified with two underscores +instead of one:: + + See `the web site of my favorite programming language`__. + +Anonymous targets begin with ".. __:"; no reference name is required +or allowed:: + + .. __: http://www.python.org + +As a convenient alternative, anonymous targets may begin with "__" +only:: + + __ http://www.python.org + +The reference name of the reference is not used to match the reference +to its target. Instead, the order of anonymous hyperlink references +and targets within the document is significant: the first anonymous +reference will link to the first anonymous target. The number of +anonymous hyperlink references in a document must match the number of +anonymous targets. + + +Directives +`````````` + +DTD elements: depend on the directive. + +Directives are indicated by an explicit markup start (".. ") followed +by the directive type, two colons, and whitespace. Directive types +are case-insensitive single words (alphanumerics plus internal +hyphens, underscores, and periods; no whitespace). Two colons are +used after the directive type for these reasons: + +- To avoid clashes with common comment text like:: + + .. Danger: modify at your own risk! + +- If an implementation of reStructuredText does not recognize a + directive (i.e., the directive-handler is not installed), the entire + directive block (including the directive itself) will be treated as + a literal block, and a level-3 (error) system message generated. + Thus "::" is a natural choice. + +Any text on the first line after the directive indicator is directive +data. The interpretation of directive data is up to the directive +code. Directive data may be interpreted as arguments to the +directive, or simply as the first line of the directive's text block. + +Actions taken in response to directives and the interpretation of text +in the directive block or subsequent text block(s) are +directive-dependent. Indented text following a directive may be +interpreted as a directive block. Simple directives may not require +any text beyond the directive data (if that), and will not process any +following indented text. + +Directives which have been implemented and registered in the reference +reStructuredText parser are described in the `reStructuredText +Directives`_ document. Below are examples of implemented directives. + +Directives are meant for the arbitrary processing of their contents +(the directive data & text block), which can be transformed into +something possibly unrelated to the original text. Directives are +used as an extension mechanism for reStructuredText, a way of adding +support for new constructs without adding new syntax. For example, +here's how an image may be placed:: + + .. image:: mylogo.png + +A figure (a graphic with a caption) may placed like this:: + + .. figure:: larch.png + The larch. + +An admonition (note, caution, etc.) contains other body elements:: + + .. note:: This is a paragraph + + - Here is a bullet list. + +It may also be possible for directives to be used as pragmas, to +modify the behavior of the parser, such as to experiment with +alternate syntax. There is no parser support for this functionality +at present; if a reasonable need for pragma directives is found, they +may be supported. + +Directives normally do not survive as "directive" elements past the +parsing stage; they are a *parser construct* only, and have no +intrinsic meaning outside of reStructuredText. Instead, the parser +will transform recognized directives into (possibly specialized) +document elements. Unknown directives will trigger level-3 (error) +system messages. + +Syntax diagram:: + + +-------+--------------------------+ + | ".. " | directive type "::" data | + +-------+ directive block | + | | + +--------------------------+ + + +Substitution Definitions +```````````````````````` + +DTD element: substitution_definition. + +Substitution definitions are indicated by an explicit markup start +(".. ") followed by a vertical bar, the substitution text, another +vertical bar, whitespace, and the definition block. Substitution text +may not begin or end with whitespace. A substitution definition block +contains an embedded inline-compatible directive (without the leading +".. "), such as an image. For example:: + + The |biohazard| symbol must be used on containers used to + dispose of medical waste. + + .. |biohazard| image:: biohazard.png + +It is an error for a substitution definition block to directly or +indirectly contain a circular substitution reference. + +`Substitution references`_ are replaced in-line by the processed +contents of the corresponding definition (linked by matching +substitution text). Substitution definitions allow the power and +flexibility of block-level directives_ to be shared by inline text. +They are a way to include arbitrarily complex inline structures within +text, while keeping the details out of the flow of text. They are the +equivalent of SGML/XML's named entities or programming language +macros. + +Without the substitution mechanism, every time someone wants an +application-specific new inline structure, they would have to petition +for a syntax change. In combination with existing directive syntax, +any inline structure can be coded without new syntax (except possibly +a new directive). + +Syntax diagram:: + + +-------+-----------------------------------------------------+ + | ".. " | "|" substitution text "| " directive type "::" data | + +-------+ directive block | + | | + +-----------------------------------------------------+ + +Following are some use cases for the substitution mechanism. Please +note that most of the embedded directives shown are examples only and +have not been implemented. + +Objects + Substitution references may be used to associate ambiguous text + with a unique object identifier. + + For example, many sites may wish to implement an inline "user" + directive:: + + |Michael| and |Jon| are our widget-wranglers. + + .. |Michael| user:: mjones + .. |Jon| user:: jhl + + Depending on the needs of the site, this may be used to index the + document for later searching, to hyperlink the inline text in + various ways (mailto, homepage, mouseover Javascript with profile + and contact information, etc.), or to customize presentation of + the text (include username in the inline text, include an icon + image with a link next to the text, make the text bold or a + different color, etc.). + + The same approach can be used in documents which frequently refer + to a particular type of objects with unique identifiers but + ambiguous common names. Movies, albums, books, photos, court + cases, and laws are possible. For example:: + + |The Transparent Society| offers a fascinating alternate view + on privacy issues. + + .. |The Transparent Society| book:: isbn=0738201448 + + Classes or functions, in contexts where the module or class names + are unclear and/or interpreted text cannot be used, are another + possibility:: + + 4XSLT has the convenience method |runString|, so you don't + have to mess with DOM objects if all you want is the + transformed output. + + .. |runString| function:: module=xml.xslt class=Processor + +Images + Images are a common use for substitution references:: + + West led the |H| 3, covered by dummy's |H| Q, East's |H| K, + and trumped in hand with the |S| 2. + + .. |H| image:: /images/heart.png + :height: 11 + :width: 11 + .. |S| image:: /images/spade.png + :height: 11 + :width: 11 + + * |Red light| means stop. + * |Green light| means go. + * |Yellow light| means go really fast. + + .. |Red light| image:: red_light.png + .. |Green light| image:: green_light.png + .. |Yellow light| image:: yellow_light.png + + |-><-| is the official symbol of POEE_. + + .. |-><-| image:: discord.png + .. _POEE: http://www.poee.org/ + + The "image" directive has been implemented. + +Styles [#]_ + Substitution references may be used to associate inline text with + an externally defined presentation style:: + + Even |the text in Texas| is big. + + .. |the text in Texas| style:: big + + The style name may be meaningful in the context of some particular + output format (CSS class name for HTML output, LaTeX style name + for LaTeX, etc), or may be ignored for other output formats (often + for plain text). + + .. @@@ This needs to be rethought & rewritten or removed: + + Interpreted text is unsuitable for this purpose because the set + of style names cannot be predefined - it is the domain of the + content author, not the author of the parser and output + formatter - and there is no way to associate a stylename + argument with an interpreted text style role. Also, it may be + desirable to use the same mechanism for styling blocks:: + + .. style:: motto + At Bob's Underwear Shop, we'll do anything to get in + your pants. + + .. style:: disclaimer + All rights reversed. Reprint what you like. + + .. [#] There may be sufficient need for a "style" mechanism to + warrant simpler syntax such as an extension to the interpreted + text role syntax. The substitution mechanism is cumbersome for + simple text styling. + +Templates + Inline markup may be used for later processing by a template + engine. For example, a Zope_ author might write:: + + Welcome back, |name|! + + .. |name| tal:: replace user/getUserName + + After processing, this ZPT output would result:: + + Welcome back, + <span tal:replace="user/getUserName">name</span>! + + Zope would then transform this to something like "Welcome back, + David!" during a session with an actual user. + +Replacement text + The substitution mechanism may be used for simple macro + substitution. This may be appropriate when the replacement text + is repeated many times throughout one or more documents, + especially if it may need to change later. A short example is + unavoidably contrived:: + + |RST| is a little annoying to type over and over, especially + when writing about |RST| itself, and spelling out the + bicapitalized word |RST| every time isn't really necessary for + |RST| source readability. + + .. |RST| replace:: reStructuredText_ + .. _reStructuredText: http://docutils.sourceforge.net/rst.html + + Substitution is also appropriate when the replacement text cannot + be represented using other inline constructs, or is obtrusively + long:: + + But still, that's nothing compared to a name like + |j2ee-cas|__. + + .. |j2ee-cas| replace:: + the Java `TM`:super: 2 Platform, Enterprise Edition Client + Access Services + __ http://developer.java.sun.com/developer/earlyAccess/ + j2eecas/ + + +Comments +```````` + +DTD element: comment. + +Arbitrary indented text may follow the explicit markup start and will +be processed as a comment element. No further processing is done on +the comment block text; a comment contains a single "text blob". +Depending on the output formatter, comments may be removed from the +processed output. The only restriction on comments is that they not +use the same syntax as directives, footnotes, citations, or hyperlink +targets. + +A explicit markup start followed by a blank line and nothing else +(apart from whitespace) is an "empty comment". It serves to terminate +a preceding construct, and does **not** consume any indented text +following. To have a block quote follow a list or any indented +construct, insert an unindented empty comment in-between. + +Syntax diagram:: + + +-------+----------------------+ + | ".. " | comment | + +-------+ block | + | | + +----------------------+ + + +Implicit Hyperlink Targets +========================== + +Implicit hyperlink targets are generated by section titles, footnotes, +and citations, and may also be generated by extension constructs. +Implicit hyperlink targets otherwise behave identically to explicit +`hyperlink targets`_. + +Problems of ambiguity due to conflicting duplicate implicit and +explicit reference names are avoided by following this procedure: + +1. `Explicit hyperlink targets`_ override any implicit targets having + the same reference name. The implicit hyperlink targets are + removed, and level-1 (info) system messages are inserted. + +2. Duplicate implicit hyperlink targets are removed, and level-1 + (info) system messages inserted. For example, if two or more + sections have the same title (such as "Introduction" subsections of + a rigidly-structured document), there will be duplicate implicit + hyperlink targets. + +3. Duplicate explicit hyperlink targets are removed, and level-2 + (warning) system messages are inserted. Exception: duplicate + `external hyperlink targets`_ (identical hyperlink names and + referenced URIs) do not conflict, and are not removed. + +System messages are inserted where target links have been removed. +See "Error Handling" in `PEP 258`_. + +The parser must return a set of *unique* hyperlink targets. The +calling software (such as the Docutils_) can warn of unresolvable +links, giving reasons for the messages. + + +Inline Markup +============= + +In reStructuredText, inline markup applies to words or phrases within +a text block. The same whitespace and punctuation that serves to +delimit words in written text is used to delimit the inline markup +syntax constructs. The text within inline markup may not begin or end +with whitespace. Arbitrary character-level markup is not supported; +it is not possible to mark up individual characters within a word. +Inline markup cannot be nested. + +There are nine inline markup constructs. Five of the constructs use +identical start-strings and end-strings to indicate the markup: + +- emphasis_: "*" +- `strong emphasis`_: "**" +- `interpreted text`_: "`" +- `inline literals`_: "``" +- `substitution references`_: "|" + +Three constructs use different start-strings and end-strings: + +- `inline hyperlink targets`_: "_`" and "`" +- `footnote references`_: "[" and "]_" +- `hyperlink references`_: "`" and "\`_" (phrases), or just a + trailing "_" (single words) + +`Standalone hyperlinks`_ are recognized implicitly, and use no extra +markup. + +The inline markup start-string and end-string recognition rules are as +follows. If any of the conditions are not met, the start-string or +end-string will not be recognized or processed. + +1. Inline markup start-strings must start a text block or be + immediately preceded by whitespace, single or double quotes, "(", + "[", "{", or "<". + +2. Inline markup start-strings must be immediately followed by + non-whitespace. + +3. Inline markup end-strings must be immediately preceded by + non-whitespace. + +4. Inline markup end-strings must end a text block or be immediately + followed by whitespace or one of:: + + ' " . , : ; ! ? - ) ] } > + +5. If an inline markup start-string is immediately preceded by a + single or double quote, "(", "[", "{", or "<", it must not be + immediately followed by the corresponding single or double quote, + ")", "]", "}", or ">". + +6. An inline markup end-string must be separated by at least one + character from the start-string. + +7. An unescaped backslash preceding a start-string or end-string will + disable markup recognition, except for the end-string of `inline + literals`_. See `Escaping Mechanism`_ above for details. + +For example, none of the following are recognized as containing inline +markup start-strings: " * ", '"*"', "'*'", "(*)", "(* ", "[*]", "{*}", +"\*", " ` ", etc. + +The inline markup recognition rules were devised intentionally to +allow 90% of non-markup uses of "*", "`", "_", and "|" *without* +resorting to backslashes. For 9 of the remaining 10%, use inline +literals or literal blocks:: + + "``\*``" -> "\*" (possibly in another font or quoted) + +Only those who understand the escaping and inline markup rules should +attempt the remaining 1%. ;-) + +Inline markup delimiter characters are used for multiple constructs, +so to avoid ambiguity there must be a specific recognition order for +each character. The inline markup recognition order is as follows: + +- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ + ("*"). + +- Backquotes: `Inline literals`_ ("``"), `inline hyperlink targets`_ + (leading "_`", trailing "`"), are mutually independent, and are + recognized before phrase `hyperlink references`_ (leading "`", + trailing "\`_") and `interpreted text`_ ("`"). + +- Trailing underscores: Footnote references ("[" + label + "]_") and + simple `hyperlink references`_ (name + trailing "_") are mutually + independent. + +- Vertical bars: `Substitution references`_ ("|") are independently + recognized. + +- `Standalone hyperlinks`_ are the last to be recognized. + + +Emphasis +-------- + +DTD element: emphasis. + +Start-string = end-string = "*". + +Text enclosed by single asterisk characters is emphasized:: + + This is *emphasized text*. + +Emphasized text is typically displayed in italics. + + +Strong Emphasis +--------------- + +DTD element: strong. + +Start-string = end-string = "**". + +Text enclosed by double-asterisks is emphasized strongly:: + + This is **strong text**. + +Strongly emphasized text is typically displayed in boldface. + + +Interpreted Text +---------------- + +DTD element: interpreted. + +Start-string = end-string = "`". + +Text enclosed by single backquote characters is interpreted:: + + This is `interpreted text`. + +Interpreted text is text that is meant to be related, indexed, linked, +summarized, or otherwise processed, but the text itself is left +alone. The text is "tagged" directly, in-place. The semantics of +interpreted text are domain-dependent. It can be used as implicit or +explicit descriptive markup (such as for program identifiers, as in +the `Python Source Reader`_), for cross-reference interpretation (such +as index entries), or for other applications where context can be +inferred. + +The role of the interpreted text determines how the text is +interpreted. It is normally inferred implicitly. The role of the +interpreted text may also be indicated explicitly, using a role +marker, either as a prefix or as a suffix to the interpreted text, +depending on which reads better:: + + :role:`interpreted text` + + `interpreted text`:role: + +Roles are simply extensions of the available inline constructs; to +emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink +references`_, we can add "index entry", "acronym", "class", "red", +"blinking" or anything else we want. + +A role marker consists of a colon, the role name, and another colon. +A role name is a single word consisting of alphanumerics plus internal +hypens, underscores, and periods; no whitespace or other characters +are allowed. + + +Inline Literals +--------------- + +DTD element: literal. + +Start-string = end-string = "``". + +Text enclosed by double-backquotes is treated as inline literals:: + + This text is an example of ``inline literals``. + +Inline literals may contain any characters except two adjacent +backquotes in an end-string context (according to the recognition +rules above). No markup interpretation (including backslash-escape +interpretation) is done within inline literals. + +Line breaks are *not* preserved in inline literals. Although a +reStructuredText parser will preserve runs of spaces in its output, +the final representation of the processed document is dependent on the +output formatter, thus the preservation of whitespace cannot be +guaranteed. If the preservation of line breaks and/or other +whitespace is important, `literal blocks`_ should be used. + +Inline literals are useful for short code snippets. For example:: + + The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches + floating-point numbers (without exponents). + + +Hyperlink References +-------------------- + +DTD element: reference. + +- Named hyperlink references: + + - Start-string = "" (empty string), end-string = "_". + - Start-string = "`", end-string = "\`_". (Phrase references.) + +- Anonymous hyperlink references: + + - Start-string = "" (empty string), end-string = "__". + - Start-string = "`", end-string = "\`__". (Phrase references.) + +Hyperlink references are indicated by a trailing underscore, "_", +except for `standalone hyperlinks`_ which are recognized +independently. The underscore can be thought of as a right-pointing +arrow. The trailing underscores point away from hyperlink references, +and the leading underscores point toward `hyperlink targets`_. + +Hyperlinks consist of two parts. In the text body, there is a source +link, a reference name with a trailing underscore (or two underscores +for `anonymous hyperlinks`_):: + + See the Python_ home page for info. + +A target link with a matching reference name must exist somewhere else +in the document. See `Hyperlink Targets`_ for a full description). + +`Anonymous hyperlinks`_ (which see) do not use reference names to +match references to targets, but otherwise behave similarly to named +hyperlinks. + + +Inline Hyperlink Targets +------------------------ + +DTD element: target. + +Start-string = "_`", end-string = "`". + +Inline hyperlink targets are the equivalent of explicit `internal +hyperlink targets`_, but may appear within running text. The syntax +begins with an underscore and a backquote, is followed by a hyperlink +name or phrase, and ends with a backquote. Inline hyperlink targets +may not be anonymous. + +For example, the following paragraph contains a hyperlink target named +"Norwegian Blue":: + + Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it? + +See `Implicit Hyperlink Targets`_ for the resolution of duplicate +reference names. + + +Footnote References +------------------- + +DTD element: footnote_reference. + +Start-string = "[", end-string = "]_". + +Each footnote reference consists of a square-bracketed label followed +by a trailing underscore. Footnote labels are one of: + +- one or more digits (i.e., a number), + +- a single "#" (denoting `auto-numbered footnotes`_), + +- a "#" followed by a simple reference name (an `autonumber label`_), + or + +- a single "*" (denoting `auto-symbol footnotes`_). + +For example:: + + Please RTFM [1]_. + + .. [1] Read The Fine Manual + + +Citation References +------------------- + +DTD element: citation_reference. + +Start-string = "[", end-string = "]_". + +Each citation reference consists of a square-bracketed label followed +by a trailing underscore. Citation labels are simple `reference +names`_ (case-insensitive single words, consisting of alphanumerics +plus internal hyphens, underscores, and periods; no whitespace). + +For example:: + + Here is a citation reference: [CIT2002]_. + +See Citations_ for the citation itself. + + +Substitution References +----------------------- + +DTD element: substitution_reference, reference. + +Start-string = "|", end-string = "|" (optionally followed by "_" or +"__"). + +Vertical bars are used to bracket the substitution reference text. A +substitution reference may also be a hyperlink reference by appending +a "_" (named) or "__" (anonymous) suffix; the substitution text is +used for the reference text in the named case. + +The processing system replaces substitution references with the +processed contents of the corresponding `substitution definitions`_. +Substitution definitions produce inline-compatible elements. + +Examples:: + + This is a simple |substitution reference|. It will be replaced by + the processing system. + + This is a combination |substitution and hyperlink reference|_. In + addition to being replaced, the replacement text or element will + refer to the "substitution and hyperlink reference" target. + + +Standalone Hyperlinks +--------------------- + +DTD element: link. + +Start-string = end-string = "" (empty string). + +A URI (absolute URI [#URI]_ or standalone email address) within a text +block is treated as a general external hyperlink with the URI itself +as the link's text. For example:: + + See http://www.python.org for info. + +would be marked up in HTML as:: + + See <A HREF="http://www.python.org">http://www.python.org</A> for + info. + +Two forms of URI are recognized: + +1. Absolute URIs. These consist of a scheme, a colon (":"), and a + scheme-specific part whose interpretation depends on the scheme. + + The scheme is the name of the protocol, such as "http", "ftp", + "mailto", or "telnet". The scheme consists of an initial letter, + followed by letters, numbers, and/or "+", "-", ".". Recognition is + limited to known schemes, per the W3C's `Index of WWW Addressing + Schemes`_. + + The scheme-specific part of the resource identifier may be either + hierarchical or opaque: + + - Hierarchical identifiers begin with one or two slashes and may + use slashes to separate hierarchical components of the path. + Examples are web pages and FTP sites:: + + http://www.python.org + + ftp://ftp.python.org/pub/python + + - Opaque identifiers do not begin with slashes. Examples are + email addresses and newsgroups:: + + mailto:someone@somewhere.com + + news:comp.lang.python + + With queries, fragments, and %-escape sequences, URIs can become + quite complicated. A reStructuredText parser must be able to + recognize any absolute URI, as defined in RFC2396_ and RFC2732_. + +2. Standalone email addresses, which are treated as if they were + ablsolute URIs with a "mailto:" scheme. Example:: + + someone@somewhere.com + +Punctuation at the end of a URI is not considered part of the URI. + +.. [#URI] Uniform Resource Identifier. URIs are a general form of + URLs (Uniform Resource Locators). For the syntax of URIs see + RFC2396_ and RFC2732_. + + +---------------- + Error Handling +---------------- + +DTD element: system_message, problematic. + +Markup errors are handled according to the specification in `PEP +258`_. + + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _Docutils: http://docutils.sourceforge.net/ +.. _Docutils Document Tree Structure: + http://docutils.sourceforge.net/spec/doctree.txt +.. _Generic Plaintext Document Interface DTD: + http://docutils.sourceforge.net/spec/gpdi.dtd +.. _transforms: + http://docutils.sourceforge.net/docutils/transforms/ +.. _Grouch: http://www.mems-exchange.org/software/grouch/ +.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt +.. _DocTitle transform: +.. _DocInfo transform: + http://docutils.sourceforge.net/docutils/transforms/frontmatter.py +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html +.. _getopt.py: + http://www.python.org/doc/current/lib/module-getopt.html +.. _GNU libc getopt_long(): + http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html +.. _Index of WWW Addressing Schemes: + http://www.w3.org/Addressing/schemes.html +.. _World Wide Web Consortium: http://www.w3.org/ +.. _HTML Techniques for Web Content Accessibility Guidelines: + http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text +.. _reStructuredText Directives: directives.html +.. _Python Source Reader: + http://docutils.sourceforge.net/spec/pysource.txt +.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt +.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt +.. _Zope: http://www.zope.com/ +.. _PEP 258: http://docutils.sourceforge.net/spec/pep-0258.txt + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/soextblx.dtd b/docs/ref/soextblx.dtd new file mode 100644 index 000000000..56ba311ba --- /dev/null +++ b/docs/ref/soextblx.dtd @@ -0,0 +1,312 @@ +<!-- +=========================================================================== + OASIS XML Exchange Table Model Declaration Module +=========================================================================== +:Date: 1999-03-15 +--> + +<!-- This set of declarations defines the XML version of the Exchange + Table Model as of the date shown in the Formal Public Identifier + (FPI) for this entity. + + This set of declarations may be referred to using a public external + entity declaration and reference as shown in the following three + lines: + + <!ENTITY % calstblx + PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"> + %calstblx; + + If various parameter entities used within this set of declarations + are to be given non-default values, the appropriate declarations + should be given before calling in this package (i.e., before the + "%calstblx;" reference). +--> + +<!-- The motivation for this XML version of the Exchange Table Model + is simply to create an XML version of the SGML Exchange Table + Model. By design, no effort has been made to "improve" the model. + + This XML version incorporates the logical bare minimum changes + necessary to make the Exchange Table Model a valid XML DTD. +--> + +<!-- The XML version of the Exchange Table Model differs from + the SGML version in the following ways: + + The following parameter entities have been removed: + + - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep + There are no exceptions in XML. The following normative statement + is made in lieu of exceptions: the exchange table model explicitly + forbids a table from occurring within another table. If the + content model of an entry includes a table element, then this + cannot be enforced by the DTD, but it is a deviation from the + exchange table model to include a table within a table. + + - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att + The motivation for these elements was to change the table + header/footer elements. Since XML does not allow element declarations + to contain name groups, and the exchange table model does not + allow a table to contain footers, the continued presence of these + attributes seems unnecessary. + + The following parameter entity has been added: + + - tbl.thead.att + This entity parameterizes the attributes on thead. It replaces + the tbl.hdft.att parameter entity. + + Other miscellaneous changes: + + - Tag ommission indicators have been removed + - Comments have been removed from declarations + - NUMBER attributes have been changed to NMTOKEN + - NUTOKEN attributes have been to changed to NMTOKEN + - Removed the grouping characters around the content model + parameter entry for the 'entry' element. This is necessary + so that an entry can contain #PCDATA and be defined as an + optional, repeatable OR group beginning with #PCDATA. +--> + +<!-- This entity includes a set of element and attribute declarations + that partially defines the Exchange table model. However, the model + is not well-defined without the accompanying natural language + description of the semantics (meanings) of these various elements, + attributes, and attribute values. The semantic writeup, also available + from SGML Open, should be used in conjunction with this entity. +--> + +<!-- In order to use the Exchange table model, various parameter entity + declarations are required. A brief description is as follows: + + ENTITY NAME WHERE USED WHAT IT IS + + %yesorno In ATTLIST of: An attribute declared value + almost all elements for a "boolean" attribute + + %paracon In content model of: The "text" (logical content) + <entry> of the model group for <entry> + + %titles In content model of: The "title" part of the model + table element group for the table element + + %tbl.table.name In declaration of: The name of the "table" + table element element + + %tbl.table-titles.mdl In content model of: The model group for the title + table elements part of the content model for + table element + + %tbl.table.mdl In content model of: The model group for the content + table elements model for table element, + often (and by default) defined + in terms of %tbl.table-titles.mdl + and tgroup + + %tbl.table.att In ATTLIST of: Additional attributes on the + table element table element + + %bodyatt In ATTLIST of: Additional attributes on the + table element table element (for backward + compatibility with the SGML + model) + + %tbl.tgroup.mdl In content model of: The model group for the content + <tgroup> model for <tgroup> + + %tbl.tgroup.att In ATTLIST of: Additional attributes on the +4 <tgroup> <tgroup> element + + %tbl.thead.att In ATTLIST of: Additional attributes on the + <thead> <thead> element + + %tbl.tbody.att In ATTLIST of: Additional attributes on the + <tbody> <tbody> element + + %tbl.colspec.att In ATTLIST of: Additional attributes on the + <colspec> <colspec> element + + %tbl.row.mdl In content model of: The model group for the content + <row> model for <row> + + %tbl.row.att In ATTLIST of: Additional attributes on the + <row> <row> element + + %tbl.entry.mdl In content model of: The model group for the content + <entry> model for <entry> + + %tbl.entry.att In ATTLIST of: Additional attributes on the + <entry> <entry> element + + This set of declarations will use the default definitions shown below + for any of these parameter entities that are not declared before this + set of declarations is referenced. +--> + +<!-- These definitions are not directly related to the table model, but are + used in the default CALS table model and may be defined elsewhere (and + prior to the inclusion of this table module) in the referencing DTD. --> + +<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value --> +<!ENTITY % titles 'title?'> +<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content --> + +<!-- +The parameter entities as defined below change and simplify the CALS table +model as published (as part of the Example DTD) in MIL-HDBK-28001. The +resulting simplified DTD has support from the SGML Open vendors and is +therefore more interoperable among different systems. + +These following declarations provide the Exchange default definitions +for these entities. However, these entities can be redefined (by giving +the appropriate parameter entity declaration(s) prior to the reference +to this Table Model declaration set entity) to fit the needs of the +current application. + +Note, however, that changes may have significant effect on the ability to +interchange table information. These changes may manifest themselves +in useability, presentation, and possible structure information degradation. +--> + +<!ENTITY % tbl.table.name "table"> +<!ENTITY % tbl.table-titles.mdl "%titles;,"> +<!ENTITY % tbl.table-main.mdl "tgroup+"> +<!ENTITY % tbl.table.mdl "%tbl.table-titles.mdl; %tbl.table-main.mdl;"> +<!ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED "> +<!ENTITY % bodyatt ""> +<!ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody"> +<!ENTITY % tbl.tgroup.att ""> +<!ENTITY % tbl.thead.att ""> +<!ENTITY % tbl.tbody.att ""> +<!ENTITY % tbl.colspec.att ""> +<!ENTITY % tbl.row.mdl "entry+"> +<!ENTITY % tbl.row.att ""> +<!ENTITY % tbl.entry.mdl "(%paracon;)*"> +<!ENTITY % tbl.entry.att ""> + +<!-- ===== Element and attribute declarations follow. ===== --> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.table.name "table" + ENTITY % tbl.table-titles.mdl "%titles;," + ENTITY % tbl.table.mdl "%tbl.table-titles; tgroup+" + ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED " +--> + +<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)> + +<!ATTLIST %tbl.table.name; + frame (top|bottom|topbot|all|sides|none) #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + %tbl.table.att; + %bodyatt; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody" + ENTITY % tbl.tgroup.att "" +--> + +<!ELEMENT tgroup (%tbl.tgroup.mdl;) > + +<!ATTLIST tgroup + cols NMTOKEN #REQUIRED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + %tbl.tgroup.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.colspec.att "" +--> + +<!ELEMENT colspec EMPTY > + +<!ATTLIST colspec + colnum NMTOKEN #IMPLIED + colname NMTOKEN #IMPLIED + colwidth CDATA #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + %tbl.colspec.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.thead.att "" +--> + +<!ELEMENT thead (row+)> + +<!ATTLIST thead + valign (top|middle|bottom) #IMPLIED + %tbl.thead.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tbody.att "" +--> + +<!ELEMENT tbody (row+)> + +<!ATTLIST tbody + valign (top|middle|bottom) #IMPLIED + %tbl.tbody.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.row.mdl "entry+" + ENTITY % tbl.row.att "" +--> + +<!ELEMENT row (%tbl.row.mdl;)> + +<!ATTLIST row + rowsep %yesorno; #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.row.att; +> + + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % paracon "#PCDATA" + ENTITY % tbl.entry.mdl "(%paracon;)*" + ENTITY % tbl.entry.att "" +--> + +<!ELEMENT entry %tbl.entry.mdl;> + +<!ATTLIST entry + colname NMTOKEN #IMPLIED + namest NMTOKEN #IMPLIED + nameend NMTOKEN #IMPLIED + morerows NMTOKEN #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.entry.att; +> diff --git a/docs/user/rst/images/ball1.gif b/docs/user/rst/images/ball1.gif new file mode 100644 index 000000000..3e14441d9 Binary files /dev/null and b/docs/user/rst/images/ball1.gif differ diff --git a/docs/user/rst/images/biohazard.bmp b/docs/user/rst/images/biohazard.bmp new file mode 100644 index 000000000..aceb52948 Binary files /dev/null and b/docs/user/rst/images/biohazard.bmp differ diff --git a/docs/user/rst/images/biohazard.gif b/docs/user/rst/images/biohazard.gif new file mode 100644 index 000000000..7e1ea34ed Binary files /dev/null and b/docs/user/rst/images/biohazard.gif differ diff --git a/docs/user/rst/images/biohazard.png b/docs/user/rst/images/biohazard.png new file mode 100644 index 000000000..ae4629d8b Binary files /dev/null and b/docs/user/rst/images/biohazard.png differ diff --git a/docs/user/rst/images/title.png b/docs/user/rst/images/title.png new file mode 100644 index 000000000..cc6218efe Binary files /dev/null and b/docs/user/rst/images/title.png differ diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html new file mode 100644 index 000000000..886a02107 --- /dev/null +++ b/docs/user/rst/quickref.html @@ -0,0 +1,1096 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> + <head> + <title>Quick reStructuredText + + + + +

Quick reStructuredText

+ + + + + + + + + + +

http://docutils.sourceforge.net/docs/rst/quickref.html +
Being a cheat-sheet for reStructuredText +
Version 0.8 of 2002-04-19 + + +

The full details may be found on the + reStructuredText + page. This document is just intended as a reminder. + +

Links that look like "(details?)" point + into the HTML version of the full reStructuredText + specification document. These are relative links; if they + don't work, please use the master "Quick reStructuredText" document. + +

Contents

+ + + +

Inline Markup

+ +

(details?) + +

+ + + + + + + + + + + + + + + + +
Plain text + Typical result + Notes +
*emphasis* + emphasis +   + +
**strong emphasis** + strong emphasis +   + +
`interpreted text` + interpreted text + What interpreted text means is domain dependent. + +
``inline literal`` + inline literal + Spaces should be preserved, but line breaks will not be. + +
reference_ + reference + A simple, one-word hyperlink reference. See Hyperlinks. + +
`phrase reference`_ + phrase reference + A hyperlink reference with spaces or punctuation needs to be quoted with backquotes. + See Hyperlinks. + +
anonymous__ + anonymous + Both simple and phrase references may be anonymous (two underscores). + See Hyperlinks. + +
_`inline hyperlink target` + inline hyperlink target + A crossreference target within text. + See Hyperlinks. + +
|substitution reference| + (see note) + The result is substituted in from the substitution definition. + It could be text, an image, a hyperlink, or a combination of these and others. + +
footnote reference [1]_ + footnote reference [1] + See Footnotes. + +
citation reference [CIT2002]_ + citation reference [CIT2002] + See Citations. + +
http://docutils.sf.net/ + http://docutils.sf.net/ + A standalone hyperlink. + +
+ +

Asterisk, backquote, vertical bar, and underscore are inline + delimiter characters. Asterisk, backquote, and vertical bar act + like quote marks; matching characters surround the marked-up word + or phrase, whitespace or other quoting is required outside them, + and there can't be whitespace just inside them. If you want to use + inline delimiter characters literally, escape + (with backslash) or quote them (with double backquotes; i.e. + use inline literals). + +

In detail, the reStructuredText specifications says that in + inline markup: +

    +
  1. The start-string must start a text block or be + immediately preceded by whitespace,  + ' " ( [ { or  <. +
  2. The start-string must be immediately followed by non-whitespace. +
  3. The end-string must be immediately preceded by non-whitespace. +
  4. The end-string must end a text block or be immediately + followed by whitespace,  + ' " . , : ; ! ? - ) ] } or  >. +
  5. If a start-string is immediately preceded by one of  + ' " ( [ { or  <, it must not be + immediately followed by the corresponding character from  + ' " ) ] } or  >. +
  6. An end-string must be separated by at least one + character from the start-string. +
  7. An unescaped backslash preceding a start-string or end-string will + disable markup recognition, except for the end-string of inline + literals. +
+ +

Also remember that inline markup may not be nested (well, + except that inline literals can contain any of the other inline + markup delimiter characters, but that doesn't count because + nothing is processed). + +

Escaping with Bashslashes

+ +

(details?) + +

reStructuredText uses backslashes ("\") to override the special + meaning given to markup characters and get the literal characters + themselves. To get a literal backslash, use an escaped backslash + ("\\"). For example: + +

+ + + + +
Raw reStructuredText + Typical result +
+ *escape* ``with`` "\" + escape with "" +
+ \*escape* \``with`` "\\" + *escape* ``with`` "\" +
+ +

In Python strings it will, of course, be necessary + to escape any backslash characters so that they actually + reach reStructuredText. + The simplest way to do this is to use raw strings: + +

+ + + + +
Python string + Typical result +
+ r"""\*escape* \`with` "\\"""" + *escape* `with` "\" +
+  """\\*escape* \\`with` "\\\\"""" + *escape* `with` "\" +
+  """\*escape* \`with` "\\"""" + escape with "" +
+ +

Section Structure

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+ ===== +
Title +
===== +
Subtitle +
-------- +
Titles are underlined (or over- +
and underlined) with a printing +
nonalphanumeric 7-bit ASCII +
character. Recommended choices +
are "``= - ` : ' " ~ ^ _ * + # < >``". + 		+ Title +

Subtitle +

Titles are underlined (or over- + and underlined) with a printing + nonalphanumeric 7-bit ASCII + character. Recommended choices + are "= - ` : ' " ~ ^ _ * + # < >". +

+ +

Paragraphs

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+

This is a paragraph. + +

Paragraphs line up at their left +
edges, and are normally separated +
by blank lines. + +

+

This is a paragraph. + +

Paragraphs line up at their left edges, and are normally + separated by blank lines. + +

+ +

Bullet Lists

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+Bullet lists: + +

- This is item 1 +
- This is item 2 + +

- Bullets are "-", "*" or "+". +
  Continuing text must be aligned +
  after the bullet and whitespace. + +

Note that a blank line is required +
before the first item and after the +
last, but is optional between items. +

Bullet lists: +
    +
  • This is item 1 +
  • This is item 2 +
  • Bullets are "-", "*" or "+". + Continuing text must be aligned + after the bullet and whitespace. +
+

Note that a blank line is required before the first + item and after the last, but is optional between items. +

+ +

Enumerated Lists

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+Enumerated lists: + +

3. This is the first item +
4. This is the second item +
5. Enumerators are arabic numbers, +
   single letters, or roman numerals +
6. List items should be sequentially +
   numbered, but need not start at 1 +
   (although not all formatters will +
   honour the first index). +

Enumerated lists: +
    +
  1. This is the first item +
  2. This is the second item +
  3. Enumerators are arabic numbers, single letters, + or roman numerals +
  4. List items should be sequentially numbered, + but need not start at 1 (although not all + formatters will honour the first index). +
+
+ +

Definition Lists

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+Definition lists: +
+
what +
  Definition lists associate a term with +
  a definition. +
+
how +
  The term is a one-line phrase, and the +
  definition is one or more paragraphs or +
  body elements, indented relative to the +
  term. Blank lines are not allowed +
  between term and definition. + 		Definition lists: +
+
what +
Definition lists associate a term with + a definition. + +
how +
The term is a one-line phrase, and the + definition is one or more paragraphs or + body elements, indented relative to the + term. Blank lines are not allowed + between term and definition. +
+
+ +

Field Lists

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+:Authors: +
    Tony J. (Tibs) Ibbs, +
    David Goodger + +

    (and sundry other good-natured folks) + +

:Version: 1.0 of 2001/08/08 +
:Dedication: To my father. +

+ + +
Authors: + Tony J. (Tibs) Ibbs, + David Goodger +
(and sundry other good-natured folks) +
Version:1.0 of 2001/08/08 +
Dedication:To my father. +
+
+ +

Option Lists

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+

+-a            command-line option "a" +
-b file       options can have arguments +
              and long descriptions +
--long        options can be long also +
--input=file  long options can also have +
              arguments +
/V            DOS/VMS-style options too + + +

+ + + + + + + +

-a +

command-line option "a" +

-b file +

options can have arguments and long descriptions +

--long +

options can be long also +

--input=file +

long options can also have arguments +

/V +

DOS/VMS-style options too +

+
+ +

There must be at least two spaces between the option and the + description. + +

Literal Blocks

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+A paragraph containing only two colons +
indicates that the following indented +
text is a literal block. +
+
:: +
+
  Whitespace, newlines, blank lines, and +
  all kinds of markup (like *this* or +
  \this) is preserved by literal blocks. +
+
  The paragraph containing only '::' +
  will be omitted from the result. +
+
The ``::`` may be tacked onto the very +
end of any paragraph. The ``::`` will be +
omitted if it is preceded by whitespace. +
The ``::`` will be converted to a single +
colon if preceded by text, like this:: +
+
  It's very convenient to use this form. +
+
Literal blocks end when text returns to +
the preceding paragraph's indentation. +
This means that something like:: +
+
      We start here +
    and continue here +
  and end here. +
+
is possible. + + 		+

A paragraph containing only two colons +indicates that the following indented +text is a literal block. + + 

+  Whitespace, newlines, blank lines, and
+  all kinds of markup (like *this* or
+  \this) is preserved by literal blocks.
+
+  The paragraph containing only '::'
+  will be omitted from the result.
+ +

The :: may be tacked onto the very +end of any paragraph. The :: will be +omitted if it is preceded by whitespace. +The :: will be converted to a single +colon if preceded by text, like this: + + 

+  It's very convenient to use this form.
+ +

Literal blocks end when text returns to +the preceding paragraph's indentation. +This means that something like: + + 

+      We start here
+    and continue here
+  and end here.
+ +

is possible. +

+ +

Block Quotes

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+Block quotes are just: + +

    Indented paragraphs, + +

        and they may nest. +

+ Block quotes are just: +
+

Indented paragraphs, +

+

and they may nest. +

+
+
+ +

Doctest Blocks

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+

Doctest blocks are interactive +
Python sessions. They begin with +
"``>>>``" and end with a blank line. + +

>>> print "This is a doctest block." +
This is a doctest block. + +

+

Doctest blocks are interactive + Python sessions. They begin with + ">>>" and end with a blank line. + +

>>> print "This is a doctest block." +
This is a doctest block. +

+ +

"The doctest + module searches a module's docstrings for text that looks like an + interactive Python session, then executes all such sessions to + verify they still work exactly as shown." (From the doctest docs.) + +

Tables

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+    +------------+------------+-----------+ +
    | Header 1   | Header 2   | Header 3  | +
    +============+============+===========+ +
    | body row 1 | column 2   | column 3  | +
    +------------+------------+-----------+ +
    | body row 2 | Cells may span columns.| +
    +------------+------------+-----------+ +
    | body row 3 | Cells may  | - Cells   | +
    +------------+ span rows. | - contain | +
    | body row 4 |            | - blocks. | +
    +------------+------------+-----------+ + 		+ + + + + + +
Header 1 + Header 2 + Header 3 +
body row 1 + column 2 + column 3 +
body row 2 + Cells may span columns. +
body row 3 + Cells may
span rows. + 		+
    +
  • Cells +
  • contain +
  • blocks. +
+
body row 4 +
+
+ +

Transitions

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
+

+A transition marker is a horizontal line +
of 4 or more repeated punctuation +
characters. + +

------------ + +

A transition should not begin or end a +
section or document, nor should two +
transitions be immediately adjacent. + +

+

A transition marker is a horizontal line + of 4 or more repeated punctuation + characters.

+ +
+ +

A transition should not begin or end a + section or document, nor should two + transitions be immediately adjacent. +

+ +

Transitions are commonly seen in novels and short fiction, as a + gap spanning one or more lines, marking text divisions or + signaling changes in subject, time, point of view, or emphasis. + +

Footnotes

+ +

(details?) + +

+ + + + + + + + +
Plain text + Typical result +
+ Footnote references, like [5]_. +
Note that footnotes may get +
rearranged, e.g., to the bottom of +
the "page". + +

.. [5] A numerical footnote. Note +
   there's no colon after the ``]``. + +

+ Footnote references, like [5]. + Note that footnotes may get rearranged, e.g., to the bottom of + the "page". + +

+
+ +
[5] A numerical footnote. + Note there's no colon after the ]. +
+ +

+ Autonumbered footnotes are +
possible, like using [#]_ and [#]_. +

.. [#] This is the first one. +
.. [#] This is the second one. + +

They may be assigned 'autonumber +
labels' - for instance, +
[#fourth]_ and [#third]_. + +

.. [#third] a.k.a. third_ +

.. [#fourth] a.k.a. fourth_ +

+ Autonumbered footnotes are possible, like using 1 and 2. + +

They may be assigned 'autonumber labels' - for instance, + 4 and 3. + +

+
+ +
[1] This is the first one. +
[2] This is the second one. +
[3] a.k.a. third +
[4] a.k.a. fourth +
+ +

+ Auto-symbol footnotes are also +
possible, like this: [*]_ and [*]_. +

.. [*] This is the first one. +
.. [*] This is the second one. + +

+ Auto-symbol footnotes are also + possible, like this: * + and †. + +

+
+ +
[*] This is the first symbol footnote +
[†] This is the second one. +
+ +

+ +

The numbering of auto-numbered footnotes is determined by the + order of the footnotes, not of the references. For auto-numbered + footnote references without autonumber labels + ("[#]_"), the references and footnotes must be in the + same relative order. Similarly for auto-symbol footnotes + ("[*]_"). + +

Citations

+ +

(details?) + +

+ + + + + + +
Plain text + Typical result +
+ Citation references, like [CIT2002]_. +
Note that citations may get +
rearranged, e.g., to the bottom of +
the "page". + +

.. [CIT2002] A citation +
   (as often used in journals). + +

Citation labels contain alphanumerics, +
underlines, hyphens and fullstops. +
Case is not significant. + +

Given a citation like [this]_, one +
can also refer to it like this_. + +

.. [this] here. + +

+ Citation references, like [CIT2002]. + Note that citations may get rearranged, e.g., to the bottom of + the "page". + +

Citation labels contain alphanumerics, underlines, hyphens + and fullstops. Case is not significant. + +

Given a citation like [this], one + can also refer to it like this. + +

+
+ +
[CIT2002] A citation + (as often used in journals). +
[this] here. +
+ +

+ +

Hyperlink Targets

+ +

(details?) + +

External Hyperlink Targets

+ +

+ + + + + + +
Plain text + Typical result +
+ External hyperlinks, like Python_. + +

.. _Python: http://www.python.org/ +

+ +
Fold-in form +
Indirect hyperlinks, like + Python. +
Call-out form +
External hyperlinks, like + Python. + +

+
+
Python: + http://www.python.org/ +
+

+
+ +

"Fold-in" is the representation typically used in HTML + documents (think of the indirect hyperlink being "folded in" like + ingredients into a cake), and "call-out" is more suitable for + printed documents, where the link needs to be presented explicitly, for + example as a footnote. + +

Internal Hyperlink Targets

+ +

+ + + + + + +
Plain text + Typical result +
Internal crossreferences, like example_. + +

.. _example: + +

This is an example crossreference target. +

+ +
Fold-in form + + + + +
Internal crossreferences, like example +

This is an example + crossreference target. +

Call-out form +
Internal crossreferences, like example + +

example: +
This is an example crossreference target. +

+ +
+ +

Indirect Hyperlink Targets

+ +

(details?) + +

+ + + + + + +
Plain text + Typical result +
+ Python_ is `my favourite +
programming language`__. + +

.. _Python: http://www.python.org/ + +

__ Python_ + +

+

Python is + my favourite + programming language. + +

+ +

The second hyperlink target (the line beginning with + "__") is both an indirect hyperlink target + (indirectly pointing at the Python website via the + "Python_" reference) and an anonymous hyperlink + target. In the text, a double-underscore suffix is used to + indicate an anonymous hyperlink reference. + +

Implicit Hyperlink Targets

+ +

(details?) + +

Section titles, footnotes, and citations automatically generate + hyperlink targets (the title text or footnote/citation label is + used as the hyperlink name). + +

+ + + +
Plain text + Typical result + +
+ Titles are targets, too +
======================= +
Implict references, like `Titles are +
targets, too`_. + 		+ Titles are targets, too +

Implict references, like Titles are + targets, too. +

+ +

Directives

+ +

(details?) + +

+ + + + + +
Plain text + Typical result +
For instance: + +

.. image:: images/ball1.gif + +

+ For instance: +

ball1 +

+ +

Substitution References and Definitions

+ +

(details?) + +

Substitutions are like inline directives, allowing graphics and + arbitrary constructs within text. + +

+ + + + + +
Plain text + Typical result +
+The |biohazard| symbol must be +used on containers used to +dispose of medical waste. + +

+.. |biohazard| image:: biohazard.png + +

+ +

The biohazard symbol + must be used on containers used to dispose of medical waste. + +

+ +

Comments

+ +

(details?) + +

+ + + + + + +
Plain text + Typical result +
.. This text will not be shown +
   (but, for instance, in HTML might be +
   rendered as an HTML comment) + + 		  + + + + +
+ An empty "comment" directive does not +
"consume" following blocks. +

.. +

        So this block is not "lost", +
        despite its indentation. +

+ An empty "comment" directive does not + "consume" following blocks. +
+ So this block is not "lost", + despite its indentation. +
+
+ +

+
+

Authors: + Tibs + (tony@lsl.co.uk or + tibs@tibsnjoan.co.uk) + and David Goodger + (goodger@users.sourceforge.net) +

+ + + diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt new file mode 100644 index 000000000..be9139d60 --- /dev/null +++ b/docs/user/rst/quickstart.txt @@ -0,0 +1,301 @@ +A ReStructuredText Primer +========================= + +:Author: Richard Jones +:Version: $Revision$ + +The text below contains links that look like "(quickref__)". These +are relative links that point to the `Quick reStructuredText`_ user +reference. If these links don't work, please refer to the `master +quick reference`_ document. + +__ +.. _Quick reStructuredText: quickref.html +.. _master quick reference: + http://docutils.sourceforge.net/docs/rst/quickref.html + + +Structure +--------- + +From the outset, let me say that "Structured Text" is probably a bit +of a misnomer. It's more like "Relaxed Text" that uses certain +consistent patterns. These patterns are interpreted by a HTML +converter to produce "Very Structured Text" that can be used by a web +browser. + +The most basic pattern recognised is a **paragraph** (quickref__). +That's a chunk of text that is separated by blank lines (one is +enough). Paragraphs must have the same indentation -- that is, line +up at their left edge. Paragraphs that start indented will result in +indented quote paragraphs. For example:: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +Results in: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +__ quickref.html#paragraphs + +Text styles +----------- + +(quickref__) + +__ quickref.html#inline-markup + +Inside paragraphs and other bodies of text, you may additionally mark +text for *italics* with "``*italics*``" or **bold** with +"``**bold**``". + +If you want something to appear as a fixed-space literal, use +"````double back-quotes````". Note that no further fiddling is done +inside the double back-quotes -- so asterisks "``*``" etc. are left +alone. + +If you find that you want to use one of the "special" characters in +text, it will generally be OK -- ReST is pretty smart. For example, +this * asterisk is handled just fine. If you actually want text +\*surrounded by asterisks* to **not** be italicised, then you need to +indicate that the asterisk is not special. You do this by placing a +backslash just before it, like so "``\*``" (quickref__). + +__ quickref.html#escaping + +Lists +----- + +Lists of items come in three main flavours: **enumerated**, +**bulleted** and **definitions**. In all list cases, you may have as +many paragraphs, sublists, etc. as you want, as long as the left-hand +side of the paragraph or whatever aligns with the first line of text +in the list item. + +Lists must always start a new paragraph -- that is, they must appear +after a blank line. + +**enumerated** lists (numbers, letters or roman numerals; quickref__) + __ quickref.html#enumerated-lists + + Start a line off with a number or letter followed by a period ".", + right bracket ")" or surrounded by brackets "( )" -- whatever you're + comfortable with. All of the following forms are recognised:: + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + + Results in (note: the different enumerated list styles are not + always supported by every web browser, so you may not get the full + effect here): + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + +**bulleted** lists (quickref__) + __ quickref.html#bullet-lists + + Just like enumerated lists, start the line off with a bullet point + character - either "-", "+" or "*":: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + + Results in: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + +**definition** lists (quickref__) + __ quickref.html#definition-lists + + Unlike the other two, the definition lists consist of a term, and + the definition of that term. The format of a definition list is:: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + + Results in: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + +Preformatting (code samples) +---------------------------- +(quickref__) + +__ quickref.html#literal-blocks + +To just include a chunk of preformatted, never-to-be-fiddled-with +text, finish the prior paragraph with "``::``". The preformatted +block is finished when the text falls back to the same indentation +level as a paragraph prior to the preformatted block. For example:: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Results in: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Note that if a paragraph consists only of "``::``", then it's removed +from the output:: + + :: + + This is preformatted text, and the + last "::" paragraph is removed + +Results in: + +:: + + This is preformatted text, and the + last "::" paragraph is removed + +Sections +-------- + +(quickref__) + +__ quickref.html#section-structure + +To break longer text up into sections, you use **section headers**. +These are a single line of text (one or more words) with an underline +(and optionally an overline) in dashes "``-----``", equals +"``======``", tildes "``~~~~~~``" or any of the non-alphanumeric +characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable +with. Be consistent though, since all sections marked with the same +underline style are deemed to be at the same level:: + + Chapter 1 Title + =============== + + Section 1.1 Title + ----------------- + + Subsection 1.1.1 Title + ~~~~~~~~~~~~~~~~~~~~~~ + + Section 1.2 Title + ----------------- + + Chapter 2 Title + =============== + +results in: + +.. sorry, I change the heading style here, but it's only an example :) + +Chapter 1 Title +~~~~~~~~~~~~~~~ + +Section 1.1 Title +''''''''''''''''' + +Subsection 1.1.1 Title +"""""""""""""""""""""" + +Section 1.2 Title +''''''''''''''''' + +Chapter 2 Title +~~~~~~~~~~~~~~~ + +Note that section headers are available as link targets, just using +their name. To link to the Lists_ heading, I write "``Lists_``". If +the heading has a space in it like `text styles`_, we need to quote +the heading "```text styles`_``". + +What Next? +---------- + +This primer introduces the most common features of reStructuredText, +but there are a lot more to explore. The `Quick reStructuredText`_ +user reference is a good place to go next. For complete details, the +`reStructuredText Markup Specification`_ is the place to go [#]_. + +.. _reStructuredText Markup Specification: + ../../spec/rst/reStructuredText.html + +.. [#] If that relative link doesn't work, try the master document: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html. -- cgit v1.2.1 From 4be9c5e656e39a59bf1fb4f664a2ab157e5ddb71 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 03:17:12 +0000 Subject: emacs stanza git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@23 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index 96d2d5644..f6ec09ebd 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -36,3 +36,12 @@ conventions which are understood by the Docutils. - Frederic Giacometti's "iPhrase Python documentation conventions" is an attachment to his Doc-SIG post of 2001-05-30 (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: -- cgit v1.2.1 From 747e5063b37ae2d5ddb7c839f975dc04ff14572d Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 03:17:45 +0000 Subject: updated URLs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@24 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 3f0536231..a3d4216d1 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -719,7 +719,7 @@ Questions & Answers References & Footnotes - [1] http://structuredtext.sourceforge.net/ + [1] http://docutils.sourceforge.net/spec/rst.html [2] http://www.python.org/sigs/doc-sig/ @@ -744,25 +744,25 @@ References & Footnotes [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage [13] A ReStructuredText Primer - http://structuredtext.sourceforge.net/docs/quickstart.html + http://docutils.sourceforge.net/docs/rst/quickstart.html [14] Quick reStructuredText - http://structuredtext.sourceforge.net/docs/quickref.html + http://docutils.sourceforge.net/docs/rst/quickref.html [15] An Introduction to reStructuredText - http://structuredtext.sourceforge.net/spec/introduction.txt + http://docutils.sourceforge.net/spec/rst/introduction.html [16] reStructuredText Markup Specification - http://structuredtext.sourceforge.net/spec/reStructuredText.txt + http://docutils.sourceforge.net/spec/rst/reStructuredText.html [17] reStructuredText Directives - http://structuredtext.sourceforge.net/spec/directives.txt + http://docutils.sourceforge.net/spec/rst/directives.html [18] Problems with StructuredText - http://structuredtext.sourceforge.net/spec/problems.txt + http://docutils.sourceforge.net/spec/rst/problems.html [19] A Record of reStructuredText Syntax Alternatives - http://structuredtext.sourceforge.net/spec/alternatives.txt + http://docutils.sourceforge.net/spec/rst/alternatives.html [20] PEP 1, PEP Guidelines, Warsaw, Hylton http://www.python.org/peps/pep-0001.html @@ -789,7 +789,8 @@ Acknowledgements Some text is borrowed from PEP 216, Docstring Format [24]_, by Moshe Zadka. - Special thanks to all members past & present of the Python Doc-SIG. + Special thanks to all members past & present of the Python + Doc-SIG. -- cgit v1.2.1 From 19f36f6deb6962feb5b798e2824abf6a835c9dcb Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Apr 2002 16:38:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@30 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 13 ------------- 1 file changed, 13 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 311751f37..7ba402eaf 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -203,19 +203,6 @@ reStructuredText Parser See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's "Structuring: a summary; and an attempt at EBNF", item 4. -- Produce a better system message when a list ends abruptly. Input:: - - -1 Option "1" - -2 - - Produces:: - - Reporter: WARNING (2) Unindent without blank line at line 2. - - But it should produce:: - - Reporter: WARNING (2) List ends without blank line at line 2. - Directives `````````` -- cgit v1.2.1 From e5157bc86fb0ebbc6463982f296d95881945a4a0 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Apr 2002 03:28:42 +0000 Subject: - Clarified prohibition of signature repetition. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@37 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0257.txt | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index 48425d9cc..af1239568 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -113,7 +113,15 @@ Specification """function(a, b) -> list""" This type of docstring is only appropriate for C functions (such - as built-ins), where introspection is not possible. + as built-ins), where introspection is not possible. However, + the nature of the return value cannot be determined by + introspection, so it should be mentioned. The preferred form + for such a docstring would be something like:: + + def function(a, b): + """Do X and return a list.""" + + (Of course "Do X" should be replaced by a useful description!) Multi-line Docstrings ---------------------- -- cgit v1.2.1 From 8233789d399195a3d502385780aa5f4e8ad29a25 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Apr 2002 03:32:59 +0000 Subject: - Clarified field list usage. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@39 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 149ef3fd4..f352c9716 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -738,6 +738,14 @@ Field Lists DTD elements: field_list, field, field_name, field_argument, field_body. +Field lists are most often used as part of an extension syntax, such +as attributes for directives_, or database-like fields meant for +further processing. They are not intended to be an alternative to +definition lists. Applications of reStructuredText may recognize +field names and transform fields or field bodies in certain contexts. +See `Bibliographic Fields`_ below for one example, or the "image" +directive in `reStructuredText Directives`_ for another. + Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, numbers, and punctuation, except colons (":") and whitespace. Field @@ -772,12 +780,6 @@ The syntax for field arguments may be extended in the future. For example, quoted phrases may be treated as a single argument, and direct support for the "name=value" syntax may be added. -Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts; they are often -used as part of an extension syntax. See `Bibliographic Fields`_ -below for one example, or the "image" directive in `reStructuredText -Directives`_ for another. - Standard RFC822 headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a line is common in written text. However, in well-defined contexts such as -- cgit v1.2.1 From 598169940149a43bc8df48a58fe9c90027221553 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Apr 2002 03:34:48 +0000 Subject: Expanded auto-numbered enumerated list idea; thanks to Fred Bremmer. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@40 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 47 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 9bbe9a2f1..f8fc35623 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -41,18 +41,47 @@ allow for nested enumerated lists without indentation? Auto-Numbered Enumerated Lists ------------------------------ -Add these? Example:: +The advantage of auto-numbered enumerated lists would be similar to +auto-numbered footnotes: no manual renumbering would be required. The +disadvantages are also the same: input and output don't match exactly; +the markup may be ugly. - #. Item 1. - #. Item 2. - #. Item 3. +1. Use the "#" symbol. Example:: -Arabic numerals only, or any sequence if first initialized? For -example:: + #. Item 1. + #. Item 2. + #. Item 3. - a) Item a. - #) Item b. - #) Item c. + Advantage: simple, explicit. Disadvantage: only one enumeration + sequence (arabic numerals), a bit ugly. + +2. As a variation on #1, first initialize the enumeration sequence? + For example:: + + a) Item a. + #) Item b. + #) Item c. + + Advantages: simple, explicit, any enumeration sequence possible. + Disadvantages: a bit ugly. + +3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: + + 1. Item 1. + 1. Item 2. + 1. Item 3. + + Advantages: enumeration sequence is explicit (could be 'a.' or + '(I)'). Disadvantage: otherwise erroneous input (e.g., a duplicate + item 1) would pass silently, either causing a problem later in the + list (if no blank lines between items) or creating two lists (with + blanks):: + + 1. Item 1. + + 1. Unintentional duplicate of item 1. + + 2. Item 2. Sloppy Indentation of List Items -- cgit v1.2.1 From f72530749ef8f8cd64a7c3d3b34f8f45cfffcb93 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Apr 2002 03:56:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@50 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7ba402eaf..52e137f45 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -60,6 +60,11 @@ General - TOC transform: use alt-text for inline images. +- Implement a PEP reader. + +- Add support for character set encodings on input & output, Unicode + internally. + Specification ------------- @@ -203,6 +208,9 @@ reStructuredText Parser See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's "Structuring: a summary; and an attempt at EBNF", item 4. +- Make the parser modular. Be able to turn on/off constructs, add + them at run time. + Directives `````````` @@ -338,6 +346,9 @@ HTML Writer - Improve the granularity of document parts in the HTML writer, so that one could just grab the parts needed. +- Return a string instead of writing to a file? Leave all I/O up to + the client? + Coding Conventions ================== -- cgit v1.2.1 From c0cf24ed21eebbc4526da045141a0b0292e0bb24 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 02:15:08 +0000 Subject: not needed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@52 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/images/biohazard.bmp | Bin 406 -> 0 bytes docs/user/rst/images/biohazard.gif | Bin 949 -> 0 bytes 2 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/user/rst/images/biohazard.bmp delete mode 100644 docs/user/rst/images/biohazard.gif (limited to 'docs') diff --git a/docs/user/rst/images/biohazard.bmp b/docs/user/rst/images/biohazard.bmp deleted file mode 100644 index aceb52948..000000000 Binary files a/docs/user/rst/images/biohazard.bmp and /dev/null differ diff --git a/docs/user/rst/images/biohazard.gif b/docs/user/rst/images/biohazard.gif deleted file mode 100644 index 7e1ea34ed..000000000 Binary files a/docs/user/rst/images/biohazard.gif and /dev/null differ -- cgit v1.2.1 From d595a6e13784333b4bb6d4ce604bdaef90bd7850 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 02:18:22 +0000 Subject: - Expanded "Auto-Enumerated Lists". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@53 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 164 +++++++++++++++++++++++++++++------------- 1 file changed, 115 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index f8fc35623..b58c6a186 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -34,56 +34,10 @@ posterity and in case any of them prove to be useful. Compound Enumerated Lists ------------------------- -Allow for compound enumerators, such as '1.1.' or '1.a.' or '1(a)', to +Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to allow for nested enumerated lists without indentation? -Auto-Numbered Enumerated Lists ------------------------------- - -The advantage of auto-numbered enumerated lists would be similar to -auto-numbered footnotes: no manual renumbering would be required. The -disadvantages are also the same: input and output don't match exactly; -the markup may be ugly. - -1. Use the "#" symbol. Example:: - - #. Item 1. - #. Item 2. - #. Item 3. - - Advantage: simple, explicit. Disadvantage: only one enumeration - sequence (arabic numerals), a bit ugly. - -2. As a variation on #1, first initialize the enumeration sequence? - For example:: - - a) Item a. - #) Item b. - #) Item c. - - Advantages: simple, explicit, any enumeration sequence possible. - Disadvantages: a bit ugly. - -3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: - - 1. Item 1. - 1. Item 2. - 1. Item 3. - - Advantages: enumeration sequence is explicit (could be 'a.' or - '(I)'). Disadvantage: otherwise erroneous input (e.g., a duplicate - item 1) would pass silently, either causing a problem later in the - list (if no blank lines between items) or creating two lists (with - blanks):: - - 1. Item 1. - - 1. Unintentional duplicate of item 1. - - 2. Item 2. - - Sloppy Indentation of List Items -------------------------------- @@ -696,8 +650,8 @@ used square brackets for phrase-links. I changed my mind because: identifiers heuristically, but it doesn't take much imagination to come up with counter-examples where PyDoc's heuristics would result in embarassing failure. I wanted to do it deterministically, and - that called for syntax. I called this construct 'interpreted - text'. + that called for syntax. I called this construct "interpreted + text". 4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the idea of using double-backquotes as syntax. @@ -1258,6 +1212,118 @@ reference syntax alone. Except that these discussions gave rise to the "auto-symbol footnote" concept, which has been added. Citations and citation references have also been added. + +Auto-Enumerated Lists +===================== + +The advantage of auto-numbered enumerated lists would be similar to +that of auto-numbered footnotes: lists could be written and rearranged +without having to manually renumber them. The disadvantages are also +the same: input and output wouldn't match exactly; the markup may be +ugly or confusing (depending on which alternative is chosen). + +1. Use the "#" symbol. Example:: + + #. Item 1. + #. Item 2. + #. Item 3. + + Advantages: simple, explicit. Disadvantage: enumeration sequence + cannot be specified (limited to arabic numerals); ugly. + +2. As a variation on #1, first initialize the enumeration sequence? + For example:: + + a) Item a. + #) Item b. + #) Item c. + + Advantages: simple, explicit, any enumeration sequence possible. + Disadvantages: ugly; perhaps confusing with mixed concrete/abstract + enumerators. + +3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: + + 1. Item 1. + 1. Item 2. + 1. Item 3. + + Advantages: enumeration sequence is explicit (could be multiple + "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise + erroneous input (e.g., a duplicate item "1.") would pass silently, + either causing a problem later in the list (if no blank lines + between items) or creating two lists (with blanks). + + Take this input for example:: + + 1. Item 1. + + 1. Unintentional duplicate of item 1. + + 2. Item 2. + + Currently the parser will produce two list, "1" and "1,2" (no + warnings, because of the presence of blank lines). Using Fred's + notation, the current behavior is "1,1,2 -> 1 1,2" (without blank + lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What + should the behavior be with auto-numbering? + + Fred has produced a patch__, whose initial behavior is as follows:: + + 1,1,1 -> 1,2,3 + 1,2,2 -> 1,2,3 + 3,3,3 -> 3,4,5 + 1,2,2,3 -> 1,2,3 [WARNING] 3 + 1,1,2 -> 1,2 [WARNING] 2 + + (After the "[WARNING]", the "3" would begin a new list.) + + I have mixed feelings about adding this functionality to the spec & + parser. It would certainly be useful to some users (myself + included; I often have to renumber lists). Perhaps it's too + clever, asking the parser to guess too much. What if you *do* want + three one-item lists in a row, each beginning with "1."? You'd + have to use empty comments to force breaks. Also, I question + whether "1,2,2 -> 1,2,3" is optimal behavior. + + In response, Fred came up with "a stricter and more explicit rule + [which] would be to only auto-number silently if *all* the + enumerators of a list were identical". In that case: + + 1,1,1 -> 1,2,3 + 1,2,2 -> 1,2 [WARNING] 2 + 3,3,3 -> 3,4,5 + 1,2,2,3 -> 1,2 [WARNING] 2,3 + 1,1,2 -> 1,2 [WARNING] 2 + + Should any start-value be allowed ("3,3,3"), or should + auto-numbered lists be limited to begin with ordinal-1 ("1", "A", + "a", "I", or "i")? + + __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 + &group_id=38414&atid=422032 + +4. Alternative proposed by Tony Ibbs:: + + #1. First item. + #3. Aha - I edited this in later. + #2. Second item. + + The initial proposal required unique enumerators within a list, but + this limits the convenience of a feature of already limited + applicability and convenience. Not a useful requirement; dropped. + + Instead, simply prepend a "#" to a standard list enumerator to + indicate auto-enumeration. The numbers (or letters) of the + enumerators themselves are not significant, except: + + - as a sequence indicator (arabic, roman, alphabetic; upper/lower), + + - and perhaps as a start value (first list item). + + Advantages: explicit, any enumeration sequence possible. + Disadvantages: a bit ugly. + .. Local Variables: -- cgit v1.2.1 From 29e9868d5635c52603e8101344cf26169bfa5328 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 02:20:57 +0000 Subject: - Field lists' field_body may be empty. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@54 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index d47238b4d..9f3d1836a 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -302,7 +302,8 @@ http://www.oasis-open.org/html/tm9901.htm). - + + -- cgit v1.2.1 From b5f1e2618bd540436686dc1593d2c398b9558f00 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 02:22:22 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@55 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/problems.txt | 43 +++++++++++++++++++++++---------------- docs/dev/todo.txt | 13 +++++++++--- docs/peps/pep-0257.txt | 2 +- docs/peps/pep-0258.txt | 2 +- docs/ref/rst/directives.txt | 6 +++--- docs/ref/rst/restructuredtext.txt | 22 ++++++++++++-------- 6 files changed, 54 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index f366bdf3f..e97887a01 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -213,27 +213,36 @@ People will write enumerated lists in all different ways. It is folly to try to come up with the "perfect" format for an enumerated list, and limit the docstring parser's recognition to that one format only. -Rather, the parser should recognize a variety of enumerator styles, -marking each block as a potential enumerated list item (PELI), and -interpret the enumerators of adjacent PELIs to decide whether they -make up a consistent enumerated list. - -If a PELI is labeled with a "1.", and is immediately followed by a -PELI labeled with a "2.", we've got an enumerated list. Or "(A)" -followed by "(B)". Or "i)" followed by "ii)", etc. The chances of -accidentally recognizing two adjacent and consistently labeled PELIs, -are acceptably small. - -For an enumerated list to be recognized, the following must be true: - -- the list must consist of multiple adjacent list items (2 or more) -- the enumerators must all have the same format -- the enumerators must be sequential - +Rather, the parser should recognize a variety of enumerator styles. It is also recommended that the enumerator of the first list item be ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be able to begin a list at an arbitrary enumeration. +An initial idea was to require two or more consistent enumerated list +items in a row. This idea proved impractical and was dropped. In +practice, the presence of a proper enumerator is enough to reliably +recognize an enumerated list item; any ambiguities are reported by the +parser. Here's the original idea for posterity: + + The parser should recognize a variety of enumerator styles, mark + each block as a potential enumerated list item (PELI), and + interpret the enumerators of adjacent PELIs to decide whether they + make up a consistent enumerated list. + + If a PELI is labeled with a "1.", and is immediately followed by a + PELI labeled with a "2.", we've got an enumerated list. Or "(A)" + followed by "(B)". Or "i)" followed by "ii)", etc. The chances + of accidentally recognizing two adjacent and consistently labeled + PELIs, are acceptably small. + + For an enumerated list to be recognized, the following must be + true: + + - the list must consist of multiple adjacent list items (2 or + more) + - the enumerators must all have the same format + - the enumerators must be sequential + Definition List Markup ====================== diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 52e137f45..c6d8f96d6 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -33,6 +33,9 @@ General checked for correctness and refactored. I'm afraid it's a bit of a spaghetti mess now. + - Change application error exceptions to use "StandardError" as + their base class instead of "Exception". + - Add validation? See http://pytrex.sourceforge.net, RELAX NG. - Ask Python-dev for opinions (GvR for a pronouncement) on special @@ -63,7 +66,7 @@ General - Implement a PEP reader. - Add support for character set encodings on input & output, Unicode - internally. + internally. Need a Unicode -> HTML entities codec for HTML writer? Specification @@ -181,7 +184,9 @@ reStructuredText Parser - Add RFC-2822 header parsing (for PEP, email Readers). - Change ``.. meta::`` to use a "pending" element, only activated for - HTML writers. + HTML writers (done). Add reader/writer/parser attributes to pending + elements (done). Figure out a way for transforms to know what + reader/writer is in control (@@@ in docutils.transforms.components). - Allow for variant styles by interpreting indented lists as if they weren't indented? For example, currently the list below will be @@ -209,7 +214,7 @@ reStructuredText Parser "Structuring: a summary; and an attempt at EBNF", item 4. - Make the parser modular. Be able to turn on/off constructs, add - them at run time. + them at run time. Or is subclassing enough? Directives @@ -349,6 +354,8 @@ HTML Writer - Return a string instead of writing to a file? Leave all I/O up to the client? +- Use lowercase element & attribute names for XHTML compatibility? + Coding Conventions ================== diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index af1239568..fc5edbcb0 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -114,7 +114,7 @@ Specification This type of docstring is only appropriate for C functions (such as built-ins), where introspection is not possible. However, - the nature of the return value cannot be determined by + the nature of the *return value* cannot be determined by introspection, so it should be mentioned. The preferred form for such a docstring would be something like:: diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 6a55e20de..cf7fbb6a6 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -299,7 +299,7 @@ Specification Most Readers will have to be told what parser to use. So far (see the list of examples below), only the Python Source Reader - (PySource) will be able to determine the syntax on its own. + (PySource) will be able to determine the parser on its own. Responsibilities: diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cbb8b4609..8012ee9ed 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -157,9 +157,9 @@ legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. ---------------------- - Document Components ---------------------- +---------------- + Document Parts +---------------- Table of Contents ================= diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f352c9716..37b53f784 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -648,23 +648,27 @@ The following formatting types are recognized: - surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". - suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". -A system message will be generated for each of the following cases: +While parsing an enumerated list, a new list will be started whenever: -- The enumerators do not all have the same format and sequence type. +- An enumerator is encountered which does not have the same format and + sequence type as the current list (e.g. "1.", "(a)" produces two + separate lists). -- The enumerators are not in sequence (i.e., "1.", "3." generates a - level-1 [info] system message and produces two separate lists). +- The enumerators are not in sequence (e.g., "1.", "3." produces two + separate lists). It is recommended that the enumerator of the first list item be ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values -will be recognized, they may not be supported by the output format. +will be recognized, they may not be supported by the output format. A +level-1 [info] system message will be generated for any list beginning +with a non-ordinal-1 enumerator. Lists using Roman numerals must begin with "I"/"i" or a multi-character value, such as "II" or "XV". Any other -single-character Roman numeral ("V", "X", etc.) will be interpreted as -a letter of the alphabet, not as a Roman numeral. Likewise, lists -using letters of the alphabet may not begin with "I"/"i", since these -are recognized as Roman numeral 1. +single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be +interpreted as a letter of the alphabet, not as a Roman numeral. +Likewise, lists using letters of the alphabet may not begin with +"I"/"i", since these are recognized as Roman numeral 1. Nested enumerated lists must be created with indentation. For example:: -- cgit v1.2.1 From 02a60820cc60749e5a12ace6d668609a758eb7cf Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 03:17:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@58 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c6d8f96d6..5c87d280d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -337,8 +337,6 @@ HTML Writer conform to the regular expression ``[a-z][-a-z0-9]*``. See ``docutils.utils.id()``. - .. _HTML 4.01 spec: http://www.w3.org/TR/html401 - .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 .. [#] Source: `HTML 4.0 in Netscape and Explorer`__. __ http://www.webreference.com/dev/html4nsie/index.html -- cgit v1.2.1 From 22738cef8ca58db6d32fc6f3516ec0ff4391d9de Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 03:42:38 +0000 Subject: markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@59 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index b58c6a186..2106ad807 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1288,7 +1288,7 @@ ugly or confusing (depending on which alternative is chosen). In response, Fred came up with "a stricter and more explicit rule [which] would be to only auto-number silently if *all* the - enumerators of a list were identical". In that case: + enumerators of a list were identical". In that case:: 1,1,1 -> 1,2,3 1,2,2 -> 1,2 [WARNING] 2 -- cgit v1.2.1 From 2b90f282714e868285516c9f08fdf0bbef9b3f17 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 30 Apr 2002 04:02:19 +0000 Subject: markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@61 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 2106ad807..4faae1f98 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -52,7 +52,7 @@ Anything wrong with this? :: 1. First line, second line. -Problem? +Problem? :: 1. First para. -- cgit v1.2.1 From 20ce026c0fff14e2503378233b3d29eb17104570 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 5 May 2002 14:46:34 +0000 Subject: whitespace git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@68 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 14 +++++++------- docs/user/rst/quickstart.txt | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 886a02107..7208b8b9f 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -17,7 +17,7 @@ -

http://docutils.sourceforge.net/docs/rst/quickref.html
Being a cheat-sheet for reStructuredText
Version 0.8 of 2002-04-19 @@ -153,7 +153,7 @@ (with backslash) or quote them (with double backquotes; i.e. use inline literals). -

In detail, the reStructuredText specifications says that in +

In detail, the reStructuredText specifications says that in inline markup:

  1. The start-string must start a text block or be @@ -165,7 +165,7 @@ followed by whitespace,  ' " . , : ; ! ? - ) ] } or  >.
  2. If a start-string is immediately preceded by one of  - ' " ( [ { or  <, it must not be + ' " ( [ { or  <, it must not be immediately followed by the corresponding character from  ' " ) ] } or  >.
  3. An end-string must be separated by at least one @@ -610,7 +610,7 @@ This means that something like:

    Doctest blocks are interactive Python sessions. They begin with ">>>" and end with a blank line. - +

    >>> print "This is a doctest block."
    This is a doctest block.     @@ -700,9 +700,9 @@ A transition marker is a horizontal line

    A transition marker is a horizontal line of 4 or more repeated punctuation characters.

    - +
    - +

    A transition should not begin or end a section or document, nor should two transitions be immediately adjacent. @@ -766,7 +766,7 @@ A transition marker is a horizontal line

    They may be assigned 'autonumber labels' - for instance, 4 and 3. - +

    diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index be9139d60..1de7abf59 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -168,7 +168,7 @@ after a blank line. Unlike the other two, the definition lists consist of a term, and the definition of that term. The format of a definition list is:: - what + what Definition lists associate a term with a definition. *how* @@ -178,7 +178,7 @@ after a blank line. Results in: - what + what Definition lists associate a term with a definition. *how* @@ -222,7 +222,7 @@ from the output:: :: - This is preformatted text, and the + This is preformatted text, and the last "::" paragraph is removed Results in: -- cgit v1.2.1 From 7dca77f3557441e3579aaba28e4d083615b549eb Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 5 May 2002 15:39:21 +0000 Subject: *** empty log message *** git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@87 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index 463844a68..1a1aa6e8b 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -92,7 +92,7 @@ http://docutils.sourceforge.net/spec/docutils.dtd. - -- cgit v1.2.1 From 34f7a6d1ac6f52cf920a933aba804f54c7be5525 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 5 May 2002 15:49:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@91 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 190 +++++++++++++++++++++++++++++-------------------- docs/peps/pep-0258.txt | 16 +++-- 2 files changed, 122 insertions(+), 84 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5c87d280d..c262f6509 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -9,6 +9,9 @@ To Do ===== +Priority items are marked with "@" symbols. The more @s, the higher +the priority. + General ------- @@ -33,9 +36,6 @@ General checked for correctness and refactored. I'm afraid it's a bit of a spaghetti mess now. - - Change application error exceptions to use "StandardError" as - their base class instead of "Exception". - - Add validation? See http://pytrex.sourceforge.net, RELAX NG. - Ask Python-dev for opinions (GvR for a pronouncement) on special @@ -43,11 +43,6 @@ General pollution. Ask opinions on whether or not Docutils should recognize & use them. -- Provide a mechanism to pass options to Readers, Writers, and Parsers - through docutils.core.publish/Publisher? Or create custom - Reader/Writer/Parser objects first, and pass *them* to - publish/Publisher? - - In reader.get_reader_class (& parser & writer too), should we be importing 'standalone' or 'docutils.readers.standalone'? (This would avoid importing top-level modules if the module name is not in @@ -57,16 +52,14 @@ General permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?) -- The "Docutils System Messages" section appears even if no actual - system messages are there. They must be below the threshold. The - transform should be fixed. - -- TOC transform: use alt-text for inline images. +- @@@ Implement a PEP reader. -- Implement a PEP reader. +- @@ Add support for character set encodings on input & output, Unicode + internally. -- Add support for character set encodings on input & output, Unicode - internally. Need a Unicode -> HTML entities codec for HTML writer? + - Use an "encoding" directive, and/or an "encoding" field in field + lists & PEP headers. (The same could apply to "language".) + - Need a Unicode -> HTML entities codec for HTML writer? Specification @@ -101,8 +94,8 @@ reStructuredText Parser - And for the sake of completeness, should definition list terms be allowed to be very long (two or more lines) also? -- Allow hyperlink references to targets in other documents? Not in an - HTML-centric way, though (it's trivial to say +- Support generic hyperlink references to targets in other documents? + Not in an HTML-centric way, though (it's trivial to say ``http://www.whatever.com/doc#name``, and useless in non-HTML contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. @@ -176,18 +169,9 @@ reStructuredText Parser the left edge of the first line if it began on the same line as the field name. -- Allow syntax constructs to be added or disabled at run-time. - - Make footnotes two-way, GNU-style? What if there are multiple references to a single footnote? -- Add RFC-2822 header parsing (for PEP, email Readers). - -- Change ``.. meta::`` to use a "pending" element, only activated for - HTML writers (done). Add reader/writer/parser attributes to pending - elements (done). Figure out a way for transforms to know what - reader/writer is in control (@@@ in docutils.transforms.components). - - 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:: @@ -213,8 +197,11 @@ reStructuredText Parser See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's "Structuring: a summary; and an attempt at EBNF", item 4. -- Make the parser modular. Be able to turn on/off constructs, add - them at run time. Or is subclassing enough? +- 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? Directives @@ -228,41 +215,99 @@ Directives - Implement directives: - - html.imagemap + - html.imagemap (Useful outside of HTML? If not, replace with image + only in non-HTML writers?) - - components.endnotes, .citations, .topic, .sectnum (section - numbering; add support to .contents; could be cmdline option also) + - parts.endnotes, .citations, .topic, .sectnum (section numbering; + add support to .contents; could be cmdline option also) - misc.raw - - misc.include: ``#include`` one file in another. But how to - parse wrt sections, reference names, conflicts? + - misc.include: ``#include`` one file in another. But how to parse + wrt sections, reference names, conflicts? Parse it in the current + document's context (C-preprocessor semantics), or separately and + then merge? + + 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:: + `` will read a standard include file from + ``docutils/include/``. (Should "quotes" be required around + non-standard include files?) - misc.exec: Execute Python code & insert the results. Perhaps dangerous? - misc.eval: Evaluate an expression & insert the text. At parse - time or at substitution time? + time or at substitution time? Dangerous? Perhaps limit to canned + macros; see text.date_ below. + + - @@@ body.qa/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 (optional attribute "qa" done). - - block.qa: Questions & Answers. Implement as a generic two-column - marked list? Or as a standalone construct? + New elements would be required. Perhaps:: - - block.columns: Multi-column table/list, with number of columns as + + + + + + + - body.columns: Multi-column table/list, with number of columns as argument. - - block.verse: Paragraphs with linebreaks preserved. A directive - would be easy; what about a literal-block-like prefix, perhaps - ';;'? E.g.:: + - body.verse: Paragraphs with linebreaks preserved, *and* inline + markup support too. A directive would be easy; what about a + literal-block-like prefix, perhaps ';;'? (It's a semi-literal + block, after all.) Example:: + + Take it away, Eric the Orchestra Leader! ;; + + A one, two, a one two three four + + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? + + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? - Take it away, Eric the orchestra leader! ;; + Singing... - Half a bee, - Philosophically, - Must ipso-facto - Half not be. - You see? + New elements would be required. Perhaps:: - ... + + + + + We could get away without "line" elements, treating line breaks + within "stanzas" as significant. But explicit is perhaps better + than implicit. + + Within a "verse" element, should any other constructs be allowed? + Should lists be recognized? The equivalent of block quotes (i.e., + further indented blocks) would be nested verse elements. These + could be "chorus" blocks. + + Perhaps individually indented "continuation lines" should also be + recognized (maybe with a "continuation" attribute on the "line" + element, or significant whitespace in a single "line"):: + + "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by + Ewan McTeagle (for Lassie O'Shea): ;; + + Lend us a couple of bob till Thursday. + I'm absolutely stint. + But I'm expecting a postal order and I can pay you back + as soon as it comes. + Love, Ewan. - colorize.python: Colorize Python code. Fine for HTML output, but what about other formats? Revert to a literal block? Do we need @@ -271,9 +316,15 @@ Directives use. Use a factory function "transformFF()" which returns either "HTMLTransform()" instance or "GenericTransform" instance? - - text.date: Datestamp. For substitutions. + - _`text.date`: Datestamp. For substitutions. + + - Combined with misc.include, implement canned macros? E.g.:: + + .. include:: + + Today's date is |date|. - - Combined with misc.include, implement canned macros? + Where "macros" contains ``.. |date| date::``, among others. Unimplemented Transforms @@ -322,37 +373,17 @@ Unimplemented Transforms HTML Writer ----------- -- Considerations for an HTML Writer [#]_: +- @@ Allow for style sheet info to be passed in, either as a , + or as embedded style info. - - Boolean attributes. ```` is good, ```` is bad. Use a special value in attribute - mappings, such as ``None``? +- @ Construct a templating system, as in ht2html/yaptu, using + directives and substitutions for dynamic stuff. - - Escape double-dashes inside comments. - - - Put the language code into an appropriate element's LANG - attribute (?). - - - Docutils identifiers (the "class" and "id" attributes) will - conform to the regular expression ``[a-z][-a-z0-9]*``. See - ``docutils.utils.id()``. - - .. [#] Source: `HTML 4.0 in Netscape and Explorer`__. - __ http://www.webreference.com/dev/html4nsie/index.html - -- Allow for style sheet info to be passed in, either as a , or - as embedded style info. - -- Construct a templating system, as in ht2html/yaptu, using directives - and substitutions for dynamic stuff. - -- Improve the granularity of document parts in the HTML writer, so +- @@ Improve the granularity of document parts in the HTML writer, so that one could just grab the parts needed. -- Return a string instead of writing to a file? Leave all I/O up to - the client? - -- Use lowercase element & attribute names for XHTML compatibility? +- @@ Return a string instead of writing to a file? Leave all I/O up + to the client? Or up to an explicit distributor/filer? Coding Conventions @@ -367,13 +398,14 @@ PEPs, with the following clarifications: lines & indentation), except for degenerate class or method definitions (i.e., ``class X: pass`` is O.K.). - Lines should be no more than 78 or 79 characters long. -- "CamelCase" shall be used for class names. +- "CamelCase" shall be used 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 joined words, use lowercase (e.g. 'tagname'). For long names with three or more joined words, or where it's hard to parse the split between two words, use lowercase_with_underscores (e.g., 'note_explicit_target', - 'explicit_target'). + 'explicit_target'). If in doubt, use underscores. __ http://www.python.org/peps/pep-0008.html __ http://www.python.org/peps/pep-0257.html diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index cf7fbb6a6..e760a9123 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -282,6 +282,11 @@ Specification method passes its input to its Reader, then passes the resulting document tree through its Writer to its destination. + Calling the "publish" function (or instantiating a "Publisher" + object) with component names will result in default behavior. For + custom behavior (setting component options), create custom + component objects first, and pass *them* to publish/Publisher. + Readers ------- @@ -441,7 +446,8 @@ Specification require anything other than monolithic output. Perhaps merge the HTML "distributor" into "writer" variants? - Perhaps translator/writer instead of writer/distributor? + Perhaps translator/writer instead of writer/distributor? Or + "filer" instead of "distributor"? Responsibilities: @@ -487,7 +493,7 @@ Specification - Package "docutils.parsers": markup parsers_. - - Function "get_parser_class(parsername)" returns a parser + - Function "get_parser_class(parser_name)" returns a parser module by name. Class "Parser" is the base class of specific parsers. (docutils/parsers/__init__.py) @@ -497,7 +503,7 @@ Specification - Package "docutils.readers": context-aware input readers. - - Function "get_reader_class(readername)" returns a reader + - Function "get_reader_class(reader_name)" returns a reader module by name or alias. Class "Reader" is the base class of specific readers. (docutils/readers/__init__.py) @@ -509,11 +515,11 @@ Specification - Package "docutils.writers": output format writers. - - Function "get_writer_class(writername)" returns a writer + - Function "get_writer_class(writer_name)" returns a writer module by name. Class "Writer" is the base class of specific writers. (docutils/writers/__init__.py) - - Module "docutils.writers.pprint" is a simple internal + - Module "docutils.writers.pseudoxml" is a simple internal document tree writer; it writes indented pseudo-XML. - Module "docutils.writers.html4css1" is a simple HyperText -- cgit v1.2.1 From 6b21c047594ea25b4fa75f903e9b315859735116 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 5 May 2002 17:06:02 +0000 Subject: fixed hyperlinks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@97 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.txt | 7 ++----- docs/ref/rst/introduction.txt | 1 - 2 files changed, 2 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index a75fd1d4d..93fba9420 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -19,8 +19,8 @@ to syntax constructs. .. contents:: -Python Source Reader -==================== +Model +===== The Python Source Reader ("PySource") model that's evolving in my mind goes something like this: @@ -158,9 +158,6 @@ The role may be one of 'package', 'module', 'class', 'method', 'exception_class', 'exception', 'warning_class', or 'warning'. Other roles may be defined. -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html -.. _Docutils: http://docutils.sourceforge.net/ .. _pysource.dtd: http://docutils.sourceforge.net/spec/pysource.dtd .. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 3d7cfc5f8..4ffb2d053 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -294,7 +294,6 @@ followed. .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ -.. _Docutils: http://docutils.sourceforge.net/ .. _master PEP repository: http://www.python.org/peps/ -- cgit v1.2.1 From d639a557186f9e7493682320b59a9897a07876a3 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 6 May 2002 04:03:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@100 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 47 +++++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c262f6509..fafddb76b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -215,18 +215,24 @@ Directives - Implement directives: - - html.imagemap (Useful outside of HTML? If not, replace with image - only in non-HTML writers?) + - _`html.imagemap` (Useful outside of HTML? If not, replace with + image only in non-HTML writers?) - - parts.endnotes, .citations, .topic, .sectnum (section numbering; - add support to .contents; could be cmdline option also) + - _`parts.endnotes` + + - _`parts.citations` + + - _`parts.topic` + + - _`parts.sectnum` (section numbering; add support to .contents; + could be cmdline option also) - - misc.raw + - _`misc.raw` - - misc.include: ``#include`` one file in another. But how to parse - wrt sections, reference names, conflicts? Parse it in the current - document's context (C-preprocessor semantics), or separately and - then merge? + - _`misc.include`: ``#include`` one file in another. But how to + parse wrt sections, reference names, conflicts? Parse it in the + current document's context (C-preprocessor semantics), or + separately and then merge? Use C-preprocessor semantics for locating include files? E.g., ``.. include:: file.txt`` will read another file into the current @@ -235,14 +241,14 @@ Directives ``docutils/include/``. (Should "quotes" be required around non-standard include files?) - - misc.exec: Execute Python code & insert the results. Perhaps + - _`misc.exec`: Execute Python code & insert the results. Perhaps dangerous? - - misc.eval: Evaluate an expression & insert the text. At parse + - _`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. - - @@@ body.qa/faq/questions: Questions & Answers. Implement as a + - @@@ _`body.qa`/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 (optional attribute "qa" done). @@ -257,11 +263,12 @@ Directives - - body.columns: Multi-column table/list, with number of columns as - argument. + - _`body.columns`: Multi-column table/list, with number of columns + as argument. - - body.verse: Paragraphs with linebreaks preserved, *and* inline - markup support too. A directive would be easy; what about a + - _`body.verse`: Paragraphs with linebreaks preserved, *and* inline + markup support too. Use cases: verse (poetry, song lyrics, etc.), + address blocks. A directive would be easy; what about a literal-block-like prefix, perhaps ';;'? (It's a semi-literal block, after all.) Example:: @@ -309,16 +316,16 @@ Directives as soon as it comes. Love, Ewan. - - 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" + - _`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? - _`text.date`: Datestamp. For substitutions. - - Combined with misc.include, implement canned macros? E.g.:: + - Combined with misc.include_, implement canned macros? E.g.:: .. include:: -- cgit v1.2.1 From 30a6456af9993b056a8f1365d9cb76c1a0cd19bf Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 6 May 2002 04:06:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@101 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fafddb76b..45be4a5c3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -248,10 +248,10 @@ Directives time or at substitution time? Dangerous? Perhaps limit to canned macros; see text.date_ below. - - @@@ _`body.qa`/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 (optional attribute "qa" done). + - @@@ _`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 (optional attribute "qa" done). New elements would be required. Perhaps:: -- cgit v1.2.1 From 6d688c4ee731218a8b027ba32e7f733676fee1f0 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 6 May 2002 04:11:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@102 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 45be4a5c3..57ccc214e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -269,8 +269,8 @@ Directives - _`body.verse`: Paragraphs with linebreaks preserved, *and* inline markup support too. Use cases: verse (poetry, song lyrics, etc.), address blocks. A directive would be easy; what about a - literal-block-like prefix, perhaps ';;'? (It's a semi-literal - block, after all.) Example:: + literal-block-like prefix, perhaps "``;;``"? (It is a semi- + literal-block, after all.) Example:: Take it away, Eric the Orchestra Leader! ;; -- cgit v1.2.1 From b5cd95550cef5b1e29e52a497acb3dd4b3192f96 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 6 May 2002 04:14:46 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@103 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 57ccc214e..2c48bc7e8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -248,7 +248,7 @@ Directives time or at substitution time? Dangerous? Perhaps limit to canned macros; see text.date_ below. - - @@@ _`body.qa` (directive a.k.a. "faq" "questions"): Questions & + - @@@ _`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 (optional attribute "qa" done). @@ -269,8 +269,8 @@ Directives - _`body.verse`: Paragraphs with linebreaks preserved, *and* inline markup support too. Use cases: verse (poetry, song lyrics, etc.), address blocks. A directive would be easy; what about a - literal-block-like prefix, perhaps "``;;``"? (It is a semi- - literal-block, after all.) Example:: + literal-block-like prefix, perhaps "``;;``"? (It is, after all, a + *semi-literal* literal block, no?) Example:: Take it away, Eric the Orchestra Leader! ;; -- cgit v1.2.1 From e5744d83bfa217b861297a76840492691f1896d2 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 7 May 2002 04:22:10 +0000 Subject: name improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@109 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index e760a9123..4acff1039 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -542,7 +542,7 @@ Specification their language identifier (as defined in `Choice of Docstring Format`_ above), converting dashes to underscores. - - Function "getlanguage(languagecode)", returns matching + - Function "get_language(language_code)", returns matching language module. (docutils/languages/__init__.py) - Module "docutils.languages.en" (English). -- cgit v1.2.1 From 9957cf043607b483c6e8e869549911be5ce5a4d0 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 7 May 2002 04:23:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@110 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2c48bc7e8..675b546f8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -57,6 +57,7 @@ General - @@ Add support for character set encodings on input & output, Unicode internally. + - Default UTF-8 on both input & output, overrideable. - Use an "encoding" directive, and/or an "encoding" field in field lists & PEP headers. (The same could apply to "language".) - Need a Unicode -> HTML entities codec for HTML writer? @@ -135,11 +136,11 @@ reStructuredText Parser - issue a warning when processing documents with no default role which contain interpreted text with no explicitly specified role -- Fix the parser's indentation handling to conform with the stricter - definition in the spec. (Explicit markup blocks should be strict or - forgiving?) +- @@ 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 +- @@ 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 @@ -266,9 +267,9 @@ Directives - _`body.columns`: Multi-column table/list, with number of columns as argument. - - _`body.verse`: Paragraphs with linebreaks preserved, *and* inline - markup support too. Use cases: verse (poetry, song lyrics, etc.), - address blocks. A directive would be easy; what about a + - @@ _`body.verse`: Paragraphs with linebreaks preserved, *and* + inline markup support too. Use cases: verse (poetry, song lyrics, + etc.), address blocks. A directive would be easy; what about a literal-block-like prefix, perhaps "``;;``"? (It is, after all, a *semi-literal* literal block, no?) Example:: -- cgit v1.2.1 From 1ec0693d345f079e7bc24811979021233dd25efe Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 9 May 2002 04:18:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@115 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 125 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 108 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 675b546f8..ff7812339 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -44,7 +44,7 @@ General & use them. - In reader.get_reader_class (& parser & writer too), should we be - importing 'standalone' or 'docutils.readers.standalone'? (This would + importing "standalone" or "docutils.readers.standalone"? (This would avoid importing top-level modules if the module name is not in docutils/readers. Potential nastiness.) @@ -97,7 +97,7 @@ reStructuredText Parser - Support generic hyperlink references to targets in other documents? Not in an HTML-centric way, though (it's trivial to say - ``http://www.whatever.com/doc#name``, and useless in non-HTML + ``http://www.example.com/doc#name``, and useless in non-HTML contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. @@ -122,7 +122,7 @@ reStructuredText Parser - 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 + 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 @@ -300,9 +300,11 @@ Directives than implicit. Within a "verse" element, should any other constructs be allowed? - Should lists be recognized? The equivalent of block quotes (i.e., - further indented blocks) would be nested verse elements. These - could be "chorus" blocks. + Should lists be recognized? No; verse blocks are variations on + paragraphs, and need not contain arbitrary nested body elements. + However, the equivalent of block quotes (i.e., further indented + blocks) would be nested verse elements. These could be "chorus" + blocks. Perhaps individually indented "continuation lines" should also be recognized (maybe with a "continuation" attribute on the "line" @@ -312,7 +314,7 @@ Directives Ewan McTeagle (for Lassie O'Shea): ;; Lend us a couple of bob till Thursday. - I'm absolutely stint. + I'm absolutely skint. But I'm expecting a postal order and I can pay you back as soon as it comes. Love, Ewan. @@ -394,30 +396,119 @@ HTML Writer to the client? Or up to an explicit distributor/filer? +Project Policies +================ + Coding Conventions -================== +------------------ -This project shall follow the generic coding conventions as specified -in the `Style Guide for Python Code`__ and `Docstring Conventions`__ -PEPs, with the following clarifications: +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: - 4 spaces per indentation level. No tabs. + - 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 or 79 characters long. -- "CamelCase" shall be used for class names (except for element - classes in docutils.nodes). + +- Lines should be no more than 78 characters long. + +- Use "CamelCase" 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 joined - words, use lowercase (e.g. 'tagname'). For long names with three or + words, use lowercase (e.g. "tagname"). For long names with three or more joined 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. + 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. __ http://www.python.org/peps/pep-0008.html __ http://www.python.org/peps/pep-0257.html + +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. + +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 + +- 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_ is the place to put new, untried code. See `Additions + to Docutils`_ below. + +Please consider subscribing to the appropriate `mailing lists`_. + +.. _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: + http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ +.. _mailing lists: ../index.html#mailing-lists + + +Additions to Docutils +````````````````````` + +Additions to the project, such as new components, should be developed +in in the sandbox_ until they're in good shape, usable, and reasonably +complete. Adding to the `main source tree`_ 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. + + The sandbox 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. Each developer who wants to play in the + sandbox should create their own subdirectory (suggested name: + SourceForge ID, or given name + family initial). It's OK to make a + mess! But please, play nice. + +- "Good shape" means that the component code is clean, readable, and + free of junk (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. + +- "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. + .. Local Variables: -- cgit v1.2.1 From 77568921276db01c972cb1ee4dd8b42d7bf1b7a6 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 10 May 2002 03:50:05 +0000 Subject: - Clarified purpose of directives. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@116 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 66 +++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 37b53f784..07c16ccd5 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1581,6 +1581,26 @@ Directives DTD elements: depend on the directive. +Directives are an extension mechanism for reStructuredText, a way of +adding support for new constructs without adding new syntax. +Directives which have been implemented and registered in the reference +reStructuredText parser are described in the `reStructuredText +Directives`_ document. For example, here's how an image may be +placed:: + + .. image:: mylogo.png + +A figure (a graphic with a caption) may placed like this:: + + .. figure:: larch.png + The larch. + +An admonition (note, caution, etc.) contains other body elements:: + + .. note:: This is a paragraph + + - Here is a bullet list. + Directives are indicated by an explicit markup start (".. ") followed by the directive type, two colons, and whitespace. Directive types are case-insensitive single words (alphanumerics plus internal @@ -1609,42 +1629,20 @@ interpreted as a directive block. Simple directives may not require any text beyond the directive data (if that), and will not process any following indented text. -Directives which have been implemented and registered in the reference -reStructuredText parser are described in the `reStructuredText -Directives`_ document. Below are examples of implemented directives. - Directives are meant for the arbitrary processing of their contents (the directive data & text block), which can be transformed into -something possibly unrelated to the original text. Directives are -used as an extension mechanism for reStructuredText, a way of adding -support for new constructs without adding new syntax. For example, -here's how an image may be placed:: - - .. image:: mylogo.png - -A figure (a graphic with a caption) may placed like this:: - - .. figure:: larch.png - The larch. - -An admonition (note, caution, etc.) contains other body elements:: - - .. note:: This is a paragraph - - - Here is a bullet list. - -It may also be possible for directives to be used as pragmas, to -modify the behavior of the parser, such as to experiment with -alternate syntax. There is no parser support for this functionality -at present; if a reasonable need for pragma directives is found, they -may be supported. - -Directives normally do not survive as "directive" elements past the -parsing stage; they are a *parser construct* only, and have no -intrinsic meaning outside of reStructuredText. Instead, the parser -will transform recognized directives into (possibly specialized) -document elements. Unknown directives will trigger level-3 (error) -system messages. +something possibly unrelated to the original text. It may also be +possible for directives to be used as pragmas, to modify the behavior +of the parser, such as to experiment with alternate syntax. There is +no parser support for this functionality at present; if a reasonable +need for pragma directives is found, they may be supported. + +Directives do not survive as "directive" elements past the parsing +stage; they are a *parser construct* only, and have no intrinsic +meaning outside of reStructuredText. Instead, the parser will +transform recognized directives into (possibly specialized) document +elements. Unknown directives will trigger level-3 (error) system +messages. Syntax diagram:: -- cgit v1.2.1 From 0933cae075aafd615c9a0519aa07cdee667d8d38 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 10 May 2002 03:51:13 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@117 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index ff7812339..bbab8bddb 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -136,6 +136,10 @@ reStructuredText Parser - issue a warning when processing documents with no default role which contain interpreted text with no explicitly specified role +- Perhaps the "default default" role for interpreted text could be + "title", as in, "title of a book". It'd be a text-only reference, + no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. + - @@ Fix the parser's indentation handling to conform with the stricter definition in the spec. (Explicit markup blocks should be strict or forgiving?) @@ -402,11 +406,20 @@ Project Policies 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: +Conventions`__ PEPs, with the following clarifications (from most to +least important): -- 4 spaces per indentation level. No tabs. +- 4 spaces per indentation level. No tabs. Indent continuation lines + according to the Emacs' python-mode standard. - No one-liner compound statements (i.e., no ``if x: return``: use two lines & indentation), except for degenerate class or method @@ -418,11 +431,12 @@ Conventions`__ PEPs, with the following clarifications: docutils.nodes). - Use "lowercase" or "lowercase_with_underscores" for function, - method, and variable names. For short names, maximum two joined - words, use lowercase (e.g. "tagname"). For long names with three or - more joined 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. + 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. -- cgit v1.2.1 From 8f2153983e79ea721ea895853f12746eb824b58f Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 11 May 2002 16:45:40 +0000 Subject: more directive clarification git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@121 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 07c16ccd5..32d03f7ea 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1582,11 +1582,14 @@ Directives DTD elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new syntax. -Directives which have been implemented and registered in the reference -reStructuredText parser are described in the `reStructuredText -Directives`_ document. For example, here's how an image may be -placed:: +adding support for new constructs without adding new syntax. All +standard directives (those implemented and registered in the reference +reStructuredText parser) are described in the `reStructuredText +Directives`_ document, and are always available. Any other directives +are domain-specific, and may require special action to make them +available when processing the document. + +For example, here's how an image may be placed:: .. image:: mylogo.png -- cgit v1.2.1 From 393114781fc407dd29fc736f05372e83552f0b5c Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 11 May 2002 16:46:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@122 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bbab8bddb..a629ea411 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -323,6 +323,10 @@ Directives as soon as it comes. Love, Ewan. + Directive name alternatives: verse, addressblock, address, + lineblock, lines, multiline, freeform, keeplines, nowrap, haiku, + keepbreaks, linebreaks. + - _`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" @@ -399,6 +403,28 @@ HTML Writer - @@ Return a string instead of writing to a file? Leave all I/O up to the client? Or up to an explicit distributor/filer? +- @@ Add an option to generate "source text" links (i.e., click to see + the source text). + +- @@ Add an option to generate "generated by Docutils from + reStructuredText source" messages, with links. + + +Front-End +--------- + +- Combine the common code from the existing front-ends into a single + library. + + - Use Optik to do modular command-line option processing. + + - The core would support all common options (--reader, --writer, + etc.). + + - Each front-end would add their own specific options (HTML: + --stylesheet, etc.), and perhaps disable common options that don't + apply. + Project Policies ================ -- cgit v1.2.1 From c9957ebcea78d02fcc2c316e4c902fdf83031c09 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 11 May 2002 18:38:10 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@123 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 32d03f7ea..31c22a184 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1596,6 +1596,7 @@ For example, here's how an image may be placed:: A figure (a graphic with a caption) may placed like this:: .. figure:: larch.png + The larch. An admonition (note, caution, etc.) contains other body elements:: -- cgit v1.2.1 From 0d70f08e9e19d34bfe082d13170ca4e525f92425 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 18 May 2002 02:51:30 +0000 Subject: - Minor edits. - Reworked Q&A as an enumerated list. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@128 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 549 +++++++++++++++++++++++++------------------------ 1 file changed, 277 insertions(+), 272 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index a3d4216d1..ecfa3186c 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -48,7 +48,7 @@ Benefits and software systems; readers are only meant to see the processed form, either on paper or via browser software. ReStructuredText is different: it is intended to be easily readable in source form, - without prior knowledge of the markup. ReStructuredText) is + without prior knowledge of the markup. ReStructuredText is entirely readable in plaintext format, and many of the markup forms match common usage (e.g., ``*emphasis*``), so it reads quite naturally. Yet it is rich enough to produce complex documents, @@ -67,7 +67,7 @@ Benefits Tools will become available in the near future, which will allow programmers to generate HTML for online help, XML for multiple - purposes, and perhaps eventually PDF/DocBook/LaTeX for printed + purposes, and eventually PDF/DocBook/LaTeX for printed documentation, essentially "for free" from the existing docstrings. The adoption of a standard will, at the very least, benefit docstring processing tools by preventing further @@ -98,7 +98,8 @@ Goals docstrings, without feeling hampered by the markup language. reStructuredText meets and exceeds all of these goals, and sets - its own goals as well, even more stringent. See "Features" below. + its own goals as well, even more stringent. See + "Docstring-Significant Features" below. The goals of this PEP are as follows: @@ -132,9 +133,9 @@ Goals be applied: a) Keep the existing PEP section structure constructs (one-line - section headers, indented body text). Subsections can - either be forbidden or supported with underlined headers in - the indented body text. + section headers, indented body text). Subsections can either + be forbidden, or supported with reStructuredText-style + underlined headers in the indented body text. b) Replace the PEP section structure constructs with the reStructuredText syntax. Section headers will require @@ -142,11 +143,11 @@ Goals and body text need not be indented (except for block quotes). - Support for RFC 2822 headers will be added to the reStructuredText - parser for PEPs (unambiguous given a specific context: the first - contiguous block of the document). It may be desired to - concretely specify what over/underline styles are allowed for PEP - section headers, for uniformity. + Support for RFC 2822 headers has been added to the + reStructuredText parser for PEPs (unambiguous given a specific + context: the first contiguous block of the document). It may be + desired to concretely specify what over/underline styles are + allowed for PEP section headers, for uniformity. Rationale @@ -203,8 +204,8 @@ Rationale - Perl POD [9]_ - Most Perl modules are documented in a format called POD -- Plain - Old Documentation. This is an easy-to-type, very low level + Most Perl modules are documented in a format called POD (Plain + Old Documentation). This is an easy-to-type, very low level format with strong integration with the Perl parser. Many tools exist to turn POD documentation into other formats: info, HTML and man pages, among others. However, the POD syntax takes @@ -250,6 +251,7 @@ Rationale - There has been no mechanism to get around the SText markup rules when a markup character is used in a non-markup context. + In other words, no way to escape markup. Proponents of implicit STexts have vigorously opposed proposals for explicit markup (XML, HTML, TeX, POD, etc.), and the debates @@ -268,8 +270,8 @@ Specification Please first take a look at "A ReStructuredText Primer" [13]_, a short and gentle introduction. The "Quick reStructuredText" user reference [14]_ quickly summarizes all of the markup constructs. - For complete and extensive details, the following documents - contain the full specification itself: + For complete and extensive details, please refer to the following + documents: - An Introduction to reStructuredText [15]_ @@ -458,263 +460,266 @@ Docstring-Significant Features Questions & Answers - Q1: Is reStructuredText rich enough? - - A1: Yes, it is for most people. If it lacks some construct that - is required for a specific application, it can be added via - the directive mechanism. If a common construct has been - overlooked and a suitably readable syntax can be found, it can - be added to the specification and parser. - - Q2: Is reStructuredText *too* rich? - - A2: For specific applications or individuals, perhaps. In - general, no. - - Since the very beginning, whenever a markup syntax has been - proposed on the Doc-SIG, someone has complained about the lack - of support for some construct or other. The reply was often - something like, "These are docstrings we're talking about, and - docstrings shouldn't have complex markup." The problem is - that a construct that seems superfluous to one person may be - absolutely essential to another. - - reStructuredText takes the opposite approach: it provides a - rich set of implicit markup constructs (plus a generic - extension mechanism for explicit markup), allowing for all - kinds of documents. If the set of constructs is too rich for - a particular application, the unused constructs can either be - removed from the parser (via application-specific overrides) - or simply omitted by convention. - - Q3: Why not use indentation for section structure, like - StructuredText does? Isn't it more "Pythonic"? - - A3: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG - post: - - I still think that using indentation to indicate - sectioning is wrong. If you look at how real books and - other print publications are laid out, you'll notice that - indentation is used frequently, but mostly at the - intra-section level. Indentation can be used to offset - lists, tables, quotations, examples, and the like. (The - argument that docstrings are different because they are - input for a text formatter is wrong: the whole point is - that they are also readable without processing.) - - I reject the argument that using indentation is Pythonic: - text is not code, and different traditions and conventions - hold. People have been presenting text for readability - for over 30 centuries. Let's not innovate needlessly. - - See "Section Structure via Indentation" in "Problems With - StructuredText" [18 ]_ for further elaboration. - - Q4: Why use reStructuredText for PEPs? What's wrong with the - existing standard? - - A4: The existing standard for PEPs is very limited in terms of - general expressibility, and referencing is especially lacking - for such a reference-rich document type. PEPs are currently - converted into HTML, but the results (mostly monospaced text) - are less than attractive, and most of the value-added - potential of HTML is untapped. - - Making reStructuredText a standard markup for PEPs will enable - much richer expression, including support for section - structure, inline markup, graphics, and tables. In several - PEPs there are ASCII graphics diagrams, which are all that - plaintext documents can support. Since PEPs are made - available in HTML form, the ability to include proper diagrams - would be immediately useful. - - Current PEP practices allow for reference markers in the form - "[1]" in the text, and the footnotes/references themselves are - listed in a section toward the end of the document. There is - currently no hyperlinking between the reference marker and the - footnote/reference itself (it would be possible to add this to - pep2html.py, but the "markup" as it stands is ambiguous and - mistakes would be inevitable). A PEP with many references - (such as this one ;-) requires a lot of flipping back and - forth. When revising a PEP, often new references are added or - unused references deleted. It is painful to renumber the - references, since it has to be done in two places and can have - a cascading effect (insert a single new reference 1, and every - other reference has to be renumbered; always adding new - references to the end is suboptimal). It is easy for - references to go out of sync. - - PEPs use references for two purposes: simple URL references - and footnotes. reStructuredText differentiates between the - two. A PEP might contain references like this:: - - Abstract - - This PEP proposes adding frungible doodads [1] to the - core. It extends PEP 9876 [2] via the BCA [3] - mechanism. - - References and Footnotes - - [1] http://www.example.org/ - - [2] PEP 9876, Let's Hope We Never Get Here - http://www.python.org/peps/pep-9876.html - - [3] "Bogus Complexity Addition" - - Reference 1 is a simple URL reference. Reference 2 is a - footnote containing text and a URL. Reference 3 is a footnote - containing text only. Rewritten using reStructuredText, this - PEP could look like this:: - - Abstract - ======== - - This PEP proposes adding `frungible doodads`_ to the - core. It extends PEP 9876 [#pep9876]_ via the BCA [#]_ - mechanism. - - .. _frungible doodads: http://www.example.org/ - - .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here - - __ http://www.python.org/peps/pep-9876.html - - .. [#] "Bogus Complexity Addition" - - URLs and footnotes can be defined close to their references if - desired, making them easier to read in the source text, and - making the PEPs easier to revise. The "References and - Footnotes" section can be auto-generated with a document tree - transform. Footnotes from throughout the PEP would be - gathered and displayed under a standard header. If URL - references should likewise be written out explicitly (in - citation form), another tree transform could be used. - - URL references can be named ("frungible doodads"), and can be - referenced from multiple places in the document without - additional definitions. When converted to HTML, references - will be replaced with inline hyperlinks (HTML tags). The - two footnotes are automatically numbered, so they will always - stay in sync. The first footnote also contains an internal - reference name, "pep9876", so it's easier to see the - connection between reference and footnote in the source text. - Named footnotes can be referenced multiple times, maintaining - consistent numbering. - - The "#pep9876" footnote could also be written in the form of a - citation:: - - It extends PEP 9876 [PEP9876]_ ... - - .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here - - Footnotes are numbered, whereas citations use text for their - references. - - Q5: Wouldn't it be better to keep the docstring and PEP proposals - separate? - - A5: The PEP markup proposal may be removed if it is deemed that - there is no need for PEP markup, or it could be made into a - separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines - [20]_, and PEP 9, Sample PEP Template [21]_ will be updated. - - It seems natural to adopt a single consistent markup standard - for all uses of structured plaintext in Python, and to propose - it all in one place. - - Q6: The existing pep2html.py script converts the existing PEP - format to HTML. How will the new-format PEPs be converted to - HTML? - - A6: One of the deliverables of the Docutils project [22]_ will be - a new version of pep2html.py with integrated reStructuredText - parsing. The Docutils project will support PEPs with a "PEP - Reader" component, including all functionality currently in - pep2html.py (auto-recognition of PEP & RFC references). - - Q7: Who's going to convert the existing PEPs to reStructuredText? - - A7: PEP authors or volunteers may convert existing PEPs if they - like, but there is no requirement to do so. The - reStructuredText-based PEPs will coexist with the old PEP - standard. The pep2html.py mentioned in A6 will process both - old and new standards. - - Q8: Why use reStructuredText for README and other ancillary files? - - A8: The reasoning given for PEPs in A4 above also applies to - README and other ancillary files. By adopting a standard - markup, these files can be converted to attractive - cross-referenced HTML and put up on python.org. Developers of - Python projects can also take advantage of this facility for - their own documentation. - - Q9: Won't the superficial similarity to existing markup - conventions cause problems, and result in people writing - invalid markup (and not noticing, because the plaintext looks - natural)? How forgiving is reStructuredText of "not quite - right" markup? - - A9: There will be some mis-steps, as there would be when moving - from one programming language to another. As with any - language, proficiency grows with experience. Luckily, - reStructuredText is a very little language indeed. - - As with any syntax, there is the possibility of syntax errors. - It is expected that a user will run the processing system over - their input and check the output for correctness. - - In a strict sense, the reStructuredText parser is very - unforgiving (as it should be; "In the face of ambiguity, - refuse the temptation to guess" [23]_ applies to parsing - markup as well as computer languages). Here's a design goal - from "An Introduction to reStructuredText" [15 ]_: - - 3. Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be - one and only one possible output (including error - output). - - While unforgiving, at the same time the parser does try to be - helpful by producing useful diagnostic output ("system - messages"). The parser reports problems, indicating their - level of severity (from least to most: debug, info, warning, - error, severe). The user or the client software can decide on - reporting thresholds; they can ignore low-level problems or - cause high-level problems to bring processing to an immediate - halt. Problems are reported during the parse as well as - included in the output, often with two-way links between the - source of the problem and the system message explaining it. - - Q10: Will the docstrings in the Python standard library modules be - converted to reStructuredText? - - A10: No. Python's library reference documentation is maintained - separately from the source. Docstrings in the Python - standard library should not try to duplicate the library - reference documentation. The current policy for docstrings - in the Python standard library is that they should be no more - than concise hints. - - Q11: I want to write all my strings in Unicode. Will anything - break? - - A11: The parser will fully support Unicode. It may not yet, but - only because nobody's gotten around to implementing or - testing Unicode support. Contributions are always welcome! - - Q12: Why does the community need a new structured text design? - What is wrong with existing markup methodologies? - - A12: The existing structured text designs are deficient. - @@@ - - For Python docstrings, there is no official standard. - @@@ + 1. Is reStructuredText rich enough? + + Yes, it is for most people. If it lacks some construct that is + required for a specific application, it can be added via the + directive mechanism. If a useful and common construct has been + overlooked and a suitably readable syntax can be found, it can + be added to the specification and parser. + + 2. Is reStructuredText *too* rich? + + For specific applications or individuals, perhaps. In general, + no. + + Since the very beginning, whenever a docstring markup syntax + has been proposed on the Doc-SIG, someone has complained about + the lack of support for some construct or other. The reply was + often something like, "These are docstrings we're talking + about, and docstrings shouldn't have complex markup." The + problem is that a construct that seems superfluous to one + person may be absolutely essential to another. + + reStructuredText takes the opposite approach: it provides a + rich set of implicit markup constructs (plus a generic + extension mechanism for explicit markup), allowing for all + kinds of documents. If the set of constructs is too rich for a + particular application, the unused constructs can either be + removed from the parser (via application-specific overrides) or + simply omitted by convention. + + 3. Why not use indentation for section structure, like + StructuredText does? Isn't it more "Pythonic"? + + Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG + post: + + I still think that using indentation to indicate sectioning + is wrong. If you look at how real books and other print + publications are laid out, you'll notice that indentation + is used frequently, but mostly at the intra-section level. + Indentation can be used to offset lists, tables, + quotations, examples, and the like. (The argument that + docstrings are different because they are input for a text + formatter is wrong: the whole point is that they are also + readable without processing.) + + I reject the argument that using indentation is Pythonic: + text is not code, and different traditions and conventions + hold. People have been presenting text for readability for + over 30 centuries. Let's not innovate needlessly. + + See "Section Structure via Indentation" in "Problems With + StructuredText" [18 ]_ for further elaboration. + + 4. Why use reStructuredText for PEPs? What's wrong with the + existing standard? + + The existing standard for PEPs is very limited in terms of + general expressibility, and referencing is especially lacking + for such a reference-rich document type. PEPs are currently + converted into HTML, but the results (mostly monospaced text) + are less than attractive, and most of the value-added potential + of HTML (especially inline hyperlinks) is untapped. + + Making reStructuredText a standard markup for PEPs will enable + much richer expression, including support for section + structure, inline markup, graphics, and tables. In several + PEPs there are ASCII graphics diagrams, which are all that + plaintext documents can support. Since PEPs are made available + in HTML form, the ability to include proper diagrams would be + immediately useful. + + Current PEP practices allow for reference markers in the form + "[1]" in the text, and the footnotes/references themselves are + listed in a section toward the end of the document. There is + currently no hyperlinking between the reference marker and the + footnote/reference itself (it would be possible to add this to + pep2html.py, but the "markup" as it stands is ambiguous and + mistakes would be inevitable). A PEP with many references + (such as this one ;-) requires a lot of flipping back and + forth. When revising a PEP, often new references are added or + unused references deleted. It is painful to renumber the + references, since it has to be done in two places and can have + a cascading effect (insert a single new reference 1, and every + other reference has to be renumbered; always adding new + references to the end is suboptimal). It is easy for + references to go out of sync. + + PEPs use references for two purposes: simple URL references and + footnotes. reStructuredText differentiates between the two. A + PEP might contain references like this:: + + Abstract + + This PEP proposes adding frungible doodads [1] to the + core. It extends PEP 9876 [2] via the BCA [3] + mechanism. + + References and Footnotes + + [1] http://www.example.org/ + + [2] PEP 9876, Let's Hope We Never Get Here + http://www.python.org/peps/pep-9876.html + + [3] "Bogus Complexity Addition" + + Reference 1 is a simple URL reference. Reference 2 is a + footnote containing text and a URL. Reference 3 is a footnote + containing text only. Rewritten using reStructuredText, this + PEP could look like this:: + + Abstract + ======== + + This PEP proposes adding `frungible doodads`_ to the core. + It extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism. + + .. _frungible doodads: http://www.example.org/ + + .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here + + __ http://www.python.org/peps/pep-9876.html + + .. [#] "Bogus Complexity Addition" + + URLs and footnotes can be defined close to their references if + desired, making them easier to read in the source text, and + making the PEPs easier to revise. The "References and + Footnotes" section can be auto-generated with a document tree + transform. Footnotes from throughout the PEP would be gathered + and displayed under a standard header. If URL references + should likewise be written out explicitly (in citation form), + another tree transform could be used. + + URL references can be named ("frungible doodads"), and can be + referenced from multiple places in the document without + additional definitions. When converted to HTML, references + will be replaced with inline hyperlinks (HTML tags). The + two footnotes are automatically numbered, so they will always + stay in sync. The first footnote also contains an internal + reference name, "pep9876", so it's easier to see the connection + between reference and footnote in the source text. Named + footnotes can be referenced multiple times, maintaining + consistent numbering. + + The "#pep9876" footnote could also be written in the form of a + citation:: + + It extends PEP 9876 [PEP9876]_ ... + + .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here + + Footnotes are numbered, whereas citations use text for their + references. + + 5. Wouldn't it be better to keep the docstring and PEP proposals + separate? + + The PEP markup proposal may be removed if it is deemed that + there is no need for PEP markup, or it could be made into a + separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines + [20]_, and PEP 9, Sample PEP Template [21]_ will be updated. + + It seems natural to adopt a single consistent markup standard + for all uses of structured plaintext in Python, and to propose + it all in one place. + + 6. The existing pep2html.py script converts the existing PEP + format to HTML. How will the new-format PEPs be converted to + HTML? + + One of the deliverables of the Docutils project [22]_ will be a + new version of pep2html.py with integrated reStructuredText + parsing. The Docutils project will support PEPs with a "PEP + Reader" component, including all functionality currently in + pep2html.py (auto-recognition of PEP & RFC references). + + 7. Who's going to convert the existing PEPs to reStructuredText? + + PEP authors or volunteers may convert existing PEPs if they + like, but there is no requirement to do so. The + reStructuredText-based PEPs will coexist with the old PEP + standard. The pep2html.py mentioned in answer 6 will process + both old and new standards. + + 8. Why use reStructuredText for README and other ancillary files? + + The reasoning given for PEPs in answer 4 above also applies to + README and other ancillary files. By adopting a standard + markup, these files can be converted to attractive + cross-referenced HTML and put up on python.org. Developers of + Python projects can also take advantage of this facility for + their own documentation. + + 9. Won't the superficial similarity to existing markup conventions + cause problems, and result in people writing invalid markup + (and not noticing, because the plaintext looks natural)? How + forgiving is reStructuredText of "not quite right" markup? + + There will be some mis-steps, as there would be when moving + from one programming language to another. As with any + language, proficiency grows with experience. Luckily, + reStructuredText is a very little language indeed. + + As with any syntax, there is the possibility of syntax errors. + It is expected that a user will run the processing system over + their input and check the output for correctness. + + In a strict sense, the reStructuredText parser is very + unforgiving (as it should be; "In the face of ambiguity, refuse + the temptation to guess" [23]_ applies to parsing markup as + well as computer languages). Here's design goal 3 from "An + Introduction to reStructuredText" [15 ]_: + + Unambiguous. The rules for markup must not be open for + interpretation. For any given input, there should be one + and only one possible output (including error output). + + While unforgiving, at the same time the parser does try to be + helpful by producing useful diagnostic output ("system + messages"). The parser reports problems, indicating their + level of severity (from least to most: debug, info, warning, + error, severe). The user or the client software can decide on + reporting thresholds; they can ignore low-level problems or + cause high-level problems to bring processing to an immediate + halt. Problems are reported during the parse as well as + included in the output, often with two-way links between the + source of the problem and the system message explaining it. + + 10. Will the docstrings in the Python standard library modules be + converted to reStructuredText? + + No. Python's library reference documentation is maintained + separately from the source. Docstrings in the Python standard + library should not try to duplicate the library reference + documentation. The current policy for docstrings in the + Python standard library is that they should be no more than + concise hints, simple and markup-free (although many *do* + contain ad-hoc implicit markup). + + 11. I want to write all my strings in Unicode. Will anything + break? + + The parser will fully support Unicode. It may not yet, but + only because nobody's gotten around to implementing or testing + Unicode support. Contributions are always welcome! + + 12. Why does the community need a new structured text design? + + The existing structured text designs are deficient, for the + reasons given in "Rationale" above. + + 13. What is wrong with existing documentation methodologies? + + What existing methodologies? For Python docstrings, there is + **no** official standard markup format, let alone a + documentation methodology. The question of methodology is at + a much higher level than syntax (what this PEP addresses), + potentially much more controversial and difficult to resolve, + and is intentionally left out of this discussion. References & Footnotes -- cgit v1.2.1 From b55a024c56277e5f9afea839679eaec5893b5f86 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 18 May 2002 02:52:35 +0000 Subject: Added "The Sandbox" section. Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@129 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 184 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 146 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a629ea411..11b55da83 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -62,6 +62,12 @@ General lists & PEP headers. (The same could apply to "language".) - Need a Unicode -> HTML entities codec for HTML writer? +- Distributor/filer object passed to Writer, equivalent passed to + Reader, to provide I/O access with a uniform API? (Names for input + object: inputter, sourcer, scanner.) Simple vs. complex I/O + structure: single file or string, vs. directory/package or tree of + strings. Simple string I/O is default? + Specification ------------- @@ -101,7 +107,7 @@ reStructuredText Parser contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. -- Add character processing? For example: +- Add _`character processing`? For example: - ``--`` -> em-dash (or ``--`` -> en-dash, and ``---`` -> em-dash). (Look for pre-existing conventions.) @@ -212,7 +218,7 @@ reStructuredText Parser Directives `````````` -- Allow directives to be added at run-time. +- Allow directives to be added at run-time? - Use the language module for directive attribute names? @@ -224,11 +230,11 @@ Directives image only in non-HTML writers?) - _`parts.endnotes` - + - _`parts.citations` - + - _`parts.topic` - + - _`parts.sectnum` (section numbering; add support to .contents; could be cmdline option also) @@ -253,21 +259,42 @@ Directives time or at substitution time? Dangerous? Perhaps limit to canned macros; see text.date_ below. - - @@@ _`body.qa` (directive a.k.a. "faq", "questions"): Questions & + - _`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?) + standalone (non-directive) construct? (Is the markup ambiguous?) Add support to parts.Contents (optional attribute "qa" done). New elements would be required. Perhaps:: + 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.columns`: Multi-column table/list, with number of columns as argument. @@ -305,7 +332,7 @@ Directives Within a "verse" element, should any other constructs be allowed? Should lists be recognized? No; verse blocks are variations on - paragraphs, and need not contain arbitrary nested body elements. + paragraphs, and need not contain arbitrary nested body elements. However, the equivalent of block quotes (i.e., further indented blocks) would be nested verse elements. These could be "chorus" blocks. @@ -323,9 +350,22 @@ Directives as soon as it comes. Love, Ewan. - Directive name alternatives: verse, addressblock, address, - lineblock, lines, multiline, freeform, keeplines, nowrap, haiku, - keepbreaks, linebreaks. + Another idea for syntax: in an ordinary paragraph, if the first + line ends with a backslash (escaping the newline), interpret the + entire paragraph as a verse block? This ties in to the `character + processing`_ idea, above. For example:: + + Adding a backslash\ + And this paragraph becomes + An awful haiku + + (And arguably invalid, since in Japanese the word "haiku" contains + three syllables.) + + Directive/construct name alternatives: verse, addressblock, + address, lineblock, lines, multiline, freeform, keeplines, nowrap, + haiku, keepbreaks, linebreaks, obeylines, linewise, textblock, + textart, text, linetext. - _`colorize.python`: Colorize Python code. Fine for HTML output, but what about other formats? Revert to a literal block? Do we @@ -391,39 +431,74 @@ Unimplemented Transforms HTML Writer ----------- -- @@ Allow for style sheet info to be passed in, either as a , +- @@@ Allow for style sheet info to be passed in, either as a , or as embedded style info. -- @ Construct a templating system, as in ht2html/yaptu, using +- @@@ Construct a templating system, as in ht2html/yaptu, using directives and substitutions for dynamic stuff. - @@ Improve the granularity of document parts in the HTML writer, so that one could just grab the parts needed. -- @@ Return a string instead of writing to a file? Leave all I/O up +- @@@ Return a string instead of writing to a file? Leave all I/O up to the client? Or up to an explicit distributor/filer? -- @@ Add an option to generate "source text" links (i.e., click to see - the source text). +- @@ Add an option to generate a "View source text" link. -- @@ Add an option to generate "generated by Docutils from - reStructuredText source" messages, with links. +- @@ Add an option to generate a "Generated by Docutils [from + reStructuredText source?]" message, with links. +- If a list's items contain single paragraphs only, omit the

    tags? + Recursively? (if item == list whose items are single paragraphs + only...) -Front-End ---------- -- Combine the common code from the existing front-ends into a single - library. +Front-Ends +---------- + +@@ Rather than a single all-purpose program, it is probably preferable +to have a bunch of small front-ends, each specialized for a specific +reader (and possibly writer as well). Each of the front-ends would +depend on a common code library described below. + +- Combine the common code from the existing front-ends into a + single library (docutils.frontend? docutils.core.xyz?). - Use Optik to do modular command-line option processing. + - Pass around an Optik 'options' object? Attach it to the + document? What to do when *not* using a front-end (i.e., when + docutils is imported by an unrelated client)? + - The core would support all common options (--reader, --writer, etc.). - Each front-end would add their own specific options (HTML: --stylesheet, etc.), and perhaps disable common options that don't - apply. + apply. (Added/removed dynamically? Is this possible with Optik? + Is it desirable?) + +- Command-line option ideas. Common options: + + --credit Include a "Generated by Docutils" credit with a + link. + --source-link Include a "(View document source)" link. + --verbose Report all system messages, info-level and higher. + (Same as "--report=info".) + --debug Report debug-level system messages. + --report=level Set verbosity; report system messages at or higher + than level (by name or number: "info" or "1", + warning/2, error/3, severe/4, none/5+). + --halt=level Set the level at or above which system messages are + converted to exceptions, halting execution + immediately. Levels as in --report. + --strict Same as "--halt=info": halt processing at the + slightest problem. + + Options specific to HTML writer: + + --stylesheet=file + Specify a stylesheet (default: "default.css"). Project Policies @@ -493,8 +568,8 @@ applicable), with particular emphasis as follows: cases to the test suite. Practise test-first programming; it's fun, it's addictive, and it works! -- The sandbox_ is the place to put new, untried code. See `Additions - to Docutils`_ below. +- The sandbox_ directory is the place to put new, untried code. See + `Additions to Docutils`_ and `The Sandbox`_ below. Please consider subscribing to the appropriate `mailing lists`_. @@ -510,21 +585,15 @@ Additions to Docutils ````````````````````` Additions to the project, such as new components, should be developed -in in the sandbox_ until they're in good shape, usable, and reasonably -complete. Adding to the `main source tree`_ implies a commitment to -the Docutils user community. +in the sandbox_ directory until they're in good shape, usable, and +reasonably complete. Adding to the `main source tree`_ 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. - - The sandbox 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. Each developer who wants to play in the - sandbox should create their own subdirectory (suggested name: - SourceForge ID, or given name + family initial). It's OK to make a - mess! But please, play nice. + 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 (unused legacy code; by analogy with "junk DNA"). @@ -534,7 +603,7 @@ the Docutils user community. - "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). + 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 @@ -549,6 +618,45 @@ 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. + +The Sandbox +----------- + +The sandbox_ 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 +their own subdirectory (suggested name: SourceForge ID, or given name ++ family initial). It's OK to make a mess! But please, play nice. + +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/ + userid/ + 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. + .. Local Variables: -- cgit v1.2.1 From 9931e557165e396bc1891a13197fa59db3571aae Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 19 May 2002 16:44:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@134 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 11b55da83..15a631d29 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1,16 +1,20 @@ -================ - Docutils Notes -================ +================= + Docutils_ Notes +================= :Date: $Date$ :Revision: $Revision$ +.. _Docutils: http://docutils.sourceforge.net/ + .. contents:: To Do ===== Priority items are marked with "@" symbols. The more @s, the higher -the priority. +the priority. Items in question form (containing "?") are ideas which +require more thought and debate; they are potential to-do's. + General ------- @@ -94,6 +98,10 @@ Specification reStructuredText Parser ----------------------- +Also see the `... Or Not To Do?`__ list. + +__ http://docutils.sf.net/spec/rst/alternatives.html#or-not-to-do + - Add motivation sections for constructs in spec. - Allow very long titles (on two or more lines)? @@ -355,7 +363,7 @@ Directives entire paragraph as a verse block? This ties in to the `character processing`_ idea, above. For example:: - Adding a backslash\ + Add just one backslash\ And this paragraph becomes An awful haiku @@ -568,15 +576,15 @@ applicable), with particular emphasis as follows: cases to the test suite. Practise test-first programming; it's fun, it's addictive, and it works! -- The sandbox_ directory is the place to put new, untried code. See - `Additions to Docutils`_ and `The Sandbox`_ below. +- The `sandbox CVS directory`_ is the place to put new, untried code. + See `Additions to Docutils`_ and `The Sandbox`_ below. Please consider subscribing to the appropriate `mailing lists`_. .. _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: +.. sandbox CVS directory: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ .. _mailing lists: ../index.html#mailing-lists @@ -585,9 +593,9 @@ Additions to Docutils ````````````````````` Additions to the project, such as new components, should be developed -in the sandbox_ directory until they're in good shape, usable, and -reasonably complete. Adding to the `main source tree`_ implies a -commitment to the Docutils user community. +in the `sandbox CVS directory`_ until they're in `good shape`_, +usable_, and `reasonably complete`_. Adding to the `main source +tree`_ implies a commitment to the Docutils user community. - Why the sandbox? @@ -595,13 +603,13 @@ commitment to the Docutils user community. 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 (unused legacy code; by analogy with "junk DNA"). +- _`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 +- _`Usable` means that the code does what it claims to do. An "XYZ Writer" should produce reasonable XYZ. -- "Reasonably complete" means that the code must handle all input. +- _`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 -- cgit v1.2.1 From f500944f4fbc72dd11c3a334a2b87b37cebd3fd3 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 19 May 2002 16:55:10 +0000 Subject: fixed targets git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@135 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 15a631d29..145316371 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -584,7 +584,7 @@ Please consider subscribing to the appropriate `mailing lists`_. .. _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: +.. _sandbox CVS directory: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ .. _mailing lists: ../index.html#mailing-lists @@ -630,14 +630,15 @@ to completion. The Sandbox ----------- -The sandbox_ 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 -their own subdirectory (suggested name: SourceForge ID, or given name -+ family initial). It's OK to make a mess! But please, play nice. +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 their own subdirectory (suggested name: SourceForge ID, or +given name + family initial). It's OK to make a mess! But please, +play nice. In order to minimize the work necessary for others to install and try out new, experimental components, the following sandbox directory -- cgit v1.2.1 From b4c6826884a1c00c4fb928dc3584cf241fdaff40 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 22 May 2002 04:23:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@138 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 145316371..e2476a2a2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -469,14 +469,19 @@ to have a bunch of small front-ends, each specialized for a specific reader (and possibly writer as well). Each of the front-ends would depend on a common code library described below. -- Combine the common code from the existing front-ends into a - single library (docutils.frontend? docutils.core.xyz?). +- Combine the common code from the existing front-ends into a single + library. + + - docutils.frontend? docutils.core.xyz? docutils.utils.options? + Part of docutils.core.Publisher/publish()? (Add a ``cmdline`` + parameter? To publish() only?) - Use Optik to do modular command-line option processing. - - Pass around an Optik 'options' object? Attach it to the + - Pass around an Optik 'option Values' object? Attach it to the document? What to do when *not* using a front-end (i.e., when - docutils is imported by an unrelated client)? + docutils is imported by an unrelated client)? I.e., + warning_level etc. - The core would support all common options (--reader, --writer, etc.). @@ -486,6 +491,16 @@ depend on a common code library described below. apply. (Added/removed dynamically? Is this possible with Optik? Is it desirable?) + - Build an OptionParser based on the known Reader & Writer? I.e., + first instantiate the common OptionParser subclass, which can be + passed to a standard function in the Reader module which adds its + specific options, then on to the Writer module. Or, store a data + structure in each component containing its specific options. + + - 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?) + - Command-line option ideas. Common options: --credit Include a "Generated by Docutils" credit with a @@ -528,7 +543,7 @@ Conventions`__ PEPs, with the following clarifications (from most to least important): - 4 spaces per indentation level. No tabs. Indent continuation lines - according to the Emacs' python-mode standard. + according to the Emacs python-mode standard. - No one-liner compound statements (i.e., no ``if x: return``: use two lines & indentation), except for degenerate class or method -- cgit v1.2.1 From a9230c020146ecfdc0488d9b49524f306a9e166e Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 23 May 2002 04:21:31 +0000 Subject: - Added "Copyrights and Licensing" section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@141 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e2476a2a2..33b5efe4a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -56,7 +56,11 @@ General permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?) -- @@@ Implement a PEP reader. +- @@@ Implement a PEP reader. (Reader for RST-PEP format done. + Writer support needed.) + + - Implement a specialized PEP/HTML writer? Or implement a generic + `templating system`_, with PEP/HTML as one application? - @@ Add support for character set encodings on input & output, Unicode internally. @@ -442,7 +446,7 @@ HTML Writer - @@@ Allow for style sheet info to be passed in, either as a , or as embedded style info. -- @@@ Construct a templating system, as in ht2html/yaptu, using +- @@@ Construct a _`templating system`, as in ht2html/yaptu, using directives and substitutions for dynamic stuff. - @@ Improve the granularity of document parts in the HTML writer, so @@ -569,6 +573,33 @@ __ http://www.python.org/peps/pep-0008.html __ http://www.python.org/peps/pep-0257.html +Copyrights and Licensing +------------------------ + +The majority of the Docutils project code and documentation has been +written by me (David Goodger), and 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 SourceForge trackers, mailing lists, or private email) +are assumed to have been placed 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): state "This module has been placed in the + public domain." + +- Copyright & open source license: include a copyright notice, along + with 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. + + CVS Check-ins ------------- -- cgit v1.2.1 From 50bdc5897f3d5d533625ee82b2d1b8ecc1270106 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 24 May 2002 03:13:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@145 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 120 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 87 insertions(+), 33 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 33b5efe4a..5da55712e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -377,7 +377,8 @@ Directives Directive/construct name alternatives: verse, addressblock, address, lineblock, lines, multiline, freeform, keeplines, nowrap, haiku, keepbreaks, linebreaks, obeylines, linewise, textblock, - textart, text, linetext. + textart, text, linetext. Current favorites: "line_block" for + element name, "lines" for directive name. - _`colorize.python`: Colorize Python code. Fine for HTML output, but what about other formats? Revert to a literal block? Do we @@ -396,6 +397,9 @@ Directives Where "macros" contains ``.. |date| date::``, among others. + - _`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.] Unimplemented Transforms ------------------------ @@ -468,13 +472,14 @@ HTML Writer Front-Ends ---------- -@@ Rather than a single all-purpose program, it is probably preferable -to have a bunch of small front-ends, each specialized for a specific -reader (and possibly writer as well). Each of the front-ends would -depend on a common code library described below. +@@@ Rather than a single all-purpose program, it is probably +preferable to have a bunch of small front-ends, each specialized for a +specific reader (and possibly writer as well; each could have a name +of the form "context2format"). Each of the front-ends would depend on +a common option-processing module, as described below. - Combine the common code from the existing front-ends into a single - library. + module, and add option processing. - docutils.frontend? docutils.core.xyz? docutils.utils.options? Part of docutils.core.Publisher/publish()? (Add a ``cmdline`` @@ -483,49 +488,95 @@ depend on a common code library described below. - Use Optik to do modular command-line option processing. - Pass around an Optik 'option Values' object? Attach it to the - document? What to do when *not* using a front-end (i.e., when - docutils is imported by an unrelated client)? I.e., - warning_level etc. + document? + + - What to do when *not* using a front-end (i.e., when docutils is + imported by an unrelated client)? I.e., report_level etc. Use + the default values of the OptionParser? Perhaps:: + + options = optik.option_parser.Values(option_parser.defaults) + options.an_option = "my default value" - The core would support all common options (--reader, --writer, etc.). - - Each front-end would add their own specific options (HTML: + - Each component would add its own specific options (HTML: --stylesheet, etc.), and perhaps disable common options that don't - apply. (Added/removed dynamically? Is this possible with Optik? - Is it desirable?) + apply. + + - Added/removed dynamically (during option processing)? Is this + possible with Optik? Is it desirable? + + - Parsers too? + + - Common and component-specific options may not conflict. + + - Build an OptionParser dynamically based on the known Reader & + Writer? Alternatives: + + a) First instantiate the common OptionParser subclass, which can + be passed to a standard function in the Reader module which + adds its specific options, then on to the Writer module. + + b) Or, store a data structure in each component containing its + specific options, merge with the common option data, and + instantiate an OptionParser. + + - 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. - - Build an OptionParser based on the known Reader & Writer? I.e., - first instantiate the common OptionParser subclass, which can be - passed to a standard function in the Reader module which adds its - specific options, then on to the Writer module. Or, store a data - structure in each component containing its specific 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. - - 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?) + Allow common options before subcommands, as in CVS? Or group all + options together? In the case of the `fully qualified`_ + front-ends, options will have to be grouped together anyway, so + there's no advantage to splitting common and component-specific + options apart. - Command-line option ideas. Common options: - --credit Include a "Generated by Docutils" credit with a - link. + --generator Include a "Generated by Docutils" credit with a + link, at the end of the document. + --date Include a datestamp at the end of the document. --source-link Include a "(View document source)" link. --verbose Report all system messages, info-level and higher. (Same as "--report=info".) --debug Report debug-level system messages. --report=level Set verbosity; report system messages at or higher - than level (by name or number: "info" or "1", - warning/2, error/3, severe/4, none/5+). - --halt=level Set the level at or above which system messages are - converted to exceptions, halting execution - immediately. Levels as in --report. + than ``level`` (by name or number: "info" or "1", + warning/2, error/3, severe/4; also, "none" or 5+). + Default is 2 (warning). + --halt=level Set the ``level`` at or above which system messages + are converted to exceptions, halting execution + immediately. Levels as in --report. Default is 4 + (severe). --strict Same as "--halt=info": halt processing at the slightest problem. + --encoding=name Specify the encoding of input text. Default is + "utf-8". + --language=name Specify the language of input text. Default is + "en" (English). Options specific to HTML writer: --stylesheet=file - Specify a stylesheet (default: "default.css"). + Specify a stylesheet. Default is "default.css". Project Policies @@ -586,18 +637,21 @@ are assumed to have been placed 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): state "This module has been placed in the - public domain." +- 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 an embedded license statement, a reference to an accompanying - license file, or a license URL. + 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. +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 -- cgit v1.2.1 From c95927c8ddb04d0b89e84311ff5f0eb9f953f9f7 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 30 May 2002 02:07:32 +0000 Subject: - Added ``-/:`` characters to inline markup's start string prefix, ``/`` to end string suffix. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@147 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 31c22a184..3d90489d4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1948,8 +1948,9 @@ follows. If any of the conditions are not met, the start-string or end-string will not be recognized or processed. 1. Inline markup start-strings must start a text block or be - immediately preceded by whitespace, single or double quotes, "(", - "[", "{", or "<". + immediately preceded by whitespace or one of:: + + ' " ( [ { < - / : 2. Inline markup start-strings must be immediately followed by non-whitespace. @@ -1960,7 +1961,7 @@ end-string will not be recognized or processed. 4. Inline markup end-strings must end a text block or be immediately followed by whitespace or one of:: - ' " . , : ; ! ? - ) ] } > + ' " ) ] } > - / : . , ; ! ? 5. If an inline markup start-string is immediately preceded by a single or double quote, "(", "[", "{", or "<", it must not be -- cgit v1.2.1 From a36ccb8dddee6b4f75ec62644a566d6d5cfaca3f Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 30 May 2002 02:48:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@161 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 106 ++++++++++++++++++++++-------------------------------- 1 file changed, 43 insertions(+), 63 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5da55712e..f0ab9880c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -447,14 +447,14 @@ Unimplemented Transforms HTML Writer ----------- -- @@@ Allow for style sheet info to be passed in, either as a , - or as embedded style info. +- Allow for style sheet info to be passed in. (Done, with the + ``--stylesheet`` command-line option.) - @@@ Construct a _`templating system`, as in ht2html/yaptu, using directives and substitutions for dynamic stuff. -- @@ Improve the granularity of document parts in the HTML writer, so - that one could just grab the parts needed. +- Improve the granularity of document parts in the HTML writer, so + that one could just grab the parts needed. (Done.) - @@@ Return a string instead of writing to a file? Leave all I/O up to the client? Or up to an explicit distributor/filer? @@ -481,46 +481,43 @@ a common option-processing module, as described below. - Combine the common code from the existing front-ends into a single module, and add option processing. - - docutils.frontend? docutils.core.xyz? docutils.utils.options? - Part of docutils.core.Publisher/publish()? (Add a ``cmdline`` - parameter? To publish() only?) + - Named docutils.frontend.OptionParser. Supporting parameters have + been added to docutils.core.Publisher/publish(): ``argv`` & + ``usage``. - Use Optik to do modular command-line option processing. - - Pass around an Optik 'option Values' object? Attach it to the - document? + - An Optik 'option Values' object is attached to the document. - - What to do when *not* using a front-end (i.e., when docutils is - imported by an unrelated client)? I.e., report_level etc. Use - the default values of the OptionParser? Perhaps:: + - The Optik 'option Values' object is used even when *not* using a + front-end (i.e., when docutils is imported by an unrelated + client). An artificial argv list can be constructed & passed to + publish(), or a default Values object can be created and + modified manually:: - options = optik.option_parser.Values(option_parser.defaults) - options.an_option = "my default value" + pub = Publisher(...) + pub.process_command_line(argv=[]) + pub.options.an_option = "my default value" + pub.publish() - - The core would support all common options (--reader, --writer, + - The core supports all common options (--verbose, --date, etc.). + + - Each component adds its own specific options (HTML: --stylesheet, etc.). - - Each component would add its own specific options (HTML: - --stylesheet, etc.), and perhaps disable common options that don't - apply. + - Disables common options that don't apply? - Added/removed dynamically (during option processing)? Is this - possible with Optik? Is it desirable? - - - Parsers too? + possible with Optik? Is it desirable? (See dynamic_ below.) - - Common and component-specific options may not conflict. + - Common and component-specific options must not conflict. Reserve + short options for the core, and restrict components to long + options? - Build an OptionParser dynamically based on the known Reader & - Writer? Alternatives: - - a) First instantiate the common OptionParser subclass, which can - be passed to a standard function in the Reader module which - adds its specific options, then on to the Writer module. - - b) Or, store a data structure in each component containing its - specific options, merge with the common option data, and - instantiate an OptionParser. + Writer. Store a data structure in each component containing its + specific options, merge with the common option data, and + instantiate an OptionParser. - 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 @@ -543,40 +540,23 @@ a common option-processing module, as described below. [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, options will have to be grouped together anyway, so - there's no advantage to splitting common and component-specific - options apart. - -- Command-line option ideas. Common options: - - --generator Include a "Generated by Docutils" credit with a - link, at the end of the document. - --date Include a datestamp at the end of the document. - --source-link Include a "(View document source)" link. - --verbose Report all system messages, info-level and higher. - (Same as "--report=info".) - --debug Report debug-level system messages. - --report=level Set verbosity; report system messages at or higher - than ``level`` (by name or number: "info" or "1", - warning/2, error/3, severe/4; also, "none" or 5+). - Default is 2 (warning). - --halt=level Set the ``level`` at or above which system messages - are converted to exceptions, halting execution - immediately. Levels as in --report. Default is 4 - (severe). - --strict Same as "--halt=info": halt processing at the - slightest problem. - --encoding=name Specify the encoding of input text. Default is - "utf-8". - --language=name Specify the language of input text. Default is - "en" (English). - - Options specific to HTML writer: - - --stylesheet=file - Specify a stylesheet. Default is "default.css". + 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. + +- Implement command-line options. Common options: --generator, + --date, --time, --source-link, --warnings, --encoding=name, + --language=name. Project Policies -- cgit v1.2.1 From fa47be81f29db06976116a9202f9150b06b0c9ef Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 31 May 2002 00:51:44 +0000 Subject: Reworked based on ideas stolen from Tony Ibbs; updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@164 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 55 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index 1a1aa6e8b..7fa920363 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -61,37 +61,50 @@ http://docutils.sourceforge.net/spec/docutils.dtd. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> - + - + + (class, inheritance_list?, fullname?, subclasses?, %structure.model;)> - + - + + (module_attribute, initial_value?, fullname?, %structure.model;)> + (class_attribute, initial_value?, fullname?, overrides?, + %structure.model;)> + (instance_attribute, initial_value?, fullname?, overrides?, + %structure.model;)> + + + + + + + + + @@ -122,13 +135,13 @@ http://docutils.sourceforge.net/spec/docutils.dtd. + %reference.atts;> + %reference.atts;> + %reference.atts;> + %reference.atts;> + %reference.atts;> + %reference.atts;> + %reference.atts;> + %reference.atts;> + ((title, subtitle?)?, docinfo?, decoration?, %structure.model;)> @@ -231,6 +231,22 @@ http://www.oasis-open.org/html/tm9901.htm). + + + + + + + + + + + + ):: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + + Doctest blocks begin with ">>> " and end with a blank line. Neither + indentation nor literal block double-colons are required. For + example:: + + Here's a doctest block: + + >>> print 'Python-specific usage examples; begun with ">>>"' + Python-specific usage examples; begun with ">>>" + >>> print '(cut and pasted from interactive sessions)' + (cut and pasted from interactive sessions) + +- Markup that isolates a Python identifier: interpreted text. + + Text enclosed in single backquotes is recognized as "interpreted + text", whose interpretation is application-dependent. In the + context of a Python docstring, the default interpretation of + interpreted text is as Python identifiers. The text will be marked + up with a hyperlink connected to the documentation for the + identifier given. Lookup rules are the same as in Python itself: + LGB namespace lookups (local, global, builtin). The "role" of the + interpreted text (identifying a class, module, function, etc.) is + determined implicitly from the namespace lookup. For example:: + + class Keeper(Storer): + + """ + Keep data fresher longer. - - A markup escaping mechanism. - - Backslashes (``\``) are used to escape markup characters when - needed for non-markup purposes. However, the inline markup - recognition rules have been constructed in order to minimize the - need for backslash-escapes. For example, although asterisks are - used for *emphasis*, in non-markup contexts such as "*" or "(*)" - or "x * y", the asterisks are not interpreted as markup and are - left unchanged. For many non-markup uses of backslashes (e.g., - describing regular expressions), inline literals or literal - blocks are applicable; see the next item. - - - Markup to include Python source code and Python interactive - sessions: inline literals, literal blocks, and doctest blocks. - - Inline literals use ``double-backquotes`` to indicate program - I/O or code snippets. No markup interpretation (including - backslash-escape [``\``] interpretation) is done within inline - literals. - - Literal blocks (block-level literal text, such as code excerpts - or ASCII graphics) are indented, and indicated with a - double-colon ("::") at the end of the preceding paragraph (right - here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - - Doctest blocks begin with ">>> " and end with a blank line. - Neither indentation nor literal block double-colons are - required. For example:: - - Here's a doctest block: - - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive sessions)' - (cut and pasted from interactive sessions) - - - Markup that isolates a Python identifier: interpreted text. - - Text enclosed in single backquotes is recognized as "interpreted - text", whose interpretation is application-dependent. In the - context of a Python docstring, the default interpretation of - interpreted text is as Python identifiers. The text will be - marked up with a hyperlink connected to the documentation for - the identifier given. Lookup rules are the same as in Python - itself: LGB namespace lookups (local, global, builtin). The - "role" of the interpreted text (identifying a class, module, - function, etc.) is determined implicitly from the namespace - lookup. For example:: - - class Keeper(Storer): + Extend `Storer`. Class attribute `instances` keeps track + of the number of `Keeper` objects instantiated. + """ + instances = 0 + """How many `Keeper` objects are there?""" + + def __init__(self): + """ + Extend `Storer.__init__()` to keep track of + instances. Keep count in `self.instances` and data + in `self.data`. """ - Keep data fresher longer. + Storer.__init__(self) + self.instances += 1 - Extend `Storer`. Class attribute `instances` keeps track - of the number of `Keeper` objects instantiated. + self.data = [] + """Store data in a list, most recent last.""" + + def storedata(self, data): + """ + Extend `Storer.storedata()`; append new `data` to a + list (in `self.data`). """ + self.data = data - instances = 0 - """How many `Keeper` objects are there?""" + Each piece of interpreted text is looked up according to the local + namespace of the block containing its docstring. - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of - instances. Keep count in `self.instances` and data - in `self.data`. - """ - Storer.__init__(self) - self.instances += 1 +- Markup that isolates a Python identifier and specifies its type: + interpreted text with roles. - self.data = [] - """Store data in a list, most recent last.""" + Although the Python source context reader is designed not to require + explicit roles, they may be used. To classify identifiers + explicitly, the role is given along with the identifier in either + prefix or suffix form:: - def storedata(self, data): - """ - Extend `Storer.storedata()`; append new `data` to a - list (in `self.data`). - """ - self.data = data + Use :method:`Keeper.storedata` to store the object's data in + `Keeper.data`:instance_attribute:. - Each piece of interpreted text is looked up according to the - local namespace of the block containing its docstring. + The syntax chosen for roles is verbose, but necessarily so (if + anyone has a better alternative, please post it to the Doc-SIG_). + The intention of the markup is that there should be little need to + use explicit roles; their use is to be kept to an absolute minimum. - - Markup that isolates a Python identifier and specifies its type: - interpreted text with roles. +- Markup for "tagged lists" or "label lists": field lists. - Although the Python source context reader is designed not to - require explicit roles, they may be used. To classify - identifiers explicitly, the role is given along with the - identifier in either prefix or suffix form:: + Field lists represent a mapping from field name to field body. + These are mostly used for extension syntax, such as "bibliographic + field lists" (representing document metadata such as author, date, + and version) and extension attributes for directives (see below). + They may be used to implement methodologies (docstring semantics), + such as identifying parameters, exceptions raised, etc.; such usage + is beyond the scope of this PEP. - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. + A modified RFC 2822 syntax is used, with a colon *before* as well as + *after* the field name. Field bodies are more versatile as well; + they may contain multiple field bodies (even nested field lists). + For example:: - The syntax chosen for roles is verbose, but necessarily so (if - anyone has a better alternative, please post it to the Doc-SIG). - The intention of the markup is that there should be little need - to use explicit roles; their use is to be kept to an absolute - minimum. + :Date: 2002-03-22 + :Version: 1 + :Authors: + - Me + - Myself + - I - - Markup for "tagged lists" or "label lists": field lists. + Standard RFC 2822 header syntax cannot be used for this construct + because it is ambiguous. A word followed by a colon at the + beginning of a line is common in written text. - Field lists represent a mapping from field name to field body. - These are mostly used for extension syntax, such as - "bibliographic field lists" (representing document metadata such - as author, date, and version) and extension attributes for - directives (see below). They may be used to implement - methodologies (docstring semantics), such as identifying - parameters, exceptions raised, etc.; such usage is beyond the - scope of this PEP. +- Markup extensibility: directives and substitutions. - A modified RFC 2822 syntax is used, with a colon *before* as - well as *after* the field name. Field bodies are more versatile - as well; they may contain multiple field bodies (even nested - field lists). For example:: + Directives are used as an extension mechanism for reStructuredText, + a way of adding support for new block-level constructs without + adding new syntax. Directives for images, admonitions (note, + caution, etc.), and tables of contents generation (among others) + have been implemented. For example, here's how to place an image:: - :Date: 2002-03-22 - :Version: 1 - :Authors: - - Me - - Myself - - I + .. image:: mylogo.png - Standard RFC 2822 header syntax cannot be used for this - construct because it is ambiguous. A word followed by a colon - at the beginning of a line is common in written text. + Substitution definitions allow the power and flexibility of + block-level directives to be shared by inline text. For example:: - - Markup extensibility: directives and substitutions. + The |biohazard| symbol must be used on containers used to + dispose of medical waste. - Directives are used as an extension mechanism for - reStructuredText, a way of adding support for new block-level - constructs without adding new syntax. Directives for images, - admonitions (note, caution, etc.), and tables of contents - generation (among others) have been implemented. For example, - here's how to place an image:: + .. |biohazard| image:: biohazard.png - .. image:: mylogo.png +- Section structure markup. - Substitution definitions allow the power and flexibility of - block-level directives to be shared by inline text. For - example:: + Section headers in reStructuredText use adornment via underlines + (and possibly overlines) rather than indentation. For example:: - The |biohazard| symbol must be used on containers used to - dispose of medical waste. + This is a Section Title + ======================= - .. |biohazard| image:: biohazard.png + This is a Subsection Title + -------------------------- - - Section structure markup. + This paragraph is in the subsection. - Section headers in reStructuredText use adornment via underlines - (and possibly overlines) rather than indentation. For example:: + This is Another Section Title + ============================= - This is a Section Title - ======================= + This paragraph is in the second section. - This is a Subsection Title - -------------------------- - This paragraph is in the subsection. +Questions & Answers +=================== + +1. Is reStructuredText rich enough? + + Yes, it is for most people. If it lacks some construct that is + required for a specific application, it can be added via the + directive mechanism. If a useful and common construct has been + overlooked and a suitably readable syntax can be found, it can be + added to the specification and parser. + +2. Is reStructuredText *too* rich? + + For specific applications or individuals, perhaps. In general, no. + + Since the very beginning, whenever a docstring markup syntax has + been proposed on the Doc-SIG_, someone has complained about the + lack of support for some construct or other. The reply was often + something like, "These are docstrings we're talking about, and + docstrings shouldn't have complex markup." The problem is that a + construct that seems superfluous to one person may be absolutely + essential to another. + + reStructuredText takes the opposite approach: it provides a rich + set of implicit markup constructs (plus a generic extension + mechanism for explicit markup), allowing for all kinds of + documents. If the set of constructs is too rich for a particular + application, the unused constructs can either be removed from the + parser (via application-specific overrides) or simply omitted by + convention. - This is Another Section Title - ============================= +3. Why not use indentation for section structure, like StructuredText + does? Isn't it more "Pythonic"? + + Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post: + + I still think that using indentation to indicate sectioning is + wrong. If you look at how real books and other print + publications are laid out, you'll notice that indentation is + used frequently, but mostly at the intra-section level. + Indentation can be used to offset lists, tables, quotations, + examples, and the like. (The argument that docstrings are + different because they are input for a text formatter is wrong: + the whole point is that they are also readable without + processing.) + + I reject the argument that using indentation is Pythonic: text + is not code, and different traditions and conventions hold. + People have been presenting text for readability for over 30 + centuries. Let's not innovate needlessly. + + See `Section Structure via Indentation`__ in `Problems With + StructuredText`_ for further elaboration. + + __ http://docutils.sourceforge.net/spec/rst/problems.html + #section-structure-via-indentation + +4. Why use reStructuredText for PEPs? What's wrong with the existing + standard? + + The existing standard for PEPs is very limited in terms of general + expressibility, and referencing is especially lacking for such a + reference-rich document type. PEPs are currently converted into + HTML, but the results (mostly monospaced text) are less than + attractive, and most of the value-added potential of HTML + (especially inline hyperlinks) is untapped. + + Making reStructuredText a standard markup for PEPs will enable much + richer expression, including support for section structure, inline + markup, graphics, and tables. In several PEPs there are ASCII + graphics diagrams, which are all that plaintext documents can + support. Since PEPs are made available in HTML form, the ability + to include proper diagrams would be immediately useful. + + Current PEP practices allow for reference markers in the form "[1]" + in the text, and the footnotes/references themselves are listed in + a section toward the end of the document. There is currently no + hyperlinking between the reference marker and the + footnote/reference itself (it would be possible to add this to + pep2html.py, but the "markup" as it stands is ambiguous and + mistakes would be inevitable). A PEP with many references (such as + this one ;-) requires a lot of flipping back and forth. When + revising a PEP, often new references are added or unused references + deleted. It is painful to renumber the references, since it has to + be done in two places and can have a cascading effect (insert a + single new reference 1, and every other reference has to be + renumbered; always adding new references to the end is suboptimal). + It is easy for references to go out of sync. + + PEPs use references for two purposes: simple URL references and + footnotes. reStructuredText differentiates between the two. A PEP + might contain references like this:: + + Abstract + + This PEP proposes adding frungible doodads [1] to the core. + It extends PEP 9876 [2] via the BCA [3] mechanism. + + References and Footnotes + + [1] http://www.example.org/ + + [2] PEP 9876, Let's Hope We Never Get Here + http://www.python.org/peps/pep-9876.html + + [3] "Bogus Complexity Addition" + + Reference 1 is a simple URL reference. Reference 2 is a footnote + containing text and a URL. Reference 3 is a footnote containing + text only. Rewritten using reStructuredText, this PEP could look + like this:: + + Abstract + ======== + + This PEP proposes adding `frungible doodads`_ to the core. It + extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism. + + ... + + References & Footnotes + ====================== + + .. _frungible doodads: http://www.example.org/ + + .. [#pep9876] PEP 9876, Let's Hope We Never Get Here + + .. [#] "Bogus Complexity Addition" + + URLs and footnotes can be defined close to their references if + desired, making them easier to read in the source text, and making + the PEPs easier to revise. The "References and Footnotes" section + can be auto-generated with a document tree transform. Footnotes + from throughout the PEP would be gathered and displayed under a + standard header. If URL references should likewise be written out + explicitly (in citation form), another tree transform could be + used. + + URL references can be named ("frungible doodads"), and can be + referenced from multiple places in the document without additional + definitions. When converted to HTML, references will be replaced + with inline hyperlinks (HTML tags). The two footnotes are + automatically numbered, so they will always stay in sync. The + first footnote also contains an internal reference name, "pep9876", + so it's easier to see the connection between reference and footnote + in the source text. Named footnotes can be referenced multiple + times, maintaining consistent numbering. + + The "#pep9876" footnote could also be written in the form of a + citation:: + + It extends PEP 9876 [PEP9876]_ ... + + .. [PEP9876] PEP 9876, Let's Hope We Never Get Here + + Footnotes are numbered, whereas citations use text for their + references. + +5. Wouldn't it be better to keep the docstring and PEP proposals + separate? + + The PEP markup proposal may be removed if it is deemed that there + is no need for PEP markup, or it could be made into a separate PEP. + If accepted, PEP 1, PEP Purpose and Guidelines [PEP-1]_, and PEP 9, + Sample PEP Template [PEP-9]_ will be updated. + + It seems natural to adopt a single consistent markup standard for + all uses of structured plaintext in Python, and to propose it all + in one place. + +6. The existing pep2html.py script converts the existing PEP format to + HTML. How will the new-format PEPs be converted to HTML? - This paragraph is in the second section. + One of the deliverables of the Docutils_ project will be a new + version of pep2html.py with integrated reStructuredText parsing. + The Docutils project will support PEPs with a "PEP Reader" + component, including all functionality currently in pep2html.py + (auto-recognition of PEP & RFC references). +7. Who's going to convert the existing PEPs to reStructuredText? -Questions & Answers + PEP authors or volunteers may convert existing PEPs if they like, + but there is no requirement to do so. The reStructuredText-based + PEPs will coexist with the old PEP standard. The pep2html.py + mentioned in answer 6 will process both old and new standards. + +8. Why use reStructuredText for README and other ancillary files? - 1. Is reStructuredText rich enough? - - Yes, it is for most people. If it lacks some construct that is - required for a specific application, it can be added via the - directive mechanism. If a useful and common construct has been - overlooked and a suitably readable syntax can be found, it can - be added to the specification and parser. - - 2. Is reStructuredText *too* rich? - - For specific applications or individuals, perhaps. In general, - no. - - Since the very beginning, whenever a docstring markup syntax - has been proposed on the Doc-SIG, someone has complained about - the lack of support for some construct or other. The reply was - often something like, "These are docstrings we're talking - about, and docstrings shouldn't have complex markup." The - problem is that a construct that seems superfluous to one - person may be absolutely essential to another. - - reStructuredText takes the opposite approach: it provides a - rich set of implicit markup constructs (plus a generic - extension mechanism for explicit markup), allowing for all - kinds of documents. If the set of constructs is too rich for a - particular application, the unused constructs can either be - removed from the parser (via application-specific overrides) or - simply omitted by convention. - - 3. Why not use indentation for section structure, like - StructuredText does? Isn't it more "Pythonic"? - - Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG - post: - - I still think that using indentation to indicate sectioning - is wrong. If you look at how real books and other print - publications are laid out, you'll notice that indentation - is used frequently, but mostly at the intra-section level. - Indentation can be used to offset lists, tables, - quotations, examples, and the like. (The argument that - docstrings are different because they are input for a text - formatter is wrong: the whole point is that they are also - readable without processing.) - - I reject the argument that using indentation is Pythonic: - text is not code, and different traditions and conventions - hold. People have been presenting text for readability for - over 30 centuries. Let's not innovate needlessly. - - See "Section Structure via Indentation" in "Problems With - StructuredText" [18 ]_ for further elaboration. - - 4. Why use reStructuredText for PEPs? What's wrong with the - existing standard? - - The existing standard for PEPs is very limited in terms of - general expressibility, and referencing is especially lacking - for such a reference-rich document type. PEPs are currently - converted into HTML, but the results (mostly monospaced text) - are less than attractive, and most of the value-added potential - of HTML (especially inline hyperlinks) is untapped. - - Making reStructuredText a standard markup for PEPs will enable - much richer expression, including support for section - structure, inline markup, graphics, and tables. In several - PEPs there are ASCII graphics diagrams, which are all that - plaintext documents can support. Since PEPs are made available - in HTML form, the ability to include proper diagrams would be - immediately useful. - - Current PEP practices allow for reference markers in the form - "[1]" in the text, and the footnotes/references themselves are - listed in a section toward the end of the document. There is - currently no hyperlinking between the reference marker and the - footnote/reference itself (it would be possible to add this to - pep2html.py, but the "markup" as it stands is ambiguous and - mistakes would be inevitable). A PEP with many references - (such as this one ;-) requires a lot of flipping back and - forth. When revising a PEP, often new references are added or - unused references deleted. It is painful to renumber the - references, since it has to be done in two places and can have - a cascading effect (insert a single new reference 1, and every - other reference has to be renumbered; always adding new - references to the end is suboptimal). It is easy for - references to go out of sync. - - PEPs use references for two purposes: simple URL references and - footnotes. reStructuredText differentiates between the two. A - PEP might contain references like this:: - - Abstract - - This PEP proposes adding frungible doodads [1] to the - core. It extends PEP 9876 [2] via the BCA [3] - mechanism. - - References and Footnotes - - [1] http://www.example.org/ - - [2] PEP 9876, Let's Hope We Never Get Here - http://www.python.org/peps/pep-9876.html - - [3] "Bogus Complexity Addition" - - Reference 1 is a simple URL reference. Reference 2 is a - footnote containing text and a URL. Reference 3 is a footnote - containing text only. Rewritten using reStructuredText, this - PEP could look like this:: - - Abstract - ======== - - This PEP proposes adding `frungible doodads`_ to the core. - It extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism. - - ... - - References & Footnotes - ====================== - - .. _frungible doodads: http://www.example.org/ - - .. [#pep9876] PEP 9876, Let's Hope We Never Get Here - - .. [#] "Bogus Complexity Addition" - - URLs and footnotes can be defined close to their references if - desired, making them easier to read in the source text, and - making the PEPs easier to revise. The "References and - Footnotes" section can be auto-generated with a document tree - transform. Footnotes from throughout the PEP would be gathered - and displayed under a standard header. If URL references - should likewise be written out explicitly (in citation form), - another tree transform could be used. - - URL references can be named ("frungible doodads"), and can be - referenced from multiple places in the document without - additional definitions. When converted to HTML, references - will be replaced with inline hyperlinks (HTML tags). The - two footnotes are automatically numbered, so they will always - stay in sync. The first footnote also contains an internal - reference name, "pep9876", so it's easier to see the connection - between reference and footnote in the source text. Named - footnotes can be referenced multiple times, maintaining - consistent numbering. - - The "#pep9876" footnote could also be written in the form of a - citation:: - - It extends PEP 9876 [PEP9876]_ ... - - .. [PEP9876] PEP 9876, Let's Hope We Never Get Here - - Footnotes are numbered, whereas citations use text for their - references. - - 5. Wouldn't it be better to keep the docstring and PEP proposals - separate? - - The PEP markup proposal may be removed if it is deemed that - there is no need for PEP markup, or it could be made into a - separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines - [20]_, and PEP 9, Sample PEP Template [21]_ will be updated. - - It seems natural to adopt a single consistent markup standard - for all uses of structured plaintext in Python, and to propose - it all in one place. - - 6. The existing pep2html.py script converts the existing PEP - format to HTML. How will the new-format PEPs be converted to - HTML? - - One of the deliverables of the Docutils project [22]_ will be a - new version of pep2html.py with integrated reStructuredText - parsing. The Docutils project will support PEPs with a "PEP - Reader" component, including all functionality currently in - pep2html.py (auto-recognition of PEP & RFC references). - - 7. Who's going to convert the existing PEPs to reStructuredText? - - PEP authors or volunteers may convert existing PEPs if they - like, but there is no requirement to do so. The - reStructuredText-based PEPs will coexist with the old PEP - standard. The pep2html.py mentioned in answer 6 will process - both old and new standards. - - 8. Why use reStructuredText for README and other ancillary files? + The reasoning given for PEPs in answer 4 above also applies to + README and other ancillary files. By adopting a standard markup, + these files can be converted to attractive cross-referenced HTML + and put up on python.org. Developers of Python projects can also + take advantage of this facility for their own documentation. - The reasoning given for PEPs in answer 4 above also applies to - README and other ancillary files. By adopting a standard - markup, these files can be converted to attractive - cross-referenced HTML and put up on python.org. Developers of - Python projects can also take advantage of this facility for - their own documentation. +9. Won't the superficial similarity to existing markup conventions + cause problems, and result in people writing invalid markup (and + not noticing, because the plaintext looks natural)? How forgiving + is reStructuredText of "not quite right" markup? - 9. Won't the superficial similarity to existing markup conventions - cause problems, and result in people writing invalid markup - (and not noticing, because the plaintext looks natural)? How - forgiving is reStructuredText of "not quite right" markup? - - There will be some mis-steps, as there would be when moving - from one programming language to another. As with any - language, proficiency grows with experience. Luckily, - reStructuredText is a very little language indeed. - - As with any syntax, there is the possibility of syntax errors. - It is expected that a user will run the processing system over - their input and check the output for correctness. - - In a strict sense, the reStructuredText parser is very - unforgiving (as it should be; "In the face of ambiguity, refuse - the temptation to guess" [23]_ applies to parsing markup as - well as computer languages). Here's design goal 3 from "An - Introduction to reStructuredText" [15 ]_: - - Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one - and only one possible output (including error output). - - While unforgiving, at the same time the parser does try to be - helpful by producing useful diagnostic output ("system - messages"). The parser reports problems, indicating their - level of severity (from least to most: debug, info, warning, - error, severe). The user or the client software can decide on - reporting thresholds; they can ignore low-level problems or - cause high-level problems to bring processing to an immediate - halt. Problems are reported during the parse as well as - included in the output, often with two-way links between the - source of the problem and the system message explaining it. - - 10. Will the docstrings in the Python standard library modules be - converted to reStructuredText? - - No. Python's library reference documentation is maintained - separately from the source. Docstrings in the Python standard - library should not try to duplicate the library reference - documentation. The current policy for docstrings in the - Python standard library is that they should be no more than - concise hints, simple and markup-free (although many *do* - contain ad-hoc implicit markup). - - 11. I want to write all my strings in Unicode. Will anything - break? - - The parser fully supports Unicode. Docutils supports - arbitrary input encodings. - - 12. Why does the community need a new structured text design? - - The existing structured text designs are deficient, for the - reasons given in "Rationale" above. reStructuredText aims to - be a complete markup syntax, within the limitations of the - "readable plaintext" medium. - - 13. What is wrong with existing documentation methodologies? - - What existing methodologies? For Python docstrings, there is - **no** official standard markup format, let alone a - documentation methodology, akin to JavaDoc. The question of - methodology is at a much higher level than syntax (which this - PEP addresses). It is potentially much more controversial and - difficult to resolve, and is intentionally left out of this - discussion. + There will be some mis-steps, as there would be when moving from + one programming language to another. As with any language, + proficiency grows with experience. Luckily, reStructuredText is a + very little language indeed. + + As with any syntax, there is the possibility of syntax errors. It + is expected that a user will run the processing system over their + input and check the output for correctness. + + In a strict sense, the reStructuredText parser is very unforgiving + (as it should be; "In the face of ambiguity, refuse the temptation + to guess" [#Zen]_ applies to parsing markup as well as computer + languages). Here's design goal 3 from `An Introduction to + reStructuredText`_: + + Unambiguous. The rules for markup must not be open for + interpretation. For any given input, there should be one and + only one possible output (including error output). + + While unforgiving, at the same time the parser does try to be + helpful by producing useful diagnostic output ("system messages"). + The parser reports problems, indicating their level of severity + (from least to most: debug, info, warning, error, severe). The + user or the client software can decide on reporting thresholds; + they can ignore low-level problems or cause high-level problems to + bring processing to an immediate halt. Problems are reported + during the parse as well as included in the output, often with + two-way links between the source of the problem and the system + message explaining it. + +10. Will the docstrings in the Python standard library modules be + converted to reStructuredText? + + No. Python's library reference documentation is maintained + separately from the source. Docstrings in the Python standard + library should not try to duplicate the library reference + documentation. The current policy for docstrings in the Python + standard library is that they should be no more than concise + hints, simple and markup-free (although many *do* contain ad-hoc + implicit markup). + +11. I want to write all my strings in Unicode. Will anything + break? + + The parser fully supports Unicode. Docutils supports arbitrary + input and output encodings. + +12. Why does the community need a new structured text design? + + The existing structured text designs are deficient, for the + reasons given in "Rationale" above. reStructuredText aims to be a + complete markup syntax, within the limitations of the "readable + plaintext" medium. + +13. What is wrong with existing documentation methodologies? + + What existing methodologies? For Python docstrings, there is + **no** official standard markup format, let alone a documentation + methodology, akin to JavaDoc. The question of methodology is at a + much higher level than syntax (which this PEP addresses). It is + potentially much more controversial and difficult to resolve, and + is intentionally left out of this discussion. References & Footnotes +====================== + +.. _reStructuredText markup: http://docutils.sourceforge.net/spec/rst.html - [1] http://docutils.sourceforge.net/spec/rst.html +.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - [2] http://www.python.org/sigs/doc-sig/ +.. _XML: http://www.w3.org/XML/ - [3] http://www.w3.org/XML/ +.. _SGML: http://www.oasis-open.org/cover/general.html - [4] http://www.oasis-open.org/cover/general.html +.. _DocBook: http://docbook.org/tdg/en/html/docbook.html - [5] http://docbook.org/tdg/en/html/docbook.html +.. _HTML: http://www.w3.org/MarkUp/ - [6] http://www.w3.org/MarkUp/ +.. _XHTML: http://www.w3.org/MarkUp/#xhtml1 - [7] http://www.w3.org/MarkUp/#xhtml1 +.. _TeX: http://www.tug.org/interest.html - [8] http://www.tug.org/interest.html +.. _Perl POD: http://www.perldoc.com/perl5.6/pod/perlpod.html - [9] http://www.perldoc.com/perl5.6/pod/perlpod.html +.. _JavaDoc: http://java.sun.com/j2se/javadoc/ - [10] http://java.sun.com/j2se/javadoc/ +.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - [11] http://docutils.sourceforge.net/mirror/setext.html +.. _StructuredText: + http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage - [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage +.. _A ReStructuredText Primer: + http://docutils.sourceforge.net/docs/rst/quickstart.html - [13] A ReStructuredText Primer - http://docutils.sourceforge.net/docs/rst/quickstart.html +.. _Quick reStructuredText: + http://docutils.sourceforge.net/docs/rst/quickref.html - [14] Quick reStructuredText - http://docutils.sourceforge.net/docs/rst/quickref.html +.. _An Introduction to reStructuredText: + http://docutils.sourceforge.net/spec/rst/introduction.html - [15] An Introduction to reStructuredText - http://docutils.sourceforge.net/spec/rst/introduction.html +.. _reStructuredText Markup Specification: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html - [16] reStructuredText Markup Specification - http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _reStructuredText Directives: + http://docutils.sourceforge.net/spec/rst/directives.html - [17] reStructuredText Directives - http://docutils.sourceforge.net/spec/rst/directives.html +.. _Problems with StructuredText: + http://docutils.sourceforge.net/spec/rst/problems.html - [18] Problems with StructuredText - http://docutils.sourceforge.net/spec/rst/problems.html +.. _A Record of reStructuredText Syntax Alternatives: + http://docutils.sourceforge.net/spec/rst/alternatives.html - [19] A Record of reStructuredText Syntax Alternatives - http://docutils.sourceforge.net/spec/rst/alternatives.html +.. [PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton + (http://www.python.org/peps/pep-0001.html) - [20] PEP 1, PEP Guidelines, Warsaw, Hylton - http://www.python.org/peps/pep-0001.html +.. [PEP-9] PEP 9, Sample PEP Template, Warsaw + (http://www.python.org/peps/pep-0009.html) - [21] PEP 9, Sample PEP Template, Warsaw - http://www.python.org/peps/pep-0009.html +.. _Docutils: http://docutils.sourceforge.net/ - [22] http://docutils.sourceforge.net/ +.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just + "``import this``" in Python) - [23] From "The Zen of Python (by Tim Peters)" - (http://www.python.org/doc/Humor.html#zen or just - "``import this``" in Python) + __ http://www.python.org/doc/Humor.html#zen - [24] PEP 216, Docstring Format, Zadka - http://www.python.org/peps/pep-0216.html +.. [PEP-216] PEP 216, Docstring Format, Zadka + (http://www.python.org/peps/pep-0216.html) Copyright +========= - This document has been placed in the public domain. +This document has been placed in the public domain. Acknowledgements +================ - Some text is borrowed from PEP 216, Docstring Format [24]_, by - Moshe Zadka. +Some text is borrowed from PEP 216, Docstring Format [PEP-216]_, by +Moshe Zadka. - Special thanks to all members past & present of the Python - Doc-SIG. +Special thanks to all members past & present of the Python Doc-SIG_. -Local Variables: -mode: indented-text -indent-tabs-mode: nil -sentence-end-double-space: t -fill-column: 70 -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: -- cgit v1.2.1 From 365c0cbc8335aabae0e7447e380f586cdb28b38e Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 15 Jul 2002 03:47:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@296 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a42f8d74f..089c5c4a7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -51,7 +51,7 @@ General - Implementation docs. - spec/doctree.txt: Doctree nodes (DTD element) semantics: - + - External (public) attributes (node.attributes). - Internal attributes (node.*). - Linking mechanism. @@ -290,6 +290,19 @@ __ rst/alternatives.html#or-not-to-do Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback"). +- Generalize the "literal block" construct to allow blocks with a + per-line quoting to avoid indentation? For example, an email reply + quoting the original:: + + John Doe wrote:: + + > Great idea! + > + > Why didn't I think of that? + + Every line of the literal block would have to begin with the same + non-alphanumeric non-whitespace character. + Directives `````````` -- cgit v1.2.1 From d2293256dba0cdc32d801cbc60d8796fe4be165d Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Jul 2002 01:33:32 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@305 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 49 ++++++++++++++++++++++--------------------------- 1 file changed, 22 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 476c57868..d138a8b2c 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -244,33 +244,28 @@ the mappings. The following state transition table shows how ``nameids`` ("ids") and ``nametypes`` ("types") change with new input (a call to -``document.set_name_id_map()``), and what actions are performed:: - - ==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes - ----------- -------- ----------------- ----------- - ids types new type sys.msg. dupname ids types - ==== ===== ======== ======== ======= ==== ===== ===== - -- -- explicit -- -- new True - -- -- implicit -- -- new False - None False explicit -- -- new True - old False explicit implicit old new True - None True explicit explicit new None True - old True explicit explicit new,old None True [1] - None False implicit implicit new None False - old False implicit implicit new,old None False - None True implicit implicit new None True - old True implicit implicit new old True - ==== ===== ======== ======== ======= ==== ===== ===== - -Note 1: Do not clear the name->id map or invalidate the old target if -both old and new targets are external and refer to identical URIs. -The new target is invalidated regardless. - -(The above is an example of `table syntax alternative 3`__; not -implemented yet, but I'm thinking about it.) - -__ rst/problems.html#tables +``document.set_name_id_map()``), and what actions are performed: + +==== ===== ======== ======== ======= ==== ===== ===== + Old State Input Action New State Notes +----------- -------- ----------------- ----------- ----- +ids types new type sys.msg. dupname ids types +==== ===== ======== ======== ======= ==== ===== ===== +-- -- explicit -- -- new True +-- -- implicit -- -- new False +None False explicit -- -- new True +old False explicit implicit old new True +None True explicit explicit new None True +old True explicit explicit new,old None True [#]_ +None False implicit implicit new None False +old False implicit implicit new,old None False +None True implicit implicit new None True +old True implicit implicit new old True +==== ===== ======== ======== ======= ==== ===== ===== + +.. [#] Do not clear the name->id map or invalidate the old target if + both old and new targets are external and refer to identical URIs. + The new target is invalidated regardless. Representation of Horizontal Rules -- cgit v1.2.1 From 46db8cb85f96053f20e7f15f980f84b1ed52a245 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Jul 2002 01:35:13 +0000 Subject: minor edits git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@306 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 20e937105..74112d2c5 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -612,8 +612,8 @@ Questions & Answers The PEP markup proposal may be removed if it is deemed that there is no need for PEP markup, or it could be made into a separate PEP. - If accepted, PEP 1, PEP Purpose and Guidelines [PEP-1]_, and PEP 9, - Sample PEP Template [PEP-9]_ will be updated. + If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP + 9, Sample PEP Template [#PEP-9]_ will be updated. It seems natural to adopt a single consistent markup standard for all uses of structured plaintext in Python, and to propose it all @@ -706,7 +706,7 @@ Questions & Answers What existing methodologies? For Python docstrings, there is **no** official standard markup format, let alone a documentation - methodology, akin to JavaDoc. The question of methodology is at a + methodology akin to JavaDoc. The question of methodology is at a much higher level than syntax (which this PEP addresses). It is potentially much more controversial and difficult to resolve, and is intentionally left out of this discussion. @@ -761,20 +761,20 @@ References & Footnotes .. _A Record of reStructuredText Syntax Alternatives: http://docutils.sourceforge.net/spec/rst/alternatives.html -.. [PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton +.. _Docutils: http://docutils.sourceforge.net/ + +.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton (http://www.python.org/peps/pep-0001.html) -.. [PEP-9] PEP 9, Sample PEP Template, Warsaw +.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw (http://www.python.org/peps/pep-0009.html) -.. _Docutils: http://docutils.sourceforge.net/ - .. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just "``import this``" in Python) __ http://www.python.org/doc/Humor.html#zen -.. [PEP-216] PEP 216, Docstring Format, Zadka +.. [#PEP-216] PEP 216, Docstring Format, Zadka (http://www.python.org/peps/pep-0216.html) @@ -787,7 +787,7 @@ This document has been placed in the public domain. Acknowledgements ================ -Some text is borrowed from PEP 216, Docstring Format [PEP-216]_, by +Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by Moshe Zadka. Special thanks to all members past & present of the Python Doc-SIG_. -- cgit v1.2.1 From 6927e19091214c51280889c64eb4ba1eb3489767 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Jul 2002 01:36:52 +0000 Subject: Added "simple table" syntax to supplement the existing but newly-renamed "grid tables". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@307 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 171 ++++++++++++++++++++++++++++++++------ 1 file changed, 146 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d996adf7a..659e952d9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -136,15 +136,26 @@ Here are examples of `body elements`_: >>> print '(cut and pasted from interactive Python sessions)' (cut and pasted from interactive Python sessions) -- Tables_:: +- Two syntaxes for tables_: - +------------------------+------------+----------+ - | Header row, column 1 | Header 2 | Header 3 | - +========================+============+==========+ - | body row 1, column 1 | column 2 | column 3 | - +------------------------+------------+----------+ - | body row 2 | Cells may span | - +------------------------+-----------------------+ + 1. `Grid tables`_; complete, but complex and verbose:: + + +------------------------+------------+----------+ + | Header row, column 1 | Header 2 | Header 3 | + +========================+============+==========+ + | body row 1, column 1 | column 2 | column 3 | + +------------------------+------------+----------+ + | body row 2 | Cells may span | + +------------------------+-----------------------+ + + 2. `Simple tables`_; easy and compact, but limited:: + + ==================== ========== ========== + Header row, column 1 Header 2 Header 3 + ==================== ========== ========== + body row 1, column 1 column 2 column 3 + body row 2 Cells may span columns + ==================== ====================== - `Explicit markup blocks`_ all begin with an explicit block marker, two periods and a space: @@ -1109,17 +1120,38 @@ Tables DTD elements: table, tgroup, colspec, thead, tbody, row, entry. -Tables are described with a visual outline made up of the characters +ReStructuredText provides two syntaxes for delineating table cells: +`Grid Tables`_ and `Simple Tables`_. + +As with other body elements, blank lines are required before and after +tables. Tables' left edges should align with the left edge of +preceding text blocks; if indented, the table is considered to be part +of a block quote. + +Once isolated, each table cell is treated as a miniature document; the +top and bottom cell boundaries act as delimiting blank lines. Each +cell contains zero or more body elements. Cell contents may include +left and/or right margins, which are removed before processing. + + +Grid Tables +``````````` + +Grid tables provide a complete table representation via grid-like +"ASCII art". Grid tables allow arbitrary cell contents (body +elements), and both row and column spans. However, grid tables can be +cumbersome to produce, especially for simple data sets. The `Emacs +table mode`_ is a tool that allows easy editing of grid tables, in +Emacs. See `Simple Tables`_ for a simpler (but limited) +representation. + +Grid tables are described with a visual grid made up of the characters "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines (row separators). The equals sign ("=") may be used to separate -optional header rows from the table body. The vertical bar ("|") is -used for vertical lines (column separators). The plus sign ("+") is -used for intersections of horizontal and vertical lines. - -Each table cell is treated as a miniature document; the top and bottom -cell boundaries act as delimiting blank lines. Each cell contains -zero or more body elements. Cell contents may include left and/or -right margins, which are removed before processing. Example:: +optional header rows from the table body (not supported by the `Emacs +table mode`_). The vertical bar ("|") is used for vertical lines +(column separators). The plus sign ("+") is used for intersections of +horizontal and vertical lines. Example:: +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | @@ -1134,14 +1166,9 @@ right margins, which are removed before processing. Example:: | body row 4 | | - body elements. | +------------------------+------------+---------------------+ -As with other body elements, blank lines are required before and after -tables. Tables' left edges should align with the left edge of -preceding text blocks; otherwise, the table is considered to be part -of a block quote. - -Some care must be taken with tables to avoid undesired interactions -with cell text in rare cases. For example, the following table -contains a cell in row 2 spanning from column 2 to column 4:: +Some care must be taken with grid tables to avoid undesired +interactions with cell text in rare cases. For example, the following +table contains a cell in row 2 spanning from column 2 to column 4:: +--------------+----------+-----------+-----------+ | row 1, col 1 | column 2 | column 3 | column 4 | @@ -1186,6 +1213,100 @@ Another possibility is to add an extra line to row 2:: +--------------+----------+-----------+-----------+ +Simple Tables +````````````` + +Simple tables provide a compact and easy to type but limited +row-oriented table representation for simple data sets. Cell contents +are typically single paragraphs, although arbitrary body elements may +be represented in most cells. Simple tables allow multi-line rows and +column spans, but not row spans. See `Grid Tables`_ above for a +complete table representation. + +Simple tables are described with horizontal borders made up of "=" and +"-" characters. The equals sign ("=") is used for top and bottom +table borders, and to separate optional header rows from the table +body. The hyphen ("-") is used to indicate column spans in a single +row by underlining the joined columns. + +A simple table begins with a top border of equals signs with one or +more spaces at each column boundary (two or more spaces recommended). +Regardless of spans, the top border *must* fully describe all table +columns. There must be at least two columns in the table (to +differentiate it from section headers). The last of the optional +header rows is underlined with '=', again with spaces at column +boundaries. There may not be a blank line below the header row +separator; it would be interpreted as the bottom border of the table. +The bottom boundary of the table consists of '=' underlines, also with +spaces at column boundaries. For example, here is a truth table, a +three-column table with one header row and four body rows:: + + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + +Underlines of '-' may be used to indicate column spans by "filling in" +column margins to join adjacent columns. Column span underlines must +be complete (they must cover all columns) and align with established +column boundaries. Text lines containing column span underlines may +not contain any other text. A column span underline applies only to +one row immediately above it. For example, here is a table with a +column span in the header:: + + ===== ===== ====== + Inputs Output + ------------ ------ + A B A or B + ===== ===== ====== + False False False + True False True + False True True + True True True + ===== ===== ====== + +Each line of text must contain spaces at column boundaries, except +where cells have been joined by column spans. Each line of text +starts a new row, except when there is a blank cell in the first +column. In that case, that line of text is parsed as a continuation +line. For this reason, cells in the first column of new rows (*not* +continuation lines) *must* contain some text; blank cells would lead +to a misinterpretation. An empty comment ("..") is sufficient and +will be omitted from the processed output. Also, cells in the first +column are limited to one line of text. + +Blank lines are permitted within simple tables. Their interpretation +depends on the context. Blank lines *between* rows are ignored. +Blank lines *within* multi-line rows may separate paragraphs or other +body elements within cells. + +The rightmost column is unbounded; text may continue past the edge of +the table (as indicated by the table borders). However, it is +recommended that borders be made long enough to contain the entire +text. + +The following example illustrates continuation lines (row 2 consists +of two lines of text, and four lines for row 3), a blank line +separating paragraphs (row 3, column 2), and text extending past the +right edge of the table:: + + ===== ===== + col 1 col 2 + ===== ===== + 1 Second column of row 1. + 2 Second column of row 2. + Second line of paragraph. + 3 - Second column of row 3. + + - Second item in bullet + list (row 3, column 2). + ===== ===== + + Explicit Markup Blocks ---------------------- -- cgit v1.2.1 From 072c69c92964642a05d2b9c91b4e4321890d933b Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Jul 2002 01:48:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@313 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/problems.txt | 3 ++- docs/dev/todo.txt | 21 ++++++++++++++++----- 2 files changed, 18 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index 1d1e8b208..25fda8136 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -465,7 +465,8 @@ documentation. Alternatives: - Cells in the first column are limited to one line of text. - Cells in the first column *must* contain some text; blank cells - would lead to a misinterpretation. + would lead to a misinterpretation. An empty comment ("..") is + sufficient. 6. Combining alternative 3 and 4, a bullet list in the first column could mean multi-line rows, and no bullet list means single-line diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 089c5c4a7..092c7e8ab 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -40,6 +40,11 @@ Bugs Idea: two-pass hyperlink resolution, ignoring errors on the first pass? +- Section headers must have underlines at least 4 characters long. + But when the section title is only 3 characters long, it's natural + to underline with "===" (I just did). The parser should produce a + warning in such cases. + General ------- @@ -230,9 +235,6 @@ __ rst/alternatives.html#or-not-to-do the left edge of the first line if it began on the same line as the field name. -- Make footnotes two-way, GNU-style? What if there are multiple - references to a single footnote? - - 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:: @@ -296,13 +298,17 @@ __ rst/alternatives.html#or-not-to-do John Doe wrote:: - > Great idea! + >> Great idea! > > Why didn't I think of that? - Every line of the literal block would have to begin with the same + The literal block would have to be a continuous text block (the + first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. +- The parser doesn't know anything about double-width characters such + as Chinese hanza & Japanese kanji/kana. + Directives `````````` @@ -628,6 +634,11 @@ Front-Ends conflicts) to splitting common and component-specific options apart. +- Allow multiple option groups per component (thus enabling component + subclasses to easily incorporate their superclass' options). + +- Parameterize help text & defaults somehow? Perhaps a callback? + Project Policies ================ -- cgit v1.2.1 From 8a2a8c7bb67756e1c7f4429094bcf2e02139ac5b Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 18 Jul 2002 02:00:37 +0000 Subject: fixed link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@314 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 659e952d9..abf85b19c 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2454,12 +2454,13 @@ Markup errors are handled according to the specification in `PEP .. _DocTitle transform: .. _DocInfo transform: http://docutils.sourceforge.net/docutils/transforms/frontmatter.py -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html .. _getopt.py: http://www.python.org/doc/current/lib/module-getopt.html .. _GNU libc getopt_long(): http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html +.. _Emacs table mode: http://table.sourceforge.net/ .. _Index of WWW Addressing Schemes: http://www.w3.org/Addressing/schemes.html .. _World Wide Web Consortium: http://www.w3.org/ -- cgit v1.2.1 From d485602ebab4977879b816aa4f2ba0c9eaedf6b3 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 19 Jul 2002 02:42:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@328 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 33 ++++++++++++--------------------- 1 file changed, 12 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 092c7e8ab..29f79947d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -94,12 +94,6 @@ General permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?) -- @@@ Implement a PEP reader. (Reader for RST-PEP format done. - Writer support needed.) - - - Implement a specialized PEP/HTML writer? Or implement a generic - `templating system`_, with PEP/HTML as one application? - - Need a Unicode -> HTML entities codec for HTML writer? - Fix tests to run standalone. I.e., allow:: @@ -108,7 +102,7 @@ General test_inline_markup.py Raises an exception with path processing on GNU/Linux (but only - sometimes?). + sometimes???). - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? @@ -126,6 +120,7 @@ Specification - Fill in the blanks in API details. - Specify the nodes.py internal data structure implementation. + Or link to doctree.txt? [Tibs:] Eventually we need to have direct documentation in there on how it all hangs together - the DTD is not enough @@ -324,9 +319,9 @@ Directives - _`html.imagemap` (Useful outside of HTML? If not, replace with image only in non-HTML writers?) - - _`parts.endnotes` + - _`parts.endnotes`: See `Footnote & Citation Gathering`_. - - _`parts.citations` + - _`parts.citations`: See `Footnote & Citation Gathering`_. - _`parts.topic` (maybe "body.topic") @@ -404,12 +399,6 @@ Directives lists). Without special syntax, this directive becomes low priority. - - _`body.columns`: Multi-column table/list. Number of columns as - argument? Several `alternative syntaxes`__ are proposed that - might not need a directive.. - - __ rst/problems.html#tables - - @@ _`body.verse`: Paragraphs with linebreaks preserved, *and* inline markup support too. Use cases: verse (poetry, song lyrics, etc.), address blocks. A directive would be easy; what about a @@ -515,10 +504,11 @@ Directives Unimplemented Transforms ------------------------ -Footnote Gathering -`````````````````` +Footnote & Citation Gathering +````````````````````````````` -Collect and move footnotes to the end of a document. +Collect and move footnotes & citations to the end of a document. +(Separate transforms.) Hyperlink Target Gathering @@ -582,8 +572,8 @@ HTML Writer of all list items lack a

    (perhaps "--compact-all-lists" and "--compact-simple-lists")? - Tried it; not easy. If you're interested, email me for a copy of - the patch. + Tried it. Twice. Not easy. If you're interested, email me for a + copy of the patches. - Add more support for elements, especially for navigation bars. @@ -637,7 +627,8 @@ Front-Ends - Allow multiple option groups per component (thus enabling component subclasses to easily incorporate their superclass' options). -- Parameterize help text & defaults somehow? Perhaps a callback? +- Parameterize help text & defaults somehow? Perhaps a callback? Or + initialize ``cmdline_options`` in ``__init__``? Project Policies -- cgit v1.2.1 From 8d80ab42497a14aa1ede2efed478ed241db51b52 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 19 Jul 2002 03:09:24 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@330 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 29f79947d..2ed81757a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -111,6 +111,9 @@ General backlinks: no TOC backlinks, backlinks to TOC entries, or backlinks to TOC itself only. +- Add resource file support (~/.docutils?): overrides application + defaults, overridden by command-line options. What syntax to use? + Specification ------------- -- cgit v1.2.1 From 1369e61bed0ec3e1da3ed2cc4d7eedbe409f6844 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 20 Jul 2002 03:21:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@338 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2ed81757a..2d244ab0c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -68,6 +68,10 @@ General - Howto: Directives - User docs. + + - How to use the front-ends (docs/tools.txt). + + - Configuration file syntax & recognized entries. - Refactor @@ -111,9 +115,6 @@ General backlinks: no TOC backlinks, backlinks to TOC entries, or backlinks to TOC itself only. -- Add resource file support (~/.docutils?): overrides application - defaults, overridden by command-line options. What syntax to use? - Specification ------------- -- cgit v1.2.1 From 805a0f809700599f03b5df222a5e495428079e58 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 23 Jul 2002 02:39:25 +0000 Subject: minimize HTML whitespace git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@349 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0287.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 74112d2c5..93e36bffb 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -772,7 +772,7 @@ References & Footnotes .. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just "``import this``" in Python) - __ http://www.python.org/doc/Humor.html#zen +__ http://www.python.org/doc/Humor.html#zen .. [#PEP-216] PEP 216, Docstring Format, Zadka (http://www.python.org/peps/pep-0216.html) -- cgit v1.2.1 From a277893cdd0f8adca0cbac657f0724c4b61e6b0d Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 24 Jul 2002 01:35:56 +0000 Subject: Added simple table. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@354 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 83 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index aa0d8f3ed..ea98e6788 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -20,7 +20,7 @@

    http://docutils.sourceforge.net/docs/rst/quickref.html
    Being a cheat-sheet for reStructuredText -
    Version 0.8a of 2002-07-12 +
    Version 0.9 of 2002-07-23

    The full details may be found on the @@ -625,6 +625,10 @@ This means that something like:

    (details?) +

    There are two syntaxes for tables in reStructuredText. Grid + tables are complete but cumbersome to create. Simple tables are + easy to create but limited (no row spans, etc.).

    +

    @@ -634,19 +638,22 @@ This means that something like: +
    -    +------------+------------+-----------+ -
        | Header 1   | Header 2   | Header 3  | -
        +============+============+===========+ -
        | body row 1 | column 2   | column 3  | -
        +------------+------------+-----------+ -
        | body row 2 | Cells may span columns.| -
        +------------+------------+-----------+ -
        | body row 3 | Cells may  | - Cells   | -
        +------------+ span rows. | - contain | -
        | body row 4 |            | - blocks. | -
        +------------+------------+-----------+ +

    Grid table:

    + +

    +------------+------------+-----------+ +
    | Header 1   | Header 2   | Header 3  | +
    +============+============+===========+ +
    | body row 1 | column 2   | column 3  | +
    +------------+------------+-----------+ +
    | body row 2 | Cells may span columns.| +
    +------------+------------+-----------+ +
    | body row 3 | Cells may  | - Cells   | +
    +------------+ span rows. | - contain | +
    | body row 4 |            | - blocks. | +
    +------------+------------+-----------+

    		 - +

    Grid table:

    +
    Header 1 Header 2 @@ -670,6 +677,56 @@ This means that something like:
    body row 4
    +
    +

    Simple table:

    + +

    =====  =====  ====== +
       Inputs     Output +
    ------------  ------ +
      A      B    A or B +
    =====  =====  ====== +
    False  False  False +
    True   False  True +
    False  True   True +
    True   True   True +
    =====  =====  ======

    + +     		+

    Simple table:

    + + + + + + + + + + + + + + +
    Inputs + Output +
    A + B + A or B +
    False + False + False +
    True + False + True +
    False + True + True +
    True + True + True +
    +

    Transitions

    -- cgit v1.2.1 From a29e32f3d2999d91eba1444f59c809de7489fed9 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 24 Jul 2002 01:44:44 +0000 Subject: Added cautions for anonymous hyperlink use. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@361 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index abf85b19c..74e8cf3c8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1676,12 +1676,14 @@ Anonymous Hyperlinks The `World Wide Web Consortium`_ recommends in its `HTML Techniques for Web Content Accessibility Guidelines`_ that authors should -"clearly identify the target of each link." Hyperlink references +"clearly identify the target of each link." Hyperlink references should be as verbose as possible, but duplicating a verbose hyperlink name in the target is onerous and error-prone. Anonymous hyperlinks are designed to allow convenient verbose hyperlink references, and are analogous to `Auto-Numbered Footnotes`_. They are particularly useful -in short or one-off documents. +in short or one-off documents. However, this feature is easily abused +and can result in unreadable plaintext and/or unmaintainable +documents. Caution is advised. Anonymous `hyperlink references`_ are specified with two underscores instead of one:: @@ -1703,7 +1705,10 @@ to its target. Instead, the order of anonymous hyperlink references and targets within the document is significant: the first anonymous reference will link to the first anonymous target. The number of anonymous hyperlink references in a document must match the number of -anonymous targets. +anonymous targets. For readability, it is recommended that targets be +kept close to references. Take care when editing text containing +anonymous references; adding, removing, and rearranging references +require attention to the order of corresponding targets. Directives -- cgit v1.2.1 From 9aff0d96c5f7e0fff2b9df8cc522d922534753dd Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 24 Jul 2002 01:45:41 +0000 Subject: Added "backlinks" attribute to "contents" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@362 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index d39f488c3..039e7fd0c 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -212,6 +212,9 @@ The following attributes are recognized: Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled. +``backlinks`` : "entry" or "top" or "none" + Generate links from section headers back to the table of contents + entries, the table of contents itself, or generate no backlinks. Footnotes -- cgit v1.2.1 From 18fba0d32c5d883296ddb64ee8ad6dc9fa1ddcd2 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 24 Jul 2002 01:51:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@364 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 4 +++- docs/dev/todo.txt | 7 ------- 2 files changed, 3 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 92681bb2e..e241ed557 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1543,7 +1543,9 @@ A new type of "inline external hyperlink" has been proposed. Advantages and disadvantages are similar to those in (2). Readability is still an issue, but the syntax is a bit less - heavyweight (reduced line noise). + heavyweight (reduced line noise). Backquotes are required, even + for one-word references; the target URL is included within the + reference text, forcing a phrase context. Problem: how to refer to a title like "HTML Anchors: " (which ends with an HTML/SGML/XML tag)? We could either require more diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2d244ab0c..8b273ce73 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -111,10 +111,6 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- Add a command-line option & directive attribute to control TOC - backlinks: no TOC backlinks, backlinks to TOC entries, or backlinks - to TOC itself only. - Specification ------------- @@ -628,9 +624,6 @@ Front-Ends conflicts) to splitting common and component-specific options apart. -- Allow multiple option groups per component (thus enabling component - subclasses to easily incorporate their superclass' options). - - Parameterize help text & defaults somehow? Perhaps a callback? Or initialize ``cmdline_options`` in ``__init__``? -- cgit v1.2.1 From 299249be5abfef3d4d12afbc4152465b5573f406 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Jul 2002 01:42:59 +0000 Subject: "Docutils Front-End Tools" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@365 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 698 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 698 insertions(+) create mode 100644 docs/user/tools.txt (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt new file mode 100644 index 000000000..923b17a0d --- /dev/null +++ b/docs/user/tools.txt @@ -0,0 +1,698 @@ +========================== + + Docutils Front-End Tools + +========================== + + + +:Author: David Goodger + +:Contact: goodger@users.sourceforge.net + +:Revision: $Revision$ + +:Date: $Date$ + + + +Once the Docutils package is unpacked, you will discover a "``tools``" + +directory containing several front ends for common Docutils + +processing. Most front ends combine a Docutils "Reader" (which knows + +how to interpret a file in context) with a "Writer" (which knows how + +to generate a specific data format) + + + +Each tool has a "``--help``" option which lists the `command-line + +options`_ and arguments it supports. Processing can also be + +customized with `configuration files`_. + + + + + +.. contents:: + + + + + +html.py + +======= + + + +:Reader: Standalone + +:Parser: reStructuredText + +:Writer: HTML + + + +The ``html.py`` front end reads standalone reStructuredText source + +files and produces HTML 4 (XHTML 1) output. It inserts a link to a + +cascading stylesheet (``.css`` file), ``default.css`` unless specified + +by a "--stylesheet" command-line option or in a configuration file. + +The ``tools/default.css`` stylesheet is provided for basic use. + + + + + +pep.py + +====== + + + +:Reader: PEP + +:Parser: reStructuredText + +:Writer: PEP/HTML + + + +``pep.py`` reads a new-style PEP (marked up with reStructuredText) and + +produces HTML. It requires a template file and a stylesheet. By + +default, it makes use of a ``pep-html-template`` file and a + +``default.css`` stylesheet in the current directory, but these can be + +overridden by command-line options or configuration files. The + +``tools/stylesheets/pep.css`` stylesheet is intended specifically for + +PEP use. + + + +The ``docutils.conf`` `configuration file`_ in the "``spec``" + +directory of Docutils contains a default setup for use in processing + +the PEP files there (``spec/pep-*.txt``) into HTML. It specifies + +defaults of ``tools/pep-html-template`` and + +``tools/stylesheets/pep.css``. + + + + + +pep2html.py + +=========== + + + +:Reader: PEP + +:Parser: reStructuredText + +:Writer: PEP/HTML + + + +``pep2html.py`` is a modified version of the original script by + +Fredrik Lundh, with support for Docutils added. It reads the + +beginning of a PEP text file to determine the format (old-style + +indented or new-style reStructuredText) and processes accordingly. + +Since it does not use the Docutils front end mechanism (the common + +command-line options are not supported), it must be configured using + +`configuration files`_. + + + + + +docutils-xml.py + +=============== + + + +:Reader: Standalone + +:Parser: reStructuredText + +:Writer: XML (Docutils native) + + + +The ``docutils-xml.py`` front end produces Docutils-native XML output. + +This can be transformed with standard XML tools such as XSLT + +processors into arbitrary final forms. + + + + + +publish.py + +========== + + + +:Reader: Standalone + +:Parser: reStructuredText + +:Writer: Pseudo-XML + + + +``publish.py`` is used for debugging the Docutils Reader -> Transform + +-> Writer pipeline. It produces a compact pretty-printed + +"pseudo-XML", where nesting is indicated by indentation (no end-tags). + +External attributes for all elements are output, and internal + +attributes for any leftover "pending" elements are also given. + + + + + +quicktest.py + +============ + + + +:Reader: N/A + +:Parser: reStructuredText + +:Writer: N/A + + + +The ``quicktest.py`` tool is used for testing the reStructuredText + +parser. It does not use the Docutils Reader/Writer mechanism. + +Rather, it does its own I/O and calls the parser directly. No + +transforms are applied to the parsed document. Various forms output + +are possible: + + + +- Pretty-printed pseudo-XML + +- Test data (Python list of input and pseudo-XML output strings; + + useful for creating new test cases) + +- Pretty-printed native XML + +- Raw native XML (with or without a stylesheet reference) + + + + + +Customization + +============= + + + +Command-Line Options + +-------------------- + + + +Each front-end tool supports command-line options for one-off + +customization. For persistent customization, use `configuration + +files`_. + + + +Use the "--help" option on each of the front ends to list the + +command-line options it supports. Command-line options and their + +corresponding configuration file entry names are listed in + +`Configuration File Entries`_ below. + + + + + +.. _configuration file: + + + +Configuration Files + +------------------- + + + +Configuration files are used for persistent customization; they can be + +set once and take effect every time you use a front-end tool. + + + +By default, Docutils checks three places for configuration files, in + +the following order: + + + +1. ``/etc/docutils.conf``: This is a system-wide configuration file, + + applicable to all Docutils processing on the system. + + + +2. ``./docutils.conf``: This is a project-specific configuration file, + + located in the current directory. The Docutils front end has to be + + executed from the directory containing this configuration file for + + it to take effect. The project-specific configuration file + + overrides the system-wide file. + + + +3. ``~/.docutils``: This is a user-specific configuration file, + + located in the user's home directory. This file overrides both the + + system-wide and project-specific configuration files. + + + +If more than one configuration file is found, all will be read but + +later entries will override earlier ones. For example, a "stylesheet" + +entry in a user-specific configuration file will override a + +system-wide entry. + + + +Configuration files use the standard ConfigParser.py_ Python_ module. + +From its documentation: + + + + The configuration file consists of sections, lead by a "[section]" + + header and followed by "name: value" entries, with continuations + + in the style of `RFC 822`_; "name=value" is also accepted. Note + + that leading whitespace is removed from values. The optional + + values can contain format strings which refer to other values in + + the same section, or values in a special DEFAULT section. + + Additional defaults can be provided upon initialization and + + retrieval. Lines beginning with "#" or ";" are ignored and may be + + used to provide comments. + + + +Docutils only uses an "[options]" section; all other sections will be + +ignored. + + + +Configuration entry names correspond to internal option attributes. + +Underscores ("_") and hyphens ("-") can be used interchangably in + +entry names. The correspondence between entry names and command-line + +options is listed in `Configuration File Entries`_ below. + + + +.. _ConfigParser.py: + + http://www.python.org/doc/current/lib/module-ConfigParser.html + +.. _Python: http://www.python.org/ + +.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt + + + + + +Configuration File Entries + +-------------------------- + + + +The entry names listed below may be specified in `configuration + +files`_ (hyphens may be used in place of underscores). Some knowledge + +of Python_ is assumed for some attributes. + + + +==================== ================================================ + +Entry Name Description and Command-Line Options + +==================== ================================================ + +datestamp Include a time/datestamp in the document footer. + + Contains a format string for ``time.strftime``. + + + + Default: None. + + + + ``--date, -d, --time, -t, --no-datestamp`` + + + +debug Report debug-level system messages. + + + + Default: don't (None). + + + + ``--debug, --no-debug`` + + + +dump_internals Hidden option: At the end of processing, print + + out all internal attributes of the document + + (``document.__dict__``). + + + + Default: don't (None). + + + + ``--dump-internals`` + + + +footnote_backlinks Enable or disable backlinks from footnotes and + + citations to their references. + + + + Default: enabled (1). + + + + ``--footnote-backlinks, --no-footnote-backlinks`` + + + +generator Include a "Generated by Docutils" credit and + + link in the document footer. + + + + Default: off (None). + + + + ``--generator, -g, --no-generator`` + + + +halt_level Set the threshold at or above which system + + messages are converted to exceptions, halting + + execution immediately. + + + + Default: severe (4). + + + + ``--halt, --strict`` + + + +indents XML-specific: Generate XML with indents and + + newlines. + + + + Default: None. + + + + ``--indents`` + + + +input_encoding Default: auto-detect (None). + + + + ``--input-encoding, -i`` + + + +language_code Default: English ("en"). + + + + ``--language, -l`` + + + +newlines XML-specific: Generate XML with newlines before + + and after tags. + + + + Default: None. + + + + ``--newlines`` + + + +no_random PEP/HTML-specific hidden option: Workaround for + + platforms which core-dump on "``import + + random``". + + + + Default: random enabled (None). + + + + ``--no-random`` + + + +output_encoding Default: UTF-8. + + + + ``--output-encoding, -o`` + + + +pep_home PEP/HTML-specific: Home URL prefix for PEPs. + + + + Default: current directory ("."). + + + + ``--pep-home`` + + + +pep_stylesheet PEP/HTML-specific: Overrides HTML stylesheet. + + + + Default: None. + + + + ``--pep-stylesheet`` + + + +pep_template PEP/HTML-specific: PEP template file. + + + + Default: "pep-html-template". + + + + ``--pep-template`` + + + +python_home PEP/HTML-specific: Python's home URL. + + + + Default: parent directory (".."). + + + + ``--python-home`` + + + +report_level Set verbosity threshold at or above which system + + messages are reported. + + + + Default: warning (2). + + + + ``--report, -r, --verbose`` + + + +source_link Include a "View document source" link in the + + document footer. + + + + Default: don't (None). + + + + ``--source-link, --no-source-link`` + + + +stylesheet HTML-specific. + + + + Default: "default.css". + + + + ``--stylesheet`` + + + +toc_backlinks Enable backlinks from section titles to table of + + contents entries ("entry"), to the top of the + + TOC ("top"), or disable ("none"). + + + + Default: "entry". + + + + ``--toc-entry-backlinks, --toc-top-backlinks, + + --no-toc-backlinks`` + + + +warning_stream Send the output of system messages (warnings) to + + a file. + + + + Default: stderr (None). + + + + ``--warnings`` + +==================== ================================================ + + + + + +.. + + Local Variables: + + mode: indented-text + + indent-tabs-mode: nil + + sentence-end-double-space: t + + fill-column: 70 + + End: + -- cgit v1.2.1 From c1cdf743e8823711597a7a0ed47822af56c030e2 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Jul 2002 01:55:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@371 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 22 ++++++++++++---------- docs/peps/pep-0258.txt | 2 +- docs/ref/rst/restructuredtext.txt | 11 ++++++----- 3 files changed, 19 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8b273ce73..a0b445f26 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,6 +45,11 @@ Bugs to underline with "===" (I just did). The parser should produce a warning in such cases. +- 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. + General ------- @@ -69,7 +74,7 @@ General - User docs. - - How to use the front-ends (docs/tools.txt). + - How to use the front-end tools (docs/tools.txt). - Configuration file syntax & recognized entries. @@ -301,9 +306,6 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. -- The parser doesn't know anything about double-width characters such - as Chinese hanza & Japanese kanji/kana. - Directives `````````` @@ -582,8 +584,8 @@ HTML Writer iframe, img, map. -Front-Ends ----------- +Front-End Tools +--------------- - Common and component-specific options must not conflict. Reserve short options for the core, and restrict components to long @@ -596,7 +598,7 @@ Front-Ends 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 + front end (e.g. ``pep2html [options]``, ``pysource2pdf [options]``). b) _`Partially qualified`: Reader is hard-coded, and the Writer is @@ -607,7 +609,7 @@ Front-Ends 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 + [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 @@ -619,7 +621,7 @@ Front-Ends 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 + 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. @@ -872,7 +874,7 @@ structure is recommended:: ... test/ # Test suite. ... - tools/ # For front-ends etc. + tools/ # For front ends etc. ... setup.py # Use Distutils to install the component # code and tools/ files into the right diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index a66feeb95..905aae688 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -322,7 +322,7 @@ Specification convenience function "publish()". See `Publisher`_ above. - Module "docutils.frontend" provides command-line and option - processing for Docutils front-ends. + processing for Docutils front-end tools. - Module "docutils.io" provides a uniform API for low-level input and output. diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 74e8cf3c8..4c56bd25d 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -795,11 +795,12 @@ The syntax for field arguments may be extended in the future. For example, quoted phrases may be treated as a single argument, and direct support for the "name=value" syntax may be added. -Standard RFC822 headers cannot be used for this construct because they -are ambiguous. A word followed by a colon at the beginning of a line -is common in written text. However, in well-defined contexts such as -when a field list invariably occurs at the beginning of a document -(PEPs and email messages), standard RFC822 headers could be used. +Standard RFC822_ headers cannot be used for this construct because +they are ambiguous. A word followed by a colon at the beginning of a +line is common in written text. However, in well-defined contexts +such as when a field list invariably occurs at the beginning of a +document (PEPs and email messages), standard RFC822 headers could be +used. Syntax diagram (simplified):: -- cgit v1.2.1 From 6b905e0d6511b550d563f0f7c79dd09a2ccdcb14 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 25 Jul 2002 02:02:54 +0000 Subject: removed extra lines git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@373 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 349 ---------------------------------------------------- 1 file changed, 349 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 923b17a0d..cf3e092d7 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -1,698 +1,349 @@ ========================== - Docutils Front-End Tools - ========================== - - :Author: David Goodger - :Contact: goodger@users.sourceforge.net - :Revision: $Revision$ - :Date: $Date$ - - Once the Docutils package is unpacked, you will discover a "``tools``" - directory containing several front ends for common Docutils - processing. Most front ends combine a Docutils "Reader" (which knows - how to interpret a file in context) with a "Writer" (which knows how - to generate a specific data format) - - Each tool has a "``--help``" option which lists the `command-line - options`_ and arguments it supports. Processing can also be - customized with `configuration files`_. - - - .. contents:: - - - html.py - ======= - - :Reader: Standalone - :Parser: reStructuredText - :Writer: HTML - - The ``html.py`` front end reads standalone reStructuredText source - files and produces HTML 4 (XHTML 1) output. It inserts a link to a - cascading stylesheet (``.css`` file), ``default.css`` unless specified - by a "--stylesheet" command-line option or in a configuration file. - The ``tools/default.css`` stylesheet is provided for basic use. - - - pep.py - ====== - - :Reader: PEP - :Parser: reStructuredText - :Writer: PEP/HTML - - ``pep.py`` reads a new-style PEP (marked up with reStructuredText) and - produces HTML. It requires a template file and a stylesheet. By - default, it makes use of a ``pep-html-template`` file and a - ``default.css`` stylesheet in the current directory, but these can be - overridden by command-line options or configuration files. The - ``tools/stylesheets/pep.css`` stylesheet is intended specifically for - PEP use. - - The ``docutils.conf`` `configuration file`_ in the "``spec``" - directory of Docutils contains a default setup for use in processing - the PEP files there (``spec/pep-*.txt``) into HTML. It specifies - defaults of ``tools/pep-html-template`` and - ``tools/stylesheets/pep.css``. - - - pep2html.py - =========== - - :Reader: PEP - :Parser: reStructuredText - :Writer: PEP/HTML - - ``pep2html.py`` is a modified version of the original script by - Fredrik Lundh, with support for Docutils added. It reads the - beginning of a PEP text file to determine the format (old-style - indented or new-style reStructuredText) and processes accordingly. - Since it does not use the Docutils front end mechanism (the common - command-line options are not supported), it must be configured using - `configuration files`_. - - - docutils-xml.py - =============== - - :Reader: Standalone - :Parser: reStructuredText - :Writer: XML (Docutils native) - - The ``docutils-xml.py`` front end produces Docutils-native XML output. - This can be transformed with standard XML tools such as XSLT - processors into arbitrary final forms. - - - publish.py - ========== - - :Reader: Standalone - :Parser: reStructuredText - :Writer: Pseudo-XML - - ``publish.py`` is used for debugging the Docutils Reader -> Transform - -> Writer pipeline. It produces a compact pretty-printed - "pseudo-XML", where nesting is indicated by indentation (no end-tags). - External attributes for all elements are output, and internal - attributes for any leftover "pending" elements are also given. - - - quicktest.py - ============ - - :Reader: N/A - :Parser: reStructuredText - :Writer: N/A - - The ``quicktest.py`` tool is used for testing the reStructuredText - parser. It does not use the Docutils Reader/Writer mechanism. - Rather, it does its own I/O and calls the parser directly. No - transforms are applied to the parsed document. Various forms output - are possible: - - - Pretty-printed pseudo-XML - - Test data (Python list of input and pseudo-XML output strings; - useful for creating new test cases) - - Pretty-printed native XML - - Raw native XML (with or without a stylesheet reference) - - - Customization - ============= - - Command-Line Options - -------------------- - - Each front-end tool supports command-line options for one-off - customization. For persistent customization, use `configuration - files`_. - - Use the "--help" option on each of the front ends to list the - command-line options it supports. Command-line options and their - corresponding configuration file entry names are listed in - `Configuration File Entries`_ below. - - - .. _configuration file: - - Configuration Files - ------------------- - - Configuration files are used for persistent customization; they can be - set once and take effect every time you use a front-end tool. - - By default, Docutils checks three places for configuration files, in - the following order: - - 1. ``/etc/docutils.conf``: This is a system-wide configuration file, - applicable to all Docutils processing on the system. - - 2. ``./docutils.conf``: This is a project-specific configuration file, - located in the current directory. The Docutils front end has to be - executed from the directory containing this configuration file for - it to take effect. The project-specific configuration file - overrides the system-wide file. - - 3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. This file overrides both the - system-wide and project-specific configuration files. - - If more than one configuration file is found, all will be read but - later entries will override earlier ones. For example, a "stylesheet" - entry in a user-specific configuration file will override a - system-wide entry. - - Configuration files use the standard ConfigParser.py_ Python_ module. - From its documentation: - - The configuration file consists of sections, lead by a "[section]" - header and followed by "name: value" entries, with continuations - in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. The optional - values can contain format strings which refer to other values in - the same section, or values in a special DEFAULT section. - Additional defaults can be provided upon initialization and - retrieval. Lines beginning with "#" or ";" are ignored and may be - used to provide comments. - - Docutils only uses an "[options]" section; all other sections will be - ignored. - - Configuration entry names correspond to internal option attributes. - Underscores ("_") and hyphens ("-") can be used interchangably in - entry names. The correspondence between entry names and command-line - options is listed in `Configuration File Entries`_ below. - - .. _ConfigParser.py: - http://www.python.org/doc/current/lib/module-ConfigParser.html - .. _Python: http://www.python.org/ - .. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt - - - Configuration File Entries - -------------------------- - - The entry names listed below may be specified in `configuration - files`_ (hyphens may be used in place of underscores). Some knowledge - of Python_ is assumed for some attributes. - - ==================== ================================================ - Entry Name Description and Command-Line Options - ==================== ================================================ - datestamp Include a time/datestamp in the document footer. - Contains a format string for ``time.strftime``. - - Default: None. - - ``--date, -d, --time, -t, --no-datestamp`` - - debug Report debug-level system messages. - - Default: don't (None). - - ``--debug, --no-debug`` - - dump_internals Hidden option: At the end of processing, print - out all internal attributes of the document - (``document.__dict__``). - - Default: don't (None). - - ``--dump-internals`` - - footnote_backlinks Enable or disable backlinks from footnotes and - citations to their references. - - Default: enabled (1). - - ``--footnote-backlinks, --no-footnote-backlinks`` - - generator Include a "Generated by Docutils" credit and - link in the document footer. - - Default: off (None). - - ``--generator, -g, --no-generator`` - - halt_level Set the threshold at or above which system - messages are converted to exceptions, halting - execution immediately. - - Default: severe (4). - - ``--halt, --strict`` - - indents XML-specific: Generate XML with indents and - newlines. - - Default: None. - - ``--indents`` - - input_encoding Default: auto-detect (None). - - ``--input-encoding, -i`` - - language_code Default: English ("en"). - - ``--language, -l`` - - newlines XML-specific: Generate XML with newlines before - and after tags. - - Default: None. - - ``--newlines`` - - no_random PEP/HTML-specific hidden option: Workaround for - platforms which core-dump on "``import - random``". - - Default: random enabled (None). - - ``--no-random`` - - output_encoding Default: UTF-8. - - ``--output-encoding, -o`` - - pep_home PEP/HTML-specific: Home URL prefix for PEPs. - - Default: current directory ("."). - - ``--pep-home`` - - pep_stylesheet PEP/HTML-specific: Overrides HTML stylesheet. - - Default: None. - - ``--pep-stylesheet`` - - pep_template PEP/HTML-specific: PEP template file. - - Default: "pep-html-template". - - ``--pep-template`` - - python_home PEP/HTML-specific: Python's home URL. - - Default: parent directory (".."). - - ``--python-home`` - - report_level Set verbosity threshold at or above which system - messages are reported. - - Default: warning (2). - - ``--report, -r, --verbose`` - - source_link Include a "View document source" link in the - document footer. - - Default: don't (None). - - ``--source-link, --no-source-link`` - - stylesheet HTML-specific. - - Default: "default.css". - - ``--stylesheet`` - - toc_backlinks Enable backlinks from section titles to table of - contents entries ("entry"), to the top of the - TOC ("top"), or disable ("none"). - - Default: "entry". - - ``--toc-entry-backlinks, --toc-top-backlinks, - --no-toc-backlinks`` - - warning_stream Send the output of system messages (warnings) to - a file. - - Default: stderr (None). - - ``--warnings`` - ==================== ================================================ - - - .. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: - -- cgit v1.2.1 From 371e8d963cd1a0872b25b3d1521b507f5a1bb741 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 27 Jul 2002 03:41:19 +0000 Subject: elaborated; added usage & stylesheet examples; redid table git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@375 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 255 +++++++++++++++++++++++++++++----------------------- 1 file changed, 144 insertions(+), 111 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index cf3e092d7..f0b183125 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -9,13 +9,23 @@ Once the Docutils package is unpacked, you will discover a "``tools``" directory containing several front ends for common Docutils -processing. Most front ends combine a Docutils "Reader" (which knows -how to interpret a file in context) with a "Writer" (which knows how -to generate a specific data format) +processing. Most Docutils front ends combine a specific "Reader" +(which knows how to interpret a file in context), a "Parser" (which +understands the syntax of the text), and a "Writer" (which knows how +to generate a specific data format). Most front ends have common +options and the same command-line usage pattern:: -Each tool has a "``--help``" option which lists the `command-line -options`_ and arguments it supports. Processing can also be -customized with `configuration files`_. + toolname [options] [ [

    http://docutils.sourceforge.net/docs/rst/quickref.html
    Being a cheat-sheet for reStructuredText -
    Version 0.9 of 2002-07-23 +
    Version 0.10 of 2002-08-07 -

    The full details may be found on the +

    The full details of the markup may be found on the reStructuredText page. This document is just intended as a reminder. @@ -64,9 +68,11 @@

  4. Directives
  5. Substitution References and Definitions
  6. Comments
    7. +
  7. Getting Help
    8. -

    Inline Markup

    +

    Inline Markup

    (details?) @@ -180,7 +186,8 @@ markup delimiter characters, but that doesn't count because nothing is processed). -

    Escaping with Bashslashes

    +

    Escaping with Bashslashes

    (details?) @@ -228,7 +235,8 @@

    		escape with ""
    -

    Section Structure

    +

    Section Structure

    (details?) @@ -261,7 +269,8 @@ are "= - ` : ' " ~ ^ _ * + # < >". -

    Paragraphs

    +

    Paragraphs

    (details?) @@ -288,7 +297,8 @@ -

    Bullet Lists

    +

    Bullet Lists

    (details?) @@ -325,7 +335,8 @@ item and after the last, but is optional between items. -

    Enumerated Lists

    +

    Enumerated Lists

    (details?) @@ -360,7 +371,8 @@

-

Definition Lists

+

Definition Lists

(details?) @@ -400,7 +412,8 @@ -

Field Lists

+

Field Lists

(details?) @@ -433,7 +446,8 @@ -

Option Lists

+

Option Lists

(details?) @@ -480,7 +494,8 @@

There must be at least two spaces between the option and the description. -

Literal Blocks

+

Literal Blocks

(details?) @@ -558,7 +573,8 @@ This means that something like:

is possible. -

Block Quotes

+

Block Quotes

(details?) @@ -586,7 +602,8 @@ This means that something like: -

Doctest Blocks

+

Doctest Blocks

(details?) @@ -621,7 +638,8 @@ This means that something like: interactive Python session, then executes all such sessions to verify they still work exactly as shown." (From the doctest docs.) -

Tables

+

Tables

(details?) @@ -729,7 +747,8 @@ This means that something like: -

Transitions

+

Transitions

(details?) @@ -769,7 +788,8 @@ A transition marker is a horizontal line gap spanning one or more lines, marking text divisions or signaling changes in subject, time, point of view, or emphasis. -

Footnotes

+

Footnotes

(details?) @@ -861,7 +881,8 @@ A transition marker is a horizontal line same relative order. Similarly for auto-symbol footnotes ("[*]_"). -

Citations

+

Citations

(details?) @@ -913,11 +934,13 @@ A transition marker is a horizontal line -

Hyperlink Targets

+

Hyperlink Targets

(details?) -

External Hyperlink Targets

+

External Hyperlink Targets

@@ -955,7 +978,8 @@ A transition marker is a horizontal line printed documents, where the link needs to be presented explicitly, for example as a footnote. -

Internal Hyperlink Targets

+

Internal Hyperlink Targets

@@ -990,7 +1014,8 @@ A transition marker is a horizontal line
-

Indirect Hyperlink Targets

+

Indirect Hyperlink Targets

(details?) @@ -1025,7 +1050,8 @@ A transition marker is a horizontal line target. In the text, a double-underscore suffix is used to indicate an anonymous hyperlink reference. -

Implicit Hyperlink Targets

+

Implicit Hyperlink Targets

(details?) @@ -1051,7 +1077,8 @@ A transition marker is a horizontal line targets, too. -

Directives

+

Directives

(details?) @@ -1072,7 +1099,8 @@ A transition marker is a horizontal line

ball1 -

Substitution References and Definitions

+

Substitution References and Definitions

(details?) @@ -1102,7 +1130,8 @@ dispose of medical waste. -

Comments

+

Comments

(details?) @@ -1139,6 +1168,18 @@ dispose of medical waste. +

Getting Help

+ +

Users who have questions or need assistance with Docutils or + reStructuredText should post a + message to the Docutils-Users mailing list. The Docutils project web + site has more information. +

Authors: -- cgit v1.2.1 From 3d2f2e74848b639f85b0e64ead6ec78a6e67b20e Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 8 Aug 2002 00:21:15 +0000 Subject: - Added a table of contents. - Added feedback information. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@477 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index e2bda81fd..c335ac97a 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -4,6 +4,9 @@ A ReStructuredText Primer :Author: Richard Jones :Version: $Revision$ +.. contents:: + + The text below contains links that look like "(quickref__)". These are relative links that point to the `Quick reStructuredText`_ user reference. If these links don't work, please refer to the `master @@ -328,8 +331,17 @@ but there are a lot more to explore. The `Quick reStructuredText`_ user reference is a good place to go next. For complete details, the `reStructuredText Markup Specification`_ is the place to go [#]_. -.. _reStructuredText Markup Specification: - ../../spec/rst/reStructuredText.html +Users who have questions or need assistance with Docutils or +reStructuredText should `post a message`_ to the `Docutils-Users +mailing list`_. The `Docutils project web site`_ has more +information. .. [#] If that relative link doesn't work, try the master document: http://docutils.sourceforge.net/spec/rst/reStructuredText.html. + +.. _reStructuredText Markup Specification: + ../../spec/rst/reStructuredText.html +.. _post a message: mailto:docutils-users@lists.sourceforge.net +.. _Docutils-Users mailing list: + http://lists.sourceforge.net/lists/listinfo/docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ -- cgit v1.2.1 From 9920a415e33b05a3890a7d0ed848edc81182b62c Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 8 Aug 2002 00:23:31 +0000 Subject: - Added a "Getting Help" section. - Rearranged the structure. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@478 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index f58a7a62d..7d2de6c0d 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -7,6 +7,12 @@ :Revision: $Revision$ :Date: $Date$ +.. contents:: + + +Introduction +============ + Once the Docutils package is unpacked, you will discover a "``tools``" directory containing several front ends for common Docutils processing. Rather than a single all-purpose program, Docutils has @@ -29,11 +35,25 @@ used for the destination. If no arguments are specified, the standard input (stdin) is used for the source as well. -.. contents:: +Getting Help +------------ + +Users who have questions or need assistance with Docutils or +reStructuredText should `post a message`_ to the `Docutils-Users +mailing list`_. The `Docutils project web site`_ has more +information. +.. _post a message: mailto:docutils-users@lists.sourceforge.net +.. _Docutils-Users mailing list: + http://lists.sourceforge.net/lists/listinfo/docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ + + +The Tools +========= buildhtml.py -============ +------------ :Readers: Standalone, PEP :Parser: reStructuredText @@ -69,7 +89,7 @@ override config file settings or replace them altogether. html.py -======= +------- :Reader: Standalone :Parser: reStructuredText @@ -95,7 +115,7 @@ of processing, and links to the Docutils projects, add some options:: Stylesheets ------------ +``````````` ``html.py`` inserts into the generated HTML a link to a cascading stylesheet, defaulting to "``default.css``" (override with a @@ -123,7 +143,7 @@ incremental experimentation. pep.py -====== +------ :Reader: PEP :Parser: reStructuredText @@ -146,7 +166,7 @@ for more information. pep2html.py -=========== +----------- :Reader: PEP :Parser: reStructuredText @@ -167,7 +187,7 @@ files. If no arguments are given, all files of the form docutils-xml.py -=============== +--------------- :Reader: Standalone :Parser: reStructuredText @@ -179,7 +199,7 @@ processors into arbitrary final forms. publish.py -========== +---------- :Reader: Standalone :Parser: reStructuredText @@ -193,7 +213,7 @@ attributes for any leftover "pending" elements are also given. quicktest.py -============ +------------ :Reader: N/A :Parser: reStructuredText -- cgit v1.2.1 From d5f026e798598f57d02ab02ffa4b20efb818473f Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 9 Aug 2002 01:19:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@492 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 72 +++++++++++++++++++++++++++++++++++++------------- docs/peps/pep-0258.txt | 10 +++---- 2 files changed, 59 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7649fb083..b2ae4584f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -50,15 +50,16 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -- Text like "``--an-option``" can get wrapped badly in HTML browsers, - like "``--\nan-option``". Should inline literals prevent soft - linebreaks? Allow breaks at whitespace or not at all? - - @@@ This shouldn't be recognized as a list item:: A. Einstein was a really smart dude. + Or this:: + + 1. This is the heading of section one + ===================================== + The only problem is, what about this? :: A. Einstein was a really smart dude. @@ -68,12 +69,19 @@ Bugs A. Einstein was a really smart dude. B. So was Carl Sagan. + But what about this? Accidents can happen:: + + A. Einstein was a great influence on + B. Physicist, who was a colleague of + C. Chemist. They all worked in + Princeton, NJ. + Time to put more smarts into the list item recognition code, or just document it as a corner case and require escapes? E.g.:: \A. Einstein was a really smart dude. - (Bug report by Jeremy Hylton.) + (Bug reports by Jeremy Hylton and Dmitry Jemerov.) General @@ -85,11 +93,19 @@ General - Implementation docs. - - spec/doctree.txt: Doctree nodes (DTD element) semantics: + - spec/doctree.txt: Doctree element (DTD element) semantics: - External (public) attributes (node.attributes). - - Internal attributes (node.*). - - Linking mechanism. + - Internal attributes (node.*). (?) + - Linking mechanism. (?) + + Should this document be about the code (implementation details), + or about the DTD (document tree elements)? I'm having trouble + writing it because it's a bit schizo; doesn't know what it is. + Perhaps it should simply document the DTD elements, their + semantics, and only refer to the implementation. Descriptions + of the classes, their methods, and internal attributes belong in + the implementation docs (docstrings for now). - How a Writer works & how to write one @@ -137,9 +153,6 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- @@@ Add references to the user docs: bugs to the SF bug tracker, - questions to the mailing lists. - Specification ------------- @@ -341,12 +354,35 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. -- Decide whether or not to implement Simon Budig's "inline external - targets" syntax idea, and if so, how: +- @@@ Decide whether or not to implement Simon Budig's "inline + external targets" syntax idea, and if so, how? + + - As a regular directive affecting its indented text block:: + + .. inline-urls:: + + This is an anonymous `reference `__ of one word ("reference"). Here is a + `phrase reference `__. + + - As a pragma directive affecting the entire document (from that + point on). Perhaps a variation on the regular directive:: + + .. inline-urls:: :pragma: + + Ordinary paragraphs ... + + This is an anonymous `reference `__ of one word ("reference"). Here is a + `phrase reference `__. + + Perhaps "``:global:``" instead of "``:pragma:``"? This pattern + could be useful for other pragma directives: local-scope unless + explicitly specified as global/pragma. - - regular directive affecting its indented text block - - pragma directive affecting the entire document - - or a full-blown addition to the spec & parser + - Or as a full-blown addition to the spec & parser. - Add support for pragma (syntax-altering) directives. @@ -369,8 +405,8 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`parts.sectnum` (section numbering; add support to .contents; - could be cmdline option also) + - _`parts.sectnum` (automatic section numbering; add support to + the "contents" directive; could be cmdline option also) - _`misc.raw` diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 7f3038116..4f6ce541b 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -288,24 +288,24 @@ Responsibilities: Examples of input sources: - A single file on disk or a stream (implemented as - ``docutils.io.FileIO``). + ``docutils.io.FileInput``). -- Multiple files on disk (``MultiFileIO``?). +- Multiple files on disk (``MultiFileInput``?). - Python source files: modules and packages. - Python strings, as received from a client application - (implemented as ``docutils.io.StringIO``). + (implemented as ``docutils.io.StringInput``). Examples of output destinations: - A single file on disk or a stream (implemented as - ``docutils.io.FileIO``). + ``docutils.io.FileOutput``). - A tree of directories and files on disk. - A Python string, returned to a client application (implemented as - ``docutils.io.StringIO``). + ``docutils.io.StringOutput``). - A single tree-shaped data structure in memory. -- cgit v1.2.1 From 5bce8db5f80f9e1a03724ee137fb0adf578bc488 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 10 Aug 2002 04:29:04 +0000 Subject: Changed the focus. It's about DTD elements: structural relationships, semantics, and external (public) attributes. Not about the element class library; moved some implementation-specific stuff into ``docutils.nodes`` docstrings. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@494 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 237 +++++++++++++++++++++++---------------------------- 1 file changed, 108 insertions(+), 129 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index d138a8b2c..ce4f951db 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -6,14 +6,35 @@ :Revision: $Revision$ :Date: $Date$ -This document describes the internal data structure representing -document trees in Docutils. The data structure is defined by the -hierarchy of classes in the ``docutils.nodes`` module. It is also -formally described by the `Docutils Generic DTD`_ XML document type -definition, docutils.dtd_, which is the definitive source for element -hierarchy details. - -Below is a simplified diagram of the hierarchy of element types in the +This document describes the XML data structure of Docutils documents, +the relationships and semantics of elements. The Docutils document +structure is formally defined by the `Docutils Generic DTD`_ XML +document type definition, docutils.dtd_, which is the definitive +source for details of element structural relationships. + +The data structure is implemented by the class library in the +``docutils.nodes`` module. This document does not discuss +implementation details; they can be found in documentation for the +``docutils.nodes`` module (docstrings). + +The reader is assumed to have some familiarity with XML or SGML, and +an understanding the data structure meaning of "tree". For a list of +introductory articles, see `Introducing the Extensible Markup Language +(XML)`_. + +.. _Docutils Generic DTD: +.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _Introducing the Extensible Markup Language (XML): + http://xml.coverpages.org/xmlIntro.html + +.. contents:: + + +------------------- + Element Hierarchy +------------------- + +Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Text in square brackets are notes. Element types in parentheses indicate recursive or @@ -36,94 +57,97 @@ contain further body elements, etc. :: | markup) | +---------+ +The Docutils document model uses a simple, recursive model for section +structure. A document_ node may contain body elements and section_ +elements. Sections in turn may contain body elements and sections. +The level (depth) of a section element is determined from its physical +nesting level; unlike other document models (``

`` in HTML_, +```` in DocBook_, ```` in XMLSpec_) the level is not +incorporated into the element name. -------------------- - Element Hierarchy -------------------- +The Docutils document model uses strict element content models. Every +element has a unique structure and semantics, but elements may be +classified into general categories: -A class hierarchy has been implemented in nodes.py. The position of -each node (the level at which it can occur) is significant and is -represented by abstract base classes (Root, Structural, Body, Inline, -etc.). Certain transformations will be easier because we can use -``isinstance(node, base_class)`` to determine the position of the node -in the hierarchy. +* _`Structural elements` (document_, section_, and topic_) may only + contain child elements; they do not directly contain text data. + Child elements of structural elements may be body elements or other + structural elements. Structural elements can only be child elements + of other structural elements. -The elements making up Docutils document trees can be categorized into -the following groups: +* _`Body elements` are contained within structural elements and + compound body elements. There are two subcategories of body + elements: -- _`Root element`: document_ + - _`Compound body elements` (like table_ and bullet_list_) contain + local substructure and further body elements. They do not + directly contain text data. -- _`Title elements`: title_, subtitle_ + - _`Simple body elements` (like paragraph_ and literal_block) + directly contain text data, and may also contain inline elements. + Some simple body elements have a "mixed content model". -- _`Bibliographic elements`: docinfo_, author_, authors_, - organization_, contact_, version_, revision_, status_, date_, - copyright_ +* _`Inline elements` (like emphasis_ and reference_) directly contain + text data, and may also contain inline elements. Inline elements + are contained within simple body elements. Inline elements have a + "mixed content model". -- _`Structural elements`: document_, section_, topic_, transition_ +Only elements which are meant to directly contain text data have a +mixed content model, where text data and elements may be intermixed. +This is unlike the HTML_ document model, where paragraphs and text +data may occur at the same level. -- _`Body elements`: +.. _HTML: http://www.w3.org/MarkUp/ +.. _DocBook: http://docbook.org/tdg/en/html/docbook.html +.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm - - _`General body elements`: paragraph_, literal_block_, - block_quote_, doctest_block_, table_, figure_, image_, footnote_ - - _`Lists`: bullet_list_, enumerated_list_, definition_list_, - field_list_, option_list_ - - - _`Admonitions`: note_, tip_, warning_, error_, caution_, danger_, - important_ +------------------- + Element Reference +------------------- - - _`Special body elements`: target_, substitution_definition_, - comment_, system_warning_ +Each element in the document tree model is described in its own +section below. Each section contains the following subsections: -- _`Inline elements`: emphasis_, strong_, interpreted_, literal_, - reference_, target_, footnote_reference_, substitution_reference_, - image_, problematic_ +* Description: The semantics of the element. + - Parents: A list of elements which may contain the element. -``Node`` -======== + - Children: A list of elements which may occur within the element. + - Analogies: Describes analogous elements in well-known document + models such as HTML_ or DocBook_. Lists similarities and + differences. -``Text`` -======== + - Processing Expectations: Lists formatting or rendering + expectations for the element. +* Content Model: the content model of the element from the `Docutils + DTD`_. -``Element`` -=========== + - Attributes: Describes the possible values and semantics of each + attribute. Common attributes are described via references. + - Parameter Entities: Lists the parameter entities in which the + element described appears. -``TextElement`` -=============== +* Example: Where possible, a reStructuredText example is shown along + with a fragment of the document tree resulting from parsing. -------------------- - Element Reference -------------------- - ``document`` ============ -description -contents +The ``document`` element is the root (topmost) element of the Docutils +document tree. ``document`` is the direct or indirect ancestor of +every other element in the tree. -External attributes -------------------- -`Common external attributes`_. +contents +Attributes +---------- -Internal attributes -------------------- -- `Common internal attributes`_. -- ``explicittargets`` -- ``implicittargets`` -- ``externaltargets`` -- ``indirecttargets`` -- ``refnames`` -- ``anonymoustargets`` -- ``anonymousrefs`` -- ``autofootnotes`` -- ``autofootnoterefs`` -- ``reporter`` +`Common external attributes`_. --------------------- @@ -188,13 +212,6 @@ The ``source`` attribute The ``xml:space`` attribute -Internal Attributes -=================== - -All element objects share the following _`common internal attributes`: -rawsource_, children_, attributes_, tagname_. - - ------------------------ DTD Parameter Entities ------------------------ @@ -234,40 +251,6 @@ The ``%text.model;`` parameter entity Appendix: Miscellaneous Topics -------------------------------- -Hyperlink Bookkeeping -===================== - -``document.nameids`` maps names to IDs, while ``document.nametypes`` -maps names to booleans representing hyperlink type (True==explicit, -False==implicit). The ``document.set_name_id_map()`` method updates -the mappings. - -The following state transition table shows how ``nameids`` ("ids") and -``nametypes`` ("types") change with new input (a call to -``document.set_name_id_map()``), and what actions are performed: - -==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes ------------ -------- ----------------- ----------- ----- -ids types new type sys.msg. dupname ids types -==== ===== ======== ======== ======= ==== ===== ===== --- -- explicit -- -- new True --- -- implicit -- -- new False -None False explicit -- -- new True -old False explicit implicit old new True -None True explicit explicit new None True -old True explicit explicit new,old None True [#]_ -None False implicit implicit new None False -old False implicit implicit new,old None False -None True implicit implicit new None True -old True implicit implicit new old True -==== ===== ======== ======== ======= ==== ===== ===== - -.. [#] Do not clear the name->id map or invalidate the old target if - both old and new targets are external and refer to identical URIs. - The new target is invalidated regardless. - - Representation of Horizontal Rules ================================== @@ -278,11 +261,11 @@ the implementation of the document tree. Given this source:: Document ======== - Paragraph + Paragraph 1 -------- - Paragraph + Paragraph 2 The horizontal rule indicates a "transition" (in prose terms) or the start of a new "division". Before implementation, the parsed document @@ -293,13 +276,12 @@ tree would be:: Document <paragraph> - Paragraph + Paragraph 1 -------- <--- error here <paragraph> - Paragraph + Paragraph 2 -There are several possibilities for the implementation. Solution 3 -was chosen. +There are several possibilities for the implementation: 1. Implement horizontal rules as "divisions" or segments. A "division" is a title-less, non-hierarchical section. The first @@ -310,10 +292,10 @@ was chosen. <title> Document <paragraph> - Paragraph + Paragraph 1 <division> <paragraph> - Paragraph + Paragraph 2 But the two paragraphs are really at the same level; they shouldn't appear to be at different levels. There's really an invisible @@ -329,18 +311,18 @@ was chosen. Document <division> <paragraph> - Paragraph + Paragraph 1 <division> <paragraph> - Paragraph + Paragraph 2 With this change, documents and sections will directly contain divisions and sections, but not body elements. Only divisions will directly contain body elements. Even without a horizontal rule anywhere, the body elements of a document or section would be contained within a division element. This makes the document tree - deeper. This is similar to the way HTML treats document contents: - grouped within a <BODY> element. + deeper. This is similar to the way HTML_ treats document contents: + grouped within a ``<body>`` element. 3. Implement them as "transitions", empty elements:: @@ -349,23 +331,20 @@ was chosen. <title> Document <paragraph> - Paragraph + Paragraph 1 <transition> <paragraph> - Paragraph + Paragraph 2 A transition would be a "point element", not containing anything, only identifying a point within the document structure. This keeps the document tree flatter, but the idea of a "point element" like "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. - - This solution has been chosen for incorporation into the document - tree. + the space between two divisions. However, transitions are a + practical solution. +Solution 3 was chosen for incorporation into the document tree model. -.. _Docutils Generic DTD: -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd .. _reStructuredText: http://docutils.sourceforge.net/spec/rst/reStructuredText.html -- cgit v1.2.1 From 917d3af9d29ddb8b0bf284ccc1cb30e1b17052b1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 10 Aug 2002 04:30:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@495 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 71 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b2ae4584f..79356e9e4 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -60,10 +60,17 @@ Bugs 1. This is the heading of section one ===================================== - The only problem is, what about this? :: + What about this? :: A. Einstein was a really smart dude. + More text. + + It's a list item followed by a paragraph. Just document it as a + corner case and require escaping if it's not a list item. E.g.:: + + \A. Einstein was a really smart dude. + This should definitely be a list:: A. Einstein was a really smart dude. @@ -76,10 +83,10 @@ Bugs C. Chemist. They all worked in Princeton, NJ. - Time to put more smarts into the list item recognition code, or - just document it as a corner case and require escapes? E.g.:: - - \A. Einstein was a really smart dude. + The first two lines indicate a list. The third item, "C.", should + be interpreted as a paragraph because of the fourth line. An + "Enumerated list ends without a blank line; unexpected unindent at + line 3" warning shall be generated. (Bug reports by Jeremy Hylton and Dmitry Jemerov.) @@ -93,11 +100,8 @@ General - Implementation docs. - - spec/doctree.txt: Doctree element (DTD element) semantics: - - - External (public) attributes (node.attributes). - - Internal attributes (node.*). (?) - - Linking mechanism. (?) + - spec/doctree.txt: DTD element structural relationships, + semantics, and external (public) attributes (node.attributes). Should this document be about the code (implementation details), or about the DTD (document tree elements)? I'm having trouble @@ -161,8 +165,7 @@ Specification - Fill in the blanks in API details. - - Specify the nodes.py internal data structure implementation. - Or link to doctree.txt? + - 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 @@ -171,9 +174,6 @@ Specification - Rework PEP 257, separating style from spec from tools, wrt Docutils? See Doc-SIG from 2001-06-19/20. -- Once doctree.txt is fleshed out, how about breaking (most of) it up - and putting it into nodes.py as docstrings? - PySource Reader --------------- @@ -369,7 +369,7 @@ __ rst/alternatives.html#or-not-to-do - As a pragma directive affecting the entire document (from that point on). Perhaps a variation on the regular directive:: - .. inline-urls:: :pragma: + .. inline-urls:: :global: Ordinary paragraphs ... @@ -378,7 +378,7 @@ __ rst/alternatives.html#or-not-to-do `phrase reference <http://www.example.org /phrase_reference/>`__. - Perhaps "``:global:``" instead of "``:pragma:``"? This pattern + Perhaps "``:pragma:``" instead of "``:global:``"? This pattern could be useful for other pragma directives: local-scope unless explicitly specified as global/pragma. @@ -386,6 +386,10 @@ __ rst/alternatives.html#or-not-to-do - Add support for pragma (syntax-altering) directives. +- 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."). + Directives `````````` @@ -396,7 +400,10 @@ Directives - Add more attributes to the image directive: align, border? -- Implement directives: +- 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?) @@ -405,8 +412,32 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`parts.sectnum` (automatic section numbering; add support to - the "contents" directive; could be cmdline option also) + - _`parts.sectnum`: Automatic section numbering. Could be a + command-line option also/instead. + + Something like this:: + + .. sectnum:: + + Section One + =========== + + Section Two + =========== + + Subsection One + -------------- + + When processed, the numbers "1", "2", and "2.1" would be prefixed + to the titles automatically. The directive name could be + "sectnum" or "section-numbers" or "section-numbering", perhaps + with a ":global:" attribute. A ":depth:" attribute would also be + useful (analogous to that of the "contents" directive). Perhaps + some kind of styling attribute as well? + + Add support to the "contents" directive. Instead of bullet lists, + the table of contents could be implemented with enumerated lists. + Nested simple enumerators or compound enumerators ("2.1")? - _`misc.raw` -- cgit v1.2.1 From 6f6ef2d4327f050afd2c10d401bcd249a39865ec Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 10 Aug 2002 04:50:25 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@496 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 79356e9e4..e624b72a3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -388,7 +388,7 @@ __ rst/alternatives.html#or-not-to-do - 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."). + "``Conclusion_``" (i.e., without the "3."). Directives -- cgit v1.2.1 From 40e46fa5d8067ac0a5b34fcf3e5c6b15f130cec0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 12 Aug 2002 01:55:51 +0000 Subject: updated & rearranged git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@501 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 60 +++++++++++++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 33 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e624b72a3..125a2d062 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -94,31 +94,6 @@ Bugs General ------- -- Document! - - - Internal module documentation (docstrings). - - - Implementation docs. - - - spec/doctree.txt: DTD element structural relationships, - semantics, and external (public) attributes (node.attributes). - - Should this document be about the code (implementation details), - or about the DTD (document tree elements)? I'm having trouble - writing it because it's a bit schizo; doesn't know what it is. - Perhaps it should simply document the DTD elements, their - semantics, and only refer to the implementation. Descriptions - of the classes, their methods, and internal attributes belong in - the implementation docs (docstrings for now). - - - How a Writer works & how to write one - - - Howto: Transforms - - - Howto: Directives - - - User docs. - - Refactor - Rename methods & variables according to the `coding conventions`_ @@ -146,20 +121,39 @@ General - Need a Unicode to HTML entities codec for HTML writer? -- Fix tests to run standalone. I.e., allow:: +- Perhaps the ``Component.supports`` method should deal with + individual features ("meta" etc.) instead of formats ("html" etc.)? + - cd test/test_rst - test_inline_markup.py +Documentation +------------- - Raises an exception with path processing on GNU/Linux (but only - sometimes???). +- User docs. -- Perhaps the ``Component.supports`` method should deal with - individual features ("meta" etc.) instead of formats ("html" etc.)? + +Implementation Docs +``````````````````` + +- Internal module documentation (docstrings). + +- spec/doctree.txt: DTD element structural relationships, semantics, + and attributes. + +- How a Writer works & how to write one + +- Howto: Transforms + +- Howto: Directives + +- Document the ``pending`` elements and when they're triggered ("first + reader", "last writer", etc.). + +- Document the transforms (perhaps in docstrings?): how they're used, + what they do. Specification -------------- +````````````` - Complete PEP 258 Docutils Design Specification. -- cgit v1.2.1 From 8a3ace64df105cd5a57919abaa5132579fa2cc42 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 12 Aug 2002 04:54:27 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@502 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 125a2d062..28fec3a9d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -124,6 +124,9 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? +- Should transforms have a priority system? Is the "first reader" ... + "last writer" system adequate for pending transforms? + Documentation ------------- @@ -149,7 +152,7 @@ Implementation Docs reader", "last writer", etc.). - Document the transforms (perhaps in docstrings?): how they're used, - what they do. + what they do, dependencies & order considerations. Specification -- cgit v1.2.1 From ec966350bdbbc7b83741dbe91f6c9bf93443ff7d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Aug 2002 00:59:29 +0000 Subject: - Added "generated" inline element. - Added "auto" attribute to "title". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@509 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5d6ec6ad6..312c74895 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -87,7 +87,7 @@ resolve to either an internal or external reference. <!ENTITY % anonymous.att " anonymous %yesorno; #IMPLIED "> -<!-- Auto-numbered footnote. --> +<!-- Auto-numbered footnote or title. --> <!ENTITY % auto.att " auto %yesorno; #IMPLIED "> @@ -127,7 +127,8 @@ resolve to either an internal or external reference. <!ENTITY % inline.elements " emphasis | strong | interpreted | literal | reference | footnote_reference | citation_reference - | substitution_reference | target | image | problematic | raw + | substitution_reference | problematic | generated + | target | image | raw %additional.inline.elements; "> <!-- Element Content Models @@ -188,7 +189,8 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT title %text.model;> <!ATTLIST title %basic.atts; - %refid.att;> + %refid.att; + %auto.att;> <!ELEMENT subtitle %text.model;> <!ATTLIST subtitle %basic.atts;> @@ -523,6 +525,9 @@ following caveats: %basic.atts; %refid.att;> +<!ELEMENT generated (%text.model;)> +<!ATTLIST generated %basic.atts;> + <!-- Local Variables: -- cgit v1.2.1 From bf0e6532758252fbf6b22c80a1f83d702463f712 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Aug 2002 01:00:28 +0000 Subject: Added the "sectnum" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@510 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 47 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 205d3843a..5e1f07314 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -9,6 +9,14 @@ This document describes the directives implemented in the reference reStructuredText parser. +Directives have the following syntax:: + + +-------+--------------------------+ + | ".. " | directive type "::" data | + +-------+ directive block | + | | + +--------------------------+ + .. contents:: @@ -235,7 +243,7 @@ The following attributes are recognized: ``depth`` : integer The number of section levels that are collected in the table of - contents. + contents. The default is unlimited depth. ``local`` : empty Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no @@ -245,17 +253,36 @@ The following attributes are recognized: entries, the table of contents itself, or generate no backlinks. -Footnotes -========= +Automatic Section Numbering +=========================== -**NOT IMPLEMENTED YET** +DTD elements: pending, generated. -DTD elements: pending, topic. +Directive block: directive data and following indented lines (up to +the first blank line) are interpreted as optional attributes. + +The "sectnum" (or "section-autonumbering") directive automatically +numbers sections and subsections in a document. Section numbers of +the "multiple enumeration" form, where each level has a number, +separated by periods. For example, the title of section 1, subsection +2, subsubsection 3 would have "1.2.3" prefixed. + +The "sectnum" directive does its work in two passes: initial parse and +transform. During the initial parse, a "pending" element is generated +which acts as a placeholder, storing any attributes internally. At a +later stage in the processing, the "pending" element triggers a +transform, which adds section numbers to titles. Section numbers are +enclosed in a "generated" element, and titles have their "auto" +attribute set to "1". -@@@ +The following attributes are recognized: +``depth`` : integer + The number of section levels that are numbered by this directive. + The default is unlimited depth. -Citations + +Footnotes ========= **NOT IMPLEMENTED YET** @@ -265,12 +292,12 @@ DTD elements: pending, topic. @@@ -Topic -===== +Citations +========= **NOT IMPLEMENTED YET** -DTD element: topic. +DTD elements: pending, topic. @@@ -- cgit v1.2.1 From 07dc5b490583921a0cc62654ed4a0e37c1bea9d9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Aug 2002 01:06:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@514 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 68 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 28 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 28fec3a9d..a13b505d5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -395,7 +395,44 @@ Directives - Use the language module for directive attribute names? -- Add more attributes to the image directive: align, border? +- Implement attributes on existing directives: + + - _`images.image`: "align", "border"? + + - _`parts.sectnum`: "start", "local"? + + A "local" attribute 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" attribute 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. - Implement directives. Each of the list items below begins with an identifier of the form, "module_name.directive_function_name". The @@ -409,33 +446,6 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`parts.sectnum`: Automatic section numbering. Could be a - command-line option also/instead. - - Something like this:: - - .. sectnum:: - - Section One - =========== - - Section Two - =========== - - Subsection One - -------------- - - When processed, the numbers "1", "2", and "2.1" would be prefixed - to the titles automatically. The directive name could be - "sectnum" or "section-numbers" or "section-numbering", perhaps - with a ":global:" attribute. A ":depth:" attribute would also be - useful (analogous to that of the "contents" directive). Perhaps - some kind of styling attribute as well? - - Add support to the "contents" directive. Instead of bullet lists, - the table of contents could be implemented with enumerated lists. - Nested simple enumerators or compound enumerators ("2.1")? - - _`misc.raw` - _`misc.include`: ``#include`` one file in another. But how to @@ -780,6 +790,8 @@ Front-End Tools - Disable common options that don't apply? +- Implement the "sectnum" directive as a command-line option also? + Project Policies ================ -- cgit v1.2.1 From 7b9bea34a8017efaa65dce4c7216cb9a567f7c8a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 14 Aug 2002 02:44:41 +0000 Subject: minor edits git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@522 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0256.txt | 9 +++------ docs/peps/pep-0258.txt | 9 +++------ 2 files changed, 6 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index 017ba3b01..e6715eb14 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -236,16 +236,13 @@ References and Footnotes ======================== .. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger - - http://www.python.org/peps/pep-0287.html + (http://www.python.org/peps/pep-0287.html) .. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum - - http://www.python.org/peps/pep-0257.html + (http://www.python.org/peps/pep-0257.html) .. [#PEP-258] PEP 258, Docutils Design Specification, Goodger - - http://www.python.org/peps/pep-0258.html + (http://www.python.org/peps/pep-0258.html) .. _Literate Programming: http://www.literateprogramming.com/ diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 4f6ce541b..9b03c9524 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -866,16 +866,13 @@ stylist code will lower the barrier considerably. ========================== .. [#PEP-256] PEP 256, Docstring Processing System Framework, Goodger - - http://www.python.org/peps/pep-0256.html + (http://www.python.org/peps/pep-0256.html) .. [#PEP-224] PEP 224, Attribute Docstrings, Lemburg - - http://www.python.org/peps/pep-0224.html + (http://www.python.org/peps/pep-0224.html) .. [#PEP-216] PEP 216, Docstring Format, Zadka - - http://www.python.org/peps/pep-0216.html + (http://www.python.org/peps/pep-0216.html) .. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd -- cgit v1.2.1 From 096e020774b4f3681762f86fb2baeff90957feb5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 14 Aug 2002 02:45:02 +0000 Subject: Added the "target-notes" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@523 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5e1f07314..f5fa956ce 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -282,6 +282,24 @@ The following attributes are recognized: The default is unlimited depth. +------------ + References +------------ + +Target Footnotes +================ + +DTD elements: pending, footnote, footnote_reference. + +Directive block: unused; directive data must be empty. + +The "target-notes" directive creates a footnote for each external +target in the text, and corresponding footnote references after each +reference. For every explicit target (of the form, ``.. _target name: +URL``) in the text, a footnote will be generated containing the +visible URL as content. + + Footnotes ========= -- cgit v1.2.1 From 16a36a0e2ef919331cabb32a76f987741eed1909 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 14 Aug 2002 02:47:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@525 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a13b505d5..a8e6d1644 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -6,11 +6,11 @@ :Date: $Date$ :Revision: $Revision$ - .. _Docutils: http://docutils.sourceforge.net/ .. contents:: + To Do ===== @@ -124,8 +124,14 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- Should transforms have a priority system? Is the "first reader" ... - "last writer" system adequate for pending transforms? +- Transforms need a priority system. The "first reader" ... "last + writer" system is no longer adequate for pending transforms. For + example, the ``references.TargetNotes`` transform needs to run after + ``references.Hyperlinks.resolve_indirect()`` but before + ``references.Footnotes``. + + - Break up ``references.Hyperlinks`` into multiple smaller + transforms. Documentation @@ -148,8 +154,8 @@ Implementation Docs - Howto: Directives -- Document the ``pending`` elements and when they're triggered ("first - reader", "last writer", etc.). +- Document the ``pending`` elements, how they're generated and when + they're triggered ("first reader", "last writer", etc.). - Document the transforms (perhaps in docstrings?): how they're used, what they do, dependencies & order considerations. -- cgit v1.2.1 From e171042f90e253b4884887ef04870c17116c74ba Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 Aug 2002 01:55:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@532 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a8e6d1644..732dbec0b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -124,14 +124,14 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- Transforms need a priority system. The "first reader" ... "last - writer" system is no longer adequate for pending transforms. For - example, the ``references.TargetNotes`` transform needs to run after - ``references.Hyperlinks.resolve_indirect()`` but before +- @@@ Transforms need a priority system. The "first reader" ... + "last writer" system is no longer adequate for pending transforms. + For example, the ``references.TargetNotes`` transform needs to run + after ``references.Hyperlinks.resolve_indirect()`` but before ``references.Footnotes``. - - Break up ``references.Hyperlinks`` into multiple smaller - transforms. +- @@@ Break up ``references.Hyperlinks`` into multiple smaller + transforms. Documentation -- cgit v1.2.1 From 0e0945034dac85d840bcf15384b533a41ece4d49 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:32:36 +0000 Subject: Added the "line-block" and "parsed-literal" directives. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@537 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f5fa956ce..dbbec83fa 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -193,6 +193,53 @@ example:: interpreted as body elements. +Line Block +========== + +DTD element: line_block. + +Directive block: directive data and all following indented text become +the body of the line block. + +The "line-block" directive constructs a paragraph-like element where +leading whitespace and linebreaks are significant and inline markup is +supported. This is useful for address blocks and verse (poetry, song +lyrics). For example:: + + "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by + Ewan McTeagle (for Lassie O'Shea): + + .. line-block:: + + Lend us a couple of bob till Thursday. + I'm absolutely skint. + But I'm expecting a postal order and I can pay you back + as soon as it comes. + Love, Ewan. + + +Parsed Literal Block +==================== + +DTD element: literal_block. + +Directive block: directive data and all following indented text become +the body of the literal block. + +Unlike an ordinary literal block, the "parsed-literal" directive +constructs a literal block where the text is parsed for inline markup. +This is useful for adding hyperlinks to code examples. For example, +all the element names in this content model are links:: + + .. parsed-literal:: + + ((title_, + subtitle_?)?, + docinfo_?, + decoration_?, + `%structure.model;`_) + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 6801360e316b2004d56599da78056b0e991b6fc6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:36:34 +0000 Subject: minor progress git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@540 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 98 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ce4f951db..16c4d6442 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -6,6 +6,8 @@ :Revision: $Revision$ :Date: $Date$ +.. contents:: :depth: 1 + This document describes the XML data structure of Docutils documents, the relationships and semantics of elements. The Docutils document structure is formally defined by the `Docutils Generic DTD`_ XML @@ -27,9 +29,6 @@ introductory articles, see `Introducing the Extensible Markup Language .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html -.. contents:: - - ------------------- Element Hierarchy ------------------- @@ -106,6 +105,10 @@ data may occur at the same level. Element Reference ------------------- +.. contents:: + :local: + :depth: 1 + Each element in the document tree model is described in its own section below. Each section contains the following subsections: @@ -138,77 +141,112 @@ section below. Each section contains the following subsections: ``document`` ============ +Description +----------- + The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of every other element in the tree. -contents + +Content Model +------------- + +.. parsed-literal:: + + ((title_, + subtitle_?)?, + docinfo_?, + decoration_?, + `%structure.model;`_) + Attributes ----------- +`````````` `Common external attributes`_. +Example +------- + + --------------------- Attribute Reference --------------------- -External Attributes -=================== +.. contents:: + :local: + :depth: 1 Through the `%basic.atts;`_ parameter entity, all elements share the following _`common external attributes`: id_, name_, dupname_, -source_. +source_, class_. ``anonymous`` -------------- +============= + The ``anonymous`` attribute ``auto`` --------- +======== + The ``auto`` attribute +``class`` +========= + +The ``class`` attribute + + ``dupname`` ------------ +=========== + The ``dupname`` attribute ``id`` ------- +====== + The ``id`` attribute ``name`` --------- +======== + The ``name`` attribute ``refid`` ---------- +========= + The ``refid`` attribute ``refname`` ------------ +=========== + The ``refname`` attribute ``refuri`` ----------- +========== + The ``refuri`` attribute ``source`` ----------- +========== + The ``source`` attribute ``xml:space`` -------------- +============= + The ``xml:space`` attribute @@ -216,40 +254,56 @@ The ``xml:space`` attribute DTD Parameter Entities ------------------------ +.. contents:: + :local: + :depth: 1 + + ``%basic.atts;`` ================ + The ``%basic.atts;`` parameter entity lists attributes common to all elements. See `Common Attributes`_. ``%body.elements;`` =================== + The ``%body.elements;`` parameter entity ``%inline.elements;`` -==================== +===================== + The ``%inline.elements;`` parameter entity ``%reference.atts;`` ==================== + The ``%reference.atts;`` parameter entity ``%structure.model;`` ===================== + The ``%structure.model;`` parameter entity ``%text.model;`` ================ + The ``%text.model;`` parameter entity --------------------------------- - Appendix: Miscellaneous Topics --------------------------------- +---------------------- + Miscellaneous Topics +---------------------- + +.. contents:: + :local: + :depth: 1 + Representation of Horizontal Rules ================================== -- cgit v1.2.1 From d5fa6b83feda02eef106ac0d7d3425cb1041932d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:38:41 +0000 Subject: Added "line_block" body element. Changed content models of "literal_block" and "doctest_block" to ``%text.model``. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@541 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 312c74895..5b7e8aac4 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -113,8 +113,8 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements - " paragraph | literal_block | block_quote | doctest_block | table - | figure | image | footnote | citation + " paragraph | literal_block | doctest_block | line_block | block_quote + | table | figure | image | footnote | citation | bullet_list | enumerated_list | definition_list | field_list | option_list | attention | caution | danger | error | hint | important | note @@ -354,15 +354,20 @@ either the string separating it from the `option` (typically either <!ELEMENT description (%body.elements;)+> <!ATTLIST description %basic.atts;> -<!ELEMENT literal_block (#PCDATA)> +<!ELEMENT literal_block %text.model;> <!ATTLIST literal_block %basic.atts; %fixedspace.att;> +<!ELEMENT line_block %text.model;> +<!ATTLIST line_block + %basic.atts; + %fixedspace.att;> + <!ELEMENT block_quote (%body.elements;)+> <!ATTLIST block_quote %basic.atts;> -<!ELEMENT doctest_block (#PCDATA)> +<!ELEMENT doctest_block %text.model;> <!ATTLIST doctest_block %basic.atts; %fixedspace.att;> -- cgit v1.2.1 From 91ae000132d385eda896d67cea537efe983f1962 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:39:36 +0000 Subject: Updated enumerated list description; added a discussion of the second-line validity checking. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@542 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index c94e03ffb..040393276 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -680,6 +680,26 @@ interpreted as a letter of the alphabet, not as a Roman numeral. Likewise, lists using letters of the alphabet may not begin with "I"/"i", since these are recognized as Roman numeral 1. +The second line of each enumerated list item is checked for validity. +This is to prevent ordinary paragraphs from being mistakenly +interpreted as list items, when they happen to begin with text +identical to enumerators. For example, this text is parsed as an +ordinary paragraph:: + + A. Einstein was a really + smart dude. + +However, ambiguity cannot be avoided if the paragraph consists of only +one line. This text is parsed as an enumerated list item:: + + A. Einstein was a really smart dude. + +If a single-line paragraph begins with text identical to an enumerator +("A.", "1.", "(b)", "I)", etc.), the first character will have to be +escaped in order to have the line parsed as an ordinary paragraph:: + + \A. Einstein was a really smart dude. + Nested enumerated lists must be created with indentation. For example:: -- cgit v1.2.1 From 84d492dd0ac01d6f187f7871670305f6ed5024e1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 00:45:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@545 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 207 +++++++++++++++++++++++------------------------------- 1 file changed, 86 insertions(+), 121 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 732dbec0b..30d9e6147 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -50,46 +50,6 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -- @@@ This shouldn't be recognized as a list item:: - - A. Einstein was a really - smart dude. - - Or this:: - - 1. This is the heading of section one - ===================================== - - What about this? :: - - A. Einstein was a really smart dude. - - More text. - - It's a list item followed by a paragraph. Just document it as a - corner case and require escaping if it's not a list item. E.g.:: - - \A. Einstein was a really smart dude. - - This should definitely be a list:: - - A. Einstein was a really smart dude. - B. So was Carl Sagan. - - But what about this? Accidents can happen:: - - A. Einstein was a great influence on - B. Physicist, who was a colleague of - C. Chemist. They all worked in - Princeton, NJ. - - The first two lines indicate a list. The third item, "C.", should - be interpreted as a paragraph because of the fourth line. An - "Enumerated list ends without a blank line; unexpected unindent at - line 3" warning shall be generated. - - (Bug reports by Jeremy Hylton and Dmitry Jemerov.) - General ------- @@ -133,6 +93,10 @@ General - @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. +- Make it easier to say, "Here's a reStructuredText string; give me + HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to + ``core.publish_file()``? + Documentation ------------- @@ -393,6 +357,38 @@ __ rst/alternatives.html#or-not-to-do A section titled "3. Conclusion" could then be referred to by "``Conclusion_``" (i.e., without the "3."). +- Syntax for the "line-block" directive? How about a + literal-block-like prefix, perhaps "``;;``"? (It is, after all, a + *semi-literal* literal block, no?) Example:: + + Take it away, Eric the Orchestra Leader! ;; + + A one, two, a one two three four + + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? + + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + + Singing... + + Another idea: in an ordinary paragraph, if the first line ends with + a backslash (escaping the newline), interpret the entire paragraph + as a verse block? This ties in to the `character processing`_ idea, + above. For example:: + + Add just one backslash\ + And this paragraph becomes + An awful haiku + + (And arguably invalid, since in Japanese the word "haiku" contains + three syllables.) + Directives `````````` @@ -523,77 +519,6 @@ Directives lists). Without special syntax, this directive becomes low priority. - - @@ _`body.verse`: Paragraphs with linebreaks preserved, *and* - inline markup support too. Use cases: verse (poetry, song lyrics, - etc.), address blocks. A directive would be easy; what about a - literal-block-like prefix, perhaps "``;;``"? (It is, after all, a - *semi-literal* literal block, no?) Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - New elements would be required. Perhaps:: - - <!ELEMENT verse (stanza | verse)+> - <!ELEMENT stanza (line+)> - <!ELEMENT line %text.model;> - - We could get away without "line" elements, treating line breaks - within "stanzas" as significant. But explicit is perhaps better - than implicit. - - Within a "verse" element, should any other constructs be allowed? - Should lists be recognized? No; verse blocks are variations on - paragraphs, and need not contain arbitrary nested body elements. - However, the equivalent of block quotes (i.e., further indented - blocks) would be nested verse elements. These could be "chorus" - blocks. - - Perhaps individually indented "continuation lines" should also be - recognized (maybe with a "continuation" attribute on the "line" - element, or significant whitespace in a single "line"):: - - "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by - Ewan McTeagle (for Lassie O'Shea): ;; - - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. - - Another idea for syntax: in an ordinary paragraph, if the first - line ends with a backslash (escaping the newline), interpret the - entire paragraph as a verse block? This ties in to the `character - processing`_ idea, above. For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (And arguably invalid, since in Japanese the word "haiku" contains - three syllables.) - - Directive/construct name alternatives: verse, address block, - address, line block, lines, multi-line, free-form, keep lines, - no-wrap, haiku, keep breaks, line breaks, obey lines, line-wise, - text block, text art, text, line text, line list. Current - favorites: "line_block" for element name, "lines" for directive - name. - - _`body.example`: Examples; suggested by Simon Hefti. Semantics as per Docbook's "example"; admonition-style, numbered, reference, with a caption/title. @@ -601,7 +526,7 @@ Directives - _`body.index`: Index targets. Were I writing a book with an index, I guess I'd need two - different kinds of index tags: inline/implicit and + different kinds of index targets: inline/implicit and out-of-line/explicit. For example:: In this `paragraph`:index:, several words are being @@ -616,20 +541,23 @@ Directives The words "paragraph", "marked", and "index" would become index entries pointing at the words in the first paragraph. The index - entries appear verbatim in the text. (Don't worry about the ugly - ":index:" part; if indexing is the only 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:: + entry words appear verbatim in the text. (Don't worry about the + ugly ":index:" part; if indexing is the only 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 entry, like:: + 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 @@ -643,8 +571,8 @@ Directives simple statements ......... 58 compound statements ....... 60 - Inline multi-level index targets could be done too. Something - like:: + Inline multi-level index targets could be done too. Perhaps + something like:: When dealing with `expression statements <statement syntax:>`, we must remember ... @@ -735,6 +663,19 @@ 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. + + Others `````` @@ -798,6 +739,30 @@ Front-End Tools - Implement the "sectnum" directive as a command-line option also? +- Add a "--relative-paths" option? + + All references to files (stylesheet, source file [in footer], PEP + template) are interpreted relative to the current working + directory, and adjusted relative to the destination directory. + For example:: + + cd /work + html.py -s --stylesheet=default.css /src/test.txt /dst/text.html + + This will interpret the stylesheet as "work/default.css", so the + stylesheet link in the HTML (which is in the /dst dir) will read + "../work/default.css", and the source link (-s option) will read + "../src/test.txt". + + Perhaps the current behavior should be optional + ("--relative-paths" or something). The default should probably be + not to process paths at all, just use them verbatim. + +- ``options._destination`` shouldn't have to be set. It's currently + needed to calculate relative paths for the stylesheet link. But the + client shouldn't have to deal with it. It's a file-bias that needs + fixing. + Project Policies ================ -- cgit v1.2.1 From f43d79c1bf8d41dec1bb40b0a609ed2c42a104e8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Aug 2002 01:45:04 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@546 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 30d9e6147..6eadeac0a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -741,22 +741,21 @@ Front-End Tools - Add a "--relative-paths" option? - All references to files (stylesheet, source file [in footer], PEP - template) are interpreted relative to the current working - directory, and adjusted relative to the destination directory. - For example:: - - cd /work - html.py -s --stylesheet=default.css /src/test.txt /dst/text.html - - This will interpret the stylesheet as "work/default.css", so the - stylesheet link in the HTML (which is in the /dst dir) will read - "../work/default.css", and the source link (-s option) will read - "../src/test.txt". - - Perhaps the current behavior should be optional - ("--relative-paths" or something). The default should probably be - not to process paths at all, just use them verbatim. + All references to files (stylesheet, source file [in footer], PEP + template) are interpreted relative to the current working directory, + and adjusted relative to the destination directory. For example:: + + cd /work + html.py -s --stylesheet=default.css /src/test.txt /dst/text.html + + This will interpret the stylesheet as "work/default.css", so the + stylesheet link in the HTML (which is in the /dst dir) will read + "../work/default.css", and the source link (-s option) will read + "../src/test.txt". + + Perhaps the current behavior should be optional ("--relative-paths" + or something). The default should probably be not to process paths + at all, just use them verbatim. - ``options._destination`` shouldn't have to be set. It's currently needed to calculate relative paths for the stylesheet link. But the @@ -850,8 +849,9 @@ 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 SourceForge trackers, mailing lists, or -private email) are assumed to be in the public domain as well. +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: -- cgit v1.2.1 From 3428a179892ef8343a8ec642c43cca59b43cb20a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:25:36 +0000 Subject: Lots of progress. Wrote descriptions of all common attributes and parameter entities. Filled in introductory material. Started on element descriptions (3 down, 80 to go). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@550 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 1330 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 1209 insertions(+), 121 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 16c4d6442..bcf983971 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1,6 +1,10 @@ ============================ The Docutils Document Tree ============================ + +A Guide to the Docutils DTD +*************************** + :Author: David Goodger :Contact: goodger@users.sourceforge.net :Revision: $Revision$ @@ -8,35 +12,51 @@ .. contents:: :depth: 1 -This document describes the XML data structure of Docutils documents, +This document describes the XML data structure of Docutils_ documents, the relationships and semantics of elements. The Docutils document structure is formally defined by the `Docutils Generic DTD`_ XML document type definition, docutils.dtd_, which is the definitive source for details of element structural relationships. -The data structure is implemented by the class library in the -``docutils.nodes`` module. This document does not discuss -implementation details; they can be found in documentation for the -``docutils.nodes`` module (docstrings). +This document does not discuss implementation details. Those can be +found in internal documentation (docstrings) for the +``docutils.nodes`` module, where the document tree data structure is +implemented in a class library. The reader is assumed to have some familiarity with XML or SGML, and an understanding the data structure meaning of "tree". For a list of introductory articles, see `Introducing the Extensible Markup Language (XML)`_. +The reStructuredText_ markup is used for illustrative examples +throughout this document. For a gentle introduction, see `A +ReStructuredText Primer`_. For complete technical details, see the +`reStructuredText Markup Specification`_. + + +.. _Docutils: http://docutils.sourceforge.net/ .. _Docutils Generic DTD: +.. _Docutils DTD: .. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _A ReStructuredText Primer: + http://docutils.sourceforge.net/docs/rst/quickstart.html +.. _reStructuredText Markup Specification: + http://docutils.sourceforge.net/spec/rst/reStructuredText.html + ------------------- Element Hierarchy ------------------- +.. contents:: :local: + Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other -elements immediately below it in the diagram. Text in square brackets -are notes. Element types in parentheses indicate recursive or +elements immediately below it in the diagram. Notes are written in +square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc. :: @@ -66,35 +86,120 @@ incorporated into the element name. The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be -classified into general categories: +classified into general categories (below). Only elements which are +meant to directly contain text data have a mixed content model, where +text data and inline elements may be intermixed. This is unlike the +much looser HTML_ document model, where paragraphs and text data may +occur at the same level. + + +Structural Elements +=================== + +Structural elements may only contain child elements; they do not +directly contain text data. Structural elements may contain body +elements or further structural elements. Structural elements can only +be child elements of other structural elements. + +Category members: document_, section_, topic_ + + +Structural Subelements +---------------------- + +Structural subelements are child elements of structural elements, but +contain no further structure of their own (except for text and inline +elements). + +Category members: title_, subtitle_, transition_ + + +Bibliographic Elements +---------------------- + +The docinfo_ element is an optional child of document_. It groups +bibliographic elements together. + +Category members: docinfo_, author_, authors_, contact_, copyright_, +date_, organization_, revision_, status_, version_ + + +Decorative Elements +------------------- + +The decoration_ element is also an optional child of document_. It +groups together elements used to generate page headers and footers. + +Category members: decoration_, footer_, header_ + + +Body Elements +============= + +Body elements are contained within structural elements and compound +body elements. There are two subcategories of body elements: simple +and compound. + +Category members: attention_, block_quote_, bullet_list_, caution_, +citation_, comment_, danger_, definition_list_, doctest_block_, +enumerated_list_, error_, field_list_, figure_, footnote_, hint_, +image_, important_, line_block_, literal_block_, note_, option_list_, +paragraph_, pending_, raw_, substitution_definition_, +system_message_, table_, target_, tip_, warning_ + -* _`Structural elements` (document_, section_, and topic_) may only - contain child elements; they do not directly contain text data. - Child elements of structural elements may be body elements or other - structural elements. Structural elements can only be child elements - of other structural elements. +Simple Body Elements +-------------------- -* _`Body elements` are contained within structural elements and - compound body elements. There are two subcategories of body - elements: +Simple body elements directly are empty or contain text data. Those +that contain text data may also contain inline elements. Such +elements therefore have a "mixed content model". - - _`Compound body elements` (like table_ and bullet_list_) contain - local substructure and further body elements. They do not - directly contain text data. +Category members: comment_, doctest_block_, image_, line_block_, +literal_block_, paragraph_, pending_, raw_, substitution_definition_, +target_ - - _`Simple body elements` (like paragraph_ and literal_block) - directly contain text data, and may also contain inline elements. - Some simple body elements have a "mixed content model". -* _`Inline elements` (like emphasis_ and reference_) directly contain - text data, and may also contain inline elements. Inline elements - are contained within simple body elements. Inline elements have a - "mixed content model". +Compound Body Elements +---------------------- + +Compound body elements contain local substructure (component parts) +and further body elements. They do not directly contain text data. + +Category members: attention_, block_quote_, bullet_list_, caution_, +citation_, danger_, definition_list_, enumerated_list_, error_, +field_list_, figure_, footnote_, hint_, important_, note_, +option_list_, system_message_, table_, tip_, warning_ + + +Compound Body Subelements +````````````````````````` + +Compound body elements contain specific compound body subelements +(e.g. bullet_list_ contains list_item_). Subelements may themselves +be compound elements (containing further child elements, like field_) +or simple data elements (containing text data, like field_name_). +These subelements always occur within specific parent elements, never +at the body element level (just below sections, etc.). + +Category members: caption_, classifier_, colspec_, definition_, +definition_list_item_, description_, entry_, field_, field_argument_, +field_body_, field_name_, label_, legend_, list_item_, option_, +option_argument_, option_group_, option_list_item_, option_string_, +row_, tbody_, term_, tgroup_, thead + + +Inline Elements +=============== + +Inline elements directly contain text data, and may also contain +further inline elements. Inline elements are contained within simple +body elements. Most inline elements have a "mixed content model". + +Category members: citation_reference_, emphasis_, footnote_reference_, +generated_, image_, interpreted_, literal_, problematic_, reference_, +strong_, substitution_reference_, target_, raw_. -Only elements which are meant to directly contain text data have a -mixed content model, where text data and elements may be intermixed. -This is unlike the HTML_ document model, where paragraphs and text -data may occur at the same level. .. _HTML: http://www.w3.org/MarkUp/ .. _DocBook: http://docbook.org/tdg/en/html/docbook.html @@ -105,12 +210,12 @@ data may occur at the same level. Element Reference ------------------- -.. contents:: - :local: - :depth: 1 +.. contents:: :local: + :depth: 1 -Each element in the document tree model is described in its own -section below. Each section contains the following subsections: +Each element in the DTD (document type definition) is described in its +own section below. Each section contains the following subsections +and items: * Description: The semantics of the element. @@ -122,20 +227,184 @@ section below. Each section contains the following subsections: models such as HTML_ or DocBook_. Lists similarities and differences. - - Processing Expectations: Lists formatting or rendering - expectations for the element. + - Processing: Lists formatting or rendering recommendations for the + element. -* Content Model: the content model of the element from the `Docutils - DTD`_. +* Content Model: from the `Docutils DTD`_. - - Attributes: Describes the possible values and semantics of each - attribute. Common attributes are described via references. + - Attributes: Describes (or refers to descriptions of) the possible + values and semantics of each attribute. - - Parameter Entities: Lists the parameter entities in which the - element described appears. + - Parameter Entities: Lists the parameter entities which include the + element described. * Example: Where possible, a reStructuredText example is shown along - with a fragment of the document tree resulting from parsing. + with a fragment of the document tree resulting from parsing. + _`Pseudo-XML` is used for the results of parsing and processing. + Pseudo-XML is a representation of XML where nesting is indicated by + indentation and end-tags are not shown. Some of the precision of + real XML is traded for easier readability. For example, the + following are equivalent. XML:: + + <document> + <section id="a-title" name="a title"> + <title>A Title + A paragraph. +

+ + + Pseudo-XML:: + + +
+ + A Title + <paragraph> + A paragraph. + +-------------------- + +Many of the element reference sections below are marked "_`to be +completed`". Please help complete this document by contributing to +its writing. + + +``attention`` +============= + +`To be completed`_. + + +``author`` +========== + +`To be completed`_. + + +``authors`` +=========== + +`To be completed`_. + + +``block_quote`` +=============== + +`To be completed`_. + + +``bullet_list`` +=============== + +`To be completed`_. + + +``caption`` +=========== + +`To be completed`_. + + +``caution`` +=========== + +`To be completed`_. + + +``citation`` +============ + +`To be completed`_. + + +``citation_reference`` +====================== + +`To be completed`_. + + +``classifier`` +============== + +`To be completed`_. + + +``colspec`` +=========== + +`To be completed`_. + + +``comment`` +=========== + +`To be completed`_. + + +``contact`` +=========== + +`To be completed`_. + + +``copyright`` +============= + +`To be completed`_. + + +``danger`` +========== + +`To be completed`_. + + +``date`` +======== + +`To be completed`_. + + +``decoration`` +============== + +`To be completed`_. + + +``definition`` +============== + +`To be completed`_. + + +``definition_list`` +=================== + +`To be completed`_. + + +``definition_list_item`` +======================== + +`To be completed`_. + + +``description`` +=============== + +`To be completed`_. + + +``docinfo`` +=========== + +`To be completed`_. + + +``doctest_block`` +================= + +`To be completed`_. ``document`` @@ -144,9 +413,24 @@ section below. Each section contains the following subsections: Description ----------- +Element category: `structural elements`_. + The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of -every other element in the tree. +every other element in the tree. It encloses the entire document +tree. It is the starting point for a document. + +Parents + The ``document`` element has no parents. + +Children + ``document`` elements may contain the following elements: title_, + subtitle_, docinfo_, decoration_, topic_, transition_, section_, + and `body elements`_. + +Analogies + ``document`` is analogous to the HTML "html" element and several + DocBook elements such as "book". Content Model @@ -155,162 +439,968 @@ Content Model .. parsed-literal:: ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, + subtitle_?)?, + docinfo_?, + decoration_?, `%structure.model;`_) +Depending on the source of the data and the stage of processing, the +"document" may not initially contain a "title". A document title is +not directly representable in reStructuredText_. Instead, a lone +top-level section may have its title promoted to become the document +title_, and similarly for a lone second-level (sub)section's title to +become the document subtitle_. The "docinfo_" may be transformed from +an initial field_list_, and "decoration_" is usually constructed +programmatically. Attributes -`````````` - -`Common external attributes`_. + The ``document`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. Example ------- +reStructuredText source:: ---------------------- - Attribute Reference ---------------------- + A Title + ======= -.. contents:: - :local: - :depth: 1 + A paragraph. -Through the `%basic.atts;`_ parameter entity, all elements share the -following _`common external attributes`: id_, name_, dupname_, -source_, class_. +Complete pseudo-XML_ result from simple parsing:: + <document> + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -``anonymous`` -============= +After applying transforms, the section title is promoted to become the +document title:: -The ``anonymous`` attribute + <document id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -``auto`` -======== +``emphasis`` +============ -The ``auto`` attribute +`To be completed`_. -``class`` +``entry`` ========= -The ``class`` attribute +`To be completed`_. -``dupname`` -=========== +``enumerated_list`` +=================== -The ``dupname`` attribute +`To be completed`_. -``id`` -====== +``error`` +========= -The ``id`` attribute +`To be completed`_. -``name`` +``field`` +========= + +`To be completed`_. + + +``field_argument`` +================== + +`To be completed`_. + + +``field_body`` +============== + +`To be completed`_. + + +``field_list`` +============== + +`To be completed`_. + + +``field_name`` +============== + +`To be completed`_. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +`To be completed`_. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +`To be completed`_. + + +``header`` +========== + +`To be completed`_. + + +``hint`` ======== -The ``name`` attribute +`To be completed`_. -``refid`` +``image`` ========= -The ``refid`` attribute +`To be completed`_. -``refname`` -=========== +``important`` +============= -The ``refname`` attribute +`To be completed`_. -``refuri`` -========== +``interpreted`` +=============== -The ``refuri`` attribute +`To be completed`_. -``source`` +``label`` +========= + +`To be completed`_. + + +``legend`` ========== -The ``source`` attribute +`To be completed`_. -``xml:space`` +``line_block`` +============== + +`To be completed`_. + + +``list_item`` ============= -The ``xml:space`` attribute +`To be completed`_. ------------------------- - DTD Parameter Entities ------------------------- +``literal`` +=========== -.. contents:: - :local: - :depth: 1 +`To be completed`_. -``%basic.atts;`` -================ +``literal_block`` +================= -The ``%basic.atts;`` parameter entity lists attributes common to all -elements. See `Common Attributes`_. +`To be completed`_. -``%body.elements;`` +``note`` +======== + +`To be completed`_. + + +``option`` +========== + +`To be completed`_. + + +``option_argument`` =================== -The ``%body.elements;`` parameter entity +`To be completed`_. -``%inline.elements;`` -===================== +``option_group`` +================ -The ``%inline.elements;`` parameter entity +`To be completed`_. -``%reference.atts;`` +``option_list`` +=============== + +`To be completed`_. + + +``option_list_item`` ==================== -The ``%reference.atts;`` parameter entity +`To be completed`_. -``%structure.model;`` -===================== +``option_string`` +================= -The ``%structure.model;`` parameter entity +`To be completed`_. -``%text.model;`` +``organization`` ================ -The ``%text.model;`` parameter entity +`To be completed`_. ----------------------- - Miscellaneous Topics ----------------------- +``paragraph`` +============= + +`To be completed`_. + + +``pending`` +=========== + +`To be completed`_. + + +``problematic`` +=============== + +`To be completed`_. + + +``raw`` +======= + +`To be completed`_. + + +``reference`` +============= + +`To be completed`_. + + +``revision`` +============ + +`To be completed`_. -.. contents:: - :local: - :depth: 1 +``row`` +======= + +`To be completed`_. + + +``section`` +=========== + +`To be completed`_. + + +``status`` +========== + +`To be completed`_. + + +``strong`` +========== + +`To be completed`_. + + +``substitution_definition`` +=========================== + +`To be completed`_. + + +``substitution_reference`` +========================== + +`To be completed`_. + + +``subtitle`` +============ + +Description +----------- + +Element category: `structural subelements`_. + +The ``subtitle`` element stores the subtitle of a document_. + +Parents + The following elements may contain ``subtitle``: document_. + +Children + ``subtitle`` elements may contain text data plus `inline + elements`_. + +Analogies + ``subtitle`` is analogous to HTML header elements ("h2" etc.) and + the DocBook "subtitle" element. + +Processing + A document's subtitle is usually rendered smaller than its title_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``subtitle`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Example +------- + +reStructuredText source:: + + ======= + Title + ======= + ---------- + Subtitle + ---------- + + A paragraph. + +Complete pseudo-XML_ result after parsing and transforms applied:: + + <document id="title" name="title"> + <title> + Title + <subtitle id="subtitle" name="subtitle"> + Subtitle + <paragraph> + A paragraph. + +Note how two section levels have collapsed, promoting their titles to +become the document's title and subtitle. Since there is only one +structural element (document), the subsection's ``id`` and ``name`` +attributes are stored in the ``subtitle`` element. + + +``system_message`` +================== + +`To be completed`_. + + +``table`` +========= + +`To be completed`_. + + +``target`` +========== + +`To be completed`_. + + +``tbody`` +========= + +`To be completed`_. + + +``term`` +======== + +`To be completed`_. + + +``tgroup`` +========== + +`To be completed`_. + + +``thead`` +========= + +`To be completed`_. + + +``tip`` +======= + +`To be completed`_. + + +``title`` +========= + +Description +----------- + +Element category: `structural subelements`_. + +The ``title`` element stores the title of a document_, section_, or +topic_. + +Parents + The following elements may contain ``title``: document_, section_, + topic_. + +Children + ``title`` elements may contain text data plus `inline elements`_. + +Analogies + ``title`` is analogous to HTML "title" and header ("h1" etc.) + elements, and DocBook "title" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``title`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), refid_, and auto_. + + ``refid`` is used as a backlink to a table of contents entry. + + ``auto`` is used to indicate (with value "1") that the ``title`` + has been numbered automatically. + + +Example +------- + +reStructuredText source:: + + A Title + ======= + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``topic`` +========= + +`To be completed`_. + + +``transition`` +============== + +`To be completed`_. + + +``version`` +=========== + +`To be completed`_. + + +``warning`` +=========== + +`To be completed`_. + + +--------------------- + Attribute Reference +--------------------- + +.. contents:: :local: + :depth: 1 + +_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, +all elements contain the following attributes: id_, name_, dupname_, +source_, and class_. + +.. _attribute type: + +Attribute types: + +``CDATA`` + Character data. ``CDATA`` attributes may contain arbitrary text. + +``ID`` + Like a ``NMTOKEN``, but it must begin with a letter (a "name + production"). Identical ``ID`` values must not appear more than + once in a document; i.e., ID values must uniquely identify their + elements. + +``IDREF`` + A reference to an ``ID`` value (a name production) of another + element. + +``IDREFS`` + One or more space-separated ``ID`` references (name productions). + +``NMTOKEN`` + A "name token". One or more of letters, digits, ".", "-", and + "_". + +``NMTOKENS`` + One or more space-separated ``NMTOKEN`` names. + +``%yesorno;`` + No if zero ("0"), yes if any other value. This is a parameter + entity which resolves to a ``NMTOKEN`` attribute type. + +``%number;`` + This emphasizes that the attribute value must be a number. This + is a parameter entity which resolves to a ``NMTOKEN`` attribute + type. + + +``anonymous`` +============= + +`Attribute type`_: ``%yesorno;``. Default value: none (implies no). + +The ``anonymous`` attribute is used for unnamed hyperlinks in the +target_ and reference_ elements. + + +``auto`` +======== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``auto`` attribute is used to indicate an automatically-numbered +footnote_, footnote_reference_ or title_. + + +``backrefs`` +============ + +`Attribute type`_: ``IDREFS``. Default value: none. + +The ``backrefs`` attribute contains a space-separated list of id_ +references, used for backlinks from footnote_, citation_, and +system_message_ elements. + + +``class`` +========= + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``class`` attribute contains one or more names used to classify or +subclassify an element. It can be used to carry context forward +between a Docutils Reader and Writer, when a custom structure is +reduced to a standardized document tree. ``class`` is one of the `common +attributes`_, shared by all Docutils elements. + + +``dupname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``dupname`` attribute contains the name of an element when there +has been a naming conflict. The contents of the ``dupname`` attribute +would have been transferred from the `name`_ attribute. An element +may have at most one of the ``name`` or ``dupname`` attributes, but +not both. ``dupname`` is one of the `common attributes`_, shared by +all Docutils elements. + + +``id`` +====== + +`Attribute type`_: ``ID``. Default value: none. + +The ``id`` attribute contains a unique identifier key. ``id`` is one +of the `common attributes`_, shared by all Docutils elements. + + +``name`` +======== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``name`` attribute contains the name of an element, typically +originating from the element's title or content. ``name`` must be +unique; if there are name conflicts (two or more elements want to the +same name), the contents will be transferred to the `dupname`_ +attribute on the duplicate elements. An element may have at most one +of the ``name`` or ``dupname`` attributes, but not both. ``name`` is +one of the `common attributes`_, shared by all Docutils elements. + + +``refid`` +========= + +`Attribute type`_: ``IDREF``. Default value: none. + +The ``refid`` attribute contains references to `id`_ attributes in +other elements. It is used by the target_, reference_, +footnote_reference_, citation_reference_, title_ and problematic_ +elements. + + +``refname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``refname`` attribute contains an internal reference to the +`name`_ attribute of another element. On a `target`_ element, +``refname`` indicates an indirect target which may resolve to either +an internal or external reference. ``refname`` is used by the +target_, reference_, footnote_reference_, citation_reference_, and +substitution_reference_ elements. + + +``refuri`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``refuri`` attribute contains an external reference to a URI/URL. +It is used by the target_, reference_, footnote_reference_, and +citation_reference_ elements. + + +``source`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``source`` attribute is used to store the path or URL to the +source text that was used to produce the document tree. It is one of +the `common attributes`_, shared by all Docutils elements. + + +``xml:space`` +============= + +`Attribute type`_: one of "default" or "preserve". Default value: +"preserve" (fixed). + +The ``xml:space`` attribute is a standard XML attribute for +whitespace-preserving elements. It is used by the literal_block_, +line_block_, doctest_block_, comment_, and raw_ elements. It is a +fixed attribute, meant to communicate to an XML parser that the +element contains significant whitespace. The attribute value should +not be set in a document instance. + + +-------------------- + Parameter Entities +-------------------- + +.. contents:: :local: + :depth: 1 + +Parameter entities are used to simplify the DTD (to share definitions +and reduce duplication) and to allow the DTD to be customized by +wrapper DTDs (external client DTDs that use or import the Docutils +DTD). Parameter entities may be overridden by wrapper DTDs, replacing +the definitions below with custom definitions. Parameter entities +whose names begin with "additional" are meant to allow easy extension +by wrapper DTDs. + + +``%anonymous.att;`` +=================== + +The ``%anonymous.att;`` parameter entity contains the anonymous_ +attribute, used for unnamed hyperlinks. + +Entity definition: + +.. parsed-literal:: + + anonymous %yesorno; #IMPLIED + + +``%auto.att;`` +============== + +The ``%auto.att;`` parameter entity contains the auto_ attribute, used +to indicate an automatically-numbered footnote or title. + +Entity definition: + +.. parsed-literal:: + + auto_ CDATA #IMPLIED + + +``%backrefs.att;`` +================== + +The ``%backrefs.att;`` parameter entity contains the backrefs_ +attribute, a space-separated list of id references, for backlinks. + +Entity definition: + +.. parsed-literal:: + + backrefs_ IDREFS #IMPLIED + + +``%basic.atts;`` +================ + +The ``%basic.atts;`` parameter entity lists attributes common to all +elements. See `Common Attributes`_. + +Entity definition: + +.. parsed-literal:: + + id_ ID #IMPLIED + name_ NMTOKENS #IMPLIED + dupname_ NMTOKENS #IMPLIED + source_ CDATA #IMPLIED + class_ NMTOKENS #IMPLIED + %additional.basic.atts; + +The ``%additional.basic.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%basic.atts;``. + + +``%body.elements;`` +=================== + +The ``%body.elements;`` parameter entity contains an OR-list of all +`body elements`_. + +Entity definition: + +.. parsed-literal:: + + paragraph_ | literal_block_ | doctest_block_ | line_block_ + | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ + | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ + | option_list_ + | attention_ | caution_ | danger_ | error_ | hint_ | important_ + | note_ | tip_ | warning_ + | target_ | substitution_definition_ | comment_ | pending_ + | system_message_ | raw_ + %additional.body.elements; + +The ``%additional.body.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%body.elements;``. + + +``%fixedspace.att;`` +==================== + +The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ +attribute, a standard XML attribute for whitespace-preserving +elements. + +Entity definition: + +.. parsed-literal:: + + xml:space (default | preserve) #FIXED 'preserve' + + +``%inline.elements;`` +===================== + +The ``%inline.elements;`` parameter entity contains an OR-list of all +`inline elements`_. + +Entity definition: + +.. parsed-literal:: + + emphasis_ | strong_ | interpreted_ | literal_ + | reference_ | footnote_reference_ | citation_reference_ + | substitution_reference_ | problematic_ | generated_ + | target_ | image_ | raw_ + %additional.inline.elements; + +The ``%additional.inline.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%inline.elements;``. + + +``%reference.atts;`` +==================== + +The ``%reference.atts;`` parameter entity groups together the refuri_, +refid_, and refname_ attributes. + +Entity definition: + +.. parsed-literal:: + + `%refuri.att;`_ + `%refid.att;`_ + `%refname.att;`_ + %additional.reference.atts; + +The ``%additional.reference.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%additional.reference.atts;``. + + +``%refid.att;`` +================ + +The ``%refid.att;`` parameter entity contains the refid_ attribute, an +internal reference to the `id`_ attribute of another element. + +Entity definition: + +.. parsed-literal:: + + refid_ CDATA #IMPLIED + + +``%refname.att;`` +================= + +The ``%refname.att;`` parameter entity contains the refname_ +attribute, an internal reference to the `name`_ attribute of another +element. On a `target`_ element, ``refname`` indicates an indirect +target which may resolve to either an internal or external +reference. + +Entity definition: + +.. parsed-literal:: + + refname_ NMTOKENS #IMPLIED + + +``%refuri.att;`` +================ + +The ``%refuri.att;`` parameter entity contains the refuri_ attribute, +an external reference to a URI/URL. + +Entity definition: + +.. parsed-literal:: + + refuri_ CDATA #IMPLIED + + +``%section.elements;`` +====================== + +The ``%section.elements;`` parameter entity contains an OR-list of +all section_-equivalent elements. + +Entity definition: + +.. parsed-literal:: + + section_ + %additional.section.elements; + +The ``%additional.section.elements;`` parameter entity can be used +by wrapper DTDs to extend ``%section.elements;``. + + +``%structure.model;`` +===================== + +The ``%structure.model;`` parameter entity is used by document_ and +section_ elements. It encapsulates the section structure of a +document and of parts of that document. See the discussion of the +`element hierarchy`_ above. + +Entity definition: + +.. parsed-literal:: + + ( ( (`%body.elements;`_ | topic_)+, + (transition_, (`%body.elements;`_ | topic_)+ )*, + (`%section.elements;`_)* ) + | (`%section.elements;`_)+ ) + +Each document_ or section_ contains either: + +- multiple body elements and/or topics, optionally interspersed with + transitions (but transitions cannot occur at the beginning or end, + nor may there be two transitions in a row), followed by zero or more + sections; or + +- one or more sections (whose contents are recursively the same as this + model). + + +``%text.model;`` +================ + +The ``%text.model;`` parameter entity is used by many elements to +represent text data mixed with `inline elements`_. + +Entity definition: + +.. parsed-literal:: + + (#PCDATA | `%inline.elements;`_)* + + +---------------------- + Miscellaneous Topics +---------------------- Representation of Horizontal Rules ================================== -Having added the "horizontal rule" construct to the reStructuredText_ -spec, a decision had to be made as to how to reflect the construct in -the implementation of the document tree. Given this source:: +Having added the "horizontal rule" construct to the `reStructuredText +Markup Specification`_, a decision had to be made as to how to reflect +the construct in the implementation of the document tree. Given this +source:: Document ======== @@ -399,8 +1489,6 @@ There are several possibilities for the implementation: Solution 3 was chosen for incorporation into the document tree model. -.. _reStructuredText: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html .. -- cgit v1.2.1 From 07f935fcc9b913de724ddf60ac5e1eecb062b0e5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:26:56 +0000 Subject: editorial improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@551 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index dbbec83fa..3e9d2da41 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -17,6 +17,12 @@ Directives have the following syntax:: | | +--------------------------+ +Directives begin with an explicit markup start (two periods and a +space), followed by the directive type, two colons, optional directive +data (on the same line as the directive type) and an optional +directive block (on subsequent lines). The directive block is +indented, aligned with the left edge of the directive type. + .. contents:: @@ -201,10 +207,13 @@ DTD element: line_block. Directive block: directive data and all following indented text become the body of the line block. -The "line-block" directive constructs a paragraph-like element where -leading whitespace and linebreaks are significant and inline markup is -supported. This is useful for address blocks and verse (poetry, song -lyrics). For example:: +The "line-block" directive constructs an element where whitespace +(including linebreaks) is significant and inline markup is supported. +It is equivalent to a `parsed literal block`_ with different +rendering: typically in an ordinary serif typeface instead of a +typewriter/monospaced face. Line blocks are useful for address blocks +and verse (poetry, song lyrics), where the structure of lines is +significant. For example, here's a classic:: "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by Ewan McTeagle (for Lassie O'Shea): @@ -228,8 +237,13 @@ the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. -This is useful for adding hyperlinks to code examples. For example, -all the element names in this content model are links:: +It is equivalent to a `line block`_ with different rendering: +typically in a typewriter/monospaced typeface, like an ordinary +literal block. Parsed literal blocks are useful for adding hyperlinks +to code examples. However, care must be taken with the text, because +inline markup is recognized; there is no protection from parsing. + +For example, all the element names in this content model are links:: .. parsed-literal:: -- cgit v1.2.1 From 47f1e25c94da9b7ca9e974804cc21d4c8e4d0496 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:29:09 +0000 Subject: - Added ``%number;`` attribute type parameter entity. - Changed ``%structural.elements;`` to ``%section.elements``. - Updated attribute types; made more specific. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@552 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 56 ++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5b7e8aac4..0e328bb34 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -19,15 +19,14 @@ The proposed formal public identifier for this DTD is:: +//IDN python.org//DTD Docutils Generic//EN//XML --> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parameter Entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parameter entities are used to simplify the DTD (reduce duplication) -and to allow the DTD to be customized by wrapper DTDs. Parameter -entities beginning with 'additional' are meant to allow easy extension +and to allow the DTD to be customized by wrapper DTDs. Parameter +entities beginning with "additional" are meant to allow easy extension by wrapper DTDs. --> @@ -37,6 +36,9 @@ by wrapper DTDs. <!-- Boolean: no if zero(s), yes if any other value. --> <!ENTITY % yesorno "NMTOKEN"> +<!-- Emphasize that the attribute value must be a number. --> +<!ENTITY % number "NMTOKEN"> + <!ENTITY % additional.basic.atts ""> <!-- Attributes shared by all elements in this DTD: @@ -49,10 +51,10 @@ Attributes shared by all elements in this DTD: --> <!ENTITY % basic.atts " id ID #IMPLIED - name CDATA #IMPLIED - dupname CDATA #IMPLIED + name NMTOKENS #IMPLIED + dupname NMTOKENS #IMPLIED source CDATA #IMPLIED - class CDATA #IMPLIED + class NMTOKENS #IMPLIED %additional.basic.atts; "> <!-- External reference to a URI/URL. --> @@ -73,7 +75,7 @@ Internal reference to the `name` attribute of an element. On a resolve to either an internal or external reference. --> <!ENTITY % refname.att - " refname CDATA #IMPLIED "> + " refname NMTOKENS #IMPLIED "> <!ENTITY % additional.reference.atts ""> <!-- Collected hyperlink reference attributes. --> @@ -89,7 +91,7 @@ resolve to either an internal or external reference. <!-- Auto-numbered footnote or title. --> <!ENTITY % auto.att - " auto %yesorno; #IMPLIED "> + " auto CDATA #IMPLIED "> <!-- XML standard attribute for whitespace-preserving elements. --> <!ENTITY % fixedspace.att @@ -106,10 +108,10 @@ resolve to either an internal or external reference. | field %additional.bibliographic.elements; "> -<!ENTITY % additional.structural.elements ""> -<!ENTITY % structural.elements +<!ENTITY % additional.section.elements ""> +<!ENTITY % section.elements " section - %additional.structural.elements; "> + %additional.section.elements; "> <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements @@ -131,18 +133,20 @@ resolve to either an internal or external reference. | target | image | raw %additional.inline.elements; "> + <!-- Element Content Models ================================================================== --> <!ENTITY % structure.model " ( ( (%body.elements; | topic)+, (transition, (%body.elements; | topic)+ )*, - (%structural.elements;)* ) - | (%structural.elements;)+ ) "> + (%section.elements;)* ) + | (%section.elements;)+ ) "> <!ENTITY % text.model " (#PCDATA | %inline.elements;)* "> + <!-- Table Model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,8 +169,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!ENTITY % tbl.entry.mdl " (%body.elements;)* "> <!ENTITY % tbl.entry.att " %basic.atts; - morecols NMTOKEN #IMPLIED "> - + morecols %number; #IMPLIED "> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -179,7 +182,6 @@ http://www.oasis-open.org/html/tm9901.htm). ((title, subtitle?)?, docinfo?, decoration?, %structure.model;)> <!ATTLIST document %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Title Elements @@ -195,7 +197,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT subtitle %text.model;> <!ATTLIST subtitle %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bibliographic Elements @@ -233,7 +234,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT copyright %text.model;> <!ATTLIST copyright %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Decoration Elements @@ -249,7 +249,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT footer (%body.elements;)+> <!ATTLIST footer %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Structural Elements @@ -265,7 +264,6 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT transition EMPTY> <!ATTLIST transition %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Body Elements @@ -288,7 +286,7 @@ http://www.oasis-open.org/html/tm9901.htm). #IMPLIED prefix CDATA #IMPLIED suffix CDATA #IMPLIED - start NUMBER #IMPLIED> + start %number; #IMPLIED> <!ELEMENT list_item (%body.elements;)+> <!ATTLIST list_item %basic.atts;> @@ -440,9 +438,9 @@ either the string separating it from the `option` (typically either %basic.atts; uri CDATA #REQUIRED alt CDATA #IMPLIED - height NMTOKEN #IMPLIED - width NMTOKEN #IMPLIED - scale NMTOKEN #IMPLIED> + height &number; #IMPLIED + width &number; #IMPLIED + scale &number; #IMPLIED> <!ELEMENT caption %text.model;> <!ATTLIST caption %basic.atts;> @@ -460,16 +458,15 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. <!ATTLIST system_message %basic.atts; %backrefs.att; - level NMTOKEN #IMPLIED - type CDATA #IMPLIED> + level &number; #IMPLIED + type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> <!ELEMENT raw %text.model;> <!ATTLIST raw %basic.atts; %fixedspace.att; - format CDATA #IMPLIED> - + format NMTOKEN #IMPLIED> <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -497,7 +494,7 @@ following caveats: <!ELEMENT interpreted (%text.model;)> <!ATTLIST interpreted %basic.atts; - role CDATA #IMPLIED + role NMTOKEN #IMPLIED position (prefix | suffix) #IMPLIED> <!ELEMENT literal (#PCDATA)> @@ -533,7 +530,6 @@ following caveats: <!ELEMENT generated (%text.model;)> <!ATTLIST generated %basic.atts;> - <!-- Local Variables: mode: sgml -- cgit v1.2.1 From b24a391ecebe5f31ba0129fdecf2aadbef595f5b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:31:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@553 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 9 ++------- docs/peps/pep-0258.txt | 2 +- docs/user/tools.txt | 13 +++++++------ 3 files changed, 10 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index f81de795d..758ce05bc 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -21,14 +21,13 @@ The proposed formal public identifier for this DTD is:: +//IDN python.org//DTD Docutils Python Source//EN//XML --> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Parameter Entity Overrides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> -<!ENTITY % additional.structural.elements +<!ENTITY % additional.section.elements " | package_section | module_section | class_section | method_section | function_section | module_attribute_section | class_attribute_section | instance_attribute_section "> @@ -39,7 +38,6 @@ The proposed formal public identifier for this DTD is:: | module_attribute | class_attribute | instance_attribute | exception_class | warning_class "> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Generic DTD @@ -54,10 +52,9 @@ http://docutils.sourceforge.net/spec/docutils.dtd. "docutils.dtd"> %docutils; - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Structural Elements + Additional Section Elements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> @@ -127,7 +124,6 @@ http://docutils.sourceforge.net/spec/docutils.dtd. <!ELEMENT initial_value (#PCDATA)> <!ATTLIST initial_value %basic.atts;> - <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Additional Inline Elements @@ -218,7 +214,6 @@ Also used as the `instance_attribute_section` identifier/title. %basic.atts; %reference.atts;> - <!-- Local Variables: mode: sgml diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 9b03c9524..e9ac3415f 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -879,7 +879,7 @@ stylist code will lower the barrier considerably. .. _soextbl.dtd: http://docutils.sourceforge.net/spec/soextblx.dtd .. _The Docutils Document Tree: - http://docutils.sourceforge.net/spec/doctree.txt + http://docutils.sourceforge.net/spec/doctree.html .. _VMS error condition severity levels: http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 7d2de6c0d..565c4d3ea 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -80,12 +80,13 @@ where "X.Y" is the release version. Alternatively:: tools/buildhtml.py --config=tools/docutils.conf The current directory (and all subdirectories) is chosen by default if -no directory is named. Incomplete files (such as spec/doctree.txt) -may generate system messages; use the ``--quiet`` option to suppress -all warnings. The ``--config`` option ensures that the correct -stylesheets, templates, and settings are in place (``./docutils.conf`` -is picked up automatically). Command-line options may be used to -override config file settings or replace them altogether. +no directory is named. Some files may generate system messages +(tools/test.txt contains intentional errors); use the ``--quiet`` +option to suppress all warnings. The ``--config`` option ensures that +the correct stylesheets, templates, and settings are in place +(``./docutils.conf`` is picked up automatically). Command-line +options may be used to override config file settings or replace them +altogether. html.py -- cgit v1.2.1 From aebb476aeb2df374d2f34c9ee9166ea3967317b0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:38:39 +0000 Subject: Made the element subsection entitled "Description" implicit, because it interfered with the "description" element. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@554 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index bcf983971..50564348e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -217,7 +217,8 @@ Each element in the DTD (document type definition) is described in its own section below. Each section contains the following subsections and items: -* Description: The semantics of the element. +* The initial text contains a description of the semantics of the + element, plus: - Parents: A list of elements which may contain the element. @@ -410,9 +411,6 @@ its writing. ``document`` ============ -Description ------------ - Element category: `structural elements`_. The ``document`` element is the root (topmost) element of the Docutils @@ -760,9 +758,6 @@ document title:: ``subtitle`` ============ -Description ------------ - Element category: `structural subelements`_. The ``subtitle`` element stores the subtitle of a document_. @@ -875,9 +870,6 @@ attributes are stored in the ``subtitle`` element. ``title`` ========= -Description ------------ - Element category: `structural subelements`_. The ``title`` element stores the title of a document_, section_, or -- cgit v1.2.1 From e7ec9616617696f83df6abe5c96e5ab85357fa6a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 01:46:49 +0000 Subject: tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@555 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 50564348e..6e9bc3b80 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -896,7 +896,7 @@ Content Model Attributes The ``title`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), refid_, and auto_. + name_, dupname_, source_, and class_), plus refid_ and auto_. ``refid`` is used as a backlink to a table of contents entry. @@ -1155,7 +1155,7 @@ Entity definition: .. parsed-literal:: - anonymous %yesorno; #IMPLIED + anonymous_ %yesorno; #IMPLIED ``%auto.att;`` @@ -1181,7 +1181,7 @@ Entity definition: .. parsed-literal:: - backrefs_ IDREFS #IMPLIED + backrefs_ IDREFS #IMPLIED ``%basic.atts;`` @@ -1240,7 +1240,7 @@ Entity definition: .. parsed-literal:: - xml:space (default | preserve) #FIXED 'preserve' + `xml:space`_ (default | preserve) #FIXED 'preserve' ``%inline.elements;`` -- cgit v1.2.1 From 7a665930bde84725f54d7a0236679682249d5e03 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 02:06:44 +0000 Subject: more tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@556 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 6e9bc3b80..ca5bb0aaa 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -24,9 +24,9 @@ found in internal documentation (docstrings) for the implemented in a class library. The reader is assumed to have some familiarity with XML or SGML, and -an understanding the data structure meaning of "tree". For a list of -introductory articles, see `Introducing the Extensible Markup Language -(XML)`_. +an understanding of the data structure meaning of "tree". For a list +of introductory articles, see `Introducing the Extensible Markup +Language (XML)`_. The reStructuredText_ markup is used for illustrative examples throughout this document. For a gentle introduction, see `A @@ -186,7 +186,7 @@ Category members: caption_, classifier_, colspec_, definition_, definition_list_item_, description_, entry_, field_, field_argument_, field_body_, field_name_, label_, legend_, list_item_, option_, option_argument_, option_group_, option_list_item_, option_string_, -row_, tbody_, term_, tgroup_, thead +row_, tbody_, term_, tgroup_, thead_ Inline Elements @@ -1028,10 +1028,10 @@ system_message_ elements. `Attribute type`_: ``NMTOKENS``. Default value: none. -The ``class`` attribute contains one or more names used to classify or -subclassify an element. It can be used to carry context forward -between a Docutils Reader and Writer, when a custom structure is -reduced to a standardized document tree. ``class`` is one of the `common +The ``class`` attribute contains one or more names used to classify an +element. It can be used to carry context forward between a Docutils +Reader and Writer, when a custom structure is reduced to a +standardized document tree. ``class`` is one of the `common attributes`_, shared by all Docutils elements. -- cgit v1.2.1 From 9631ca774f2b84f2cd7ae2fb83090308a609ac5e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 16:12:59 +0000 Subject: Added missing ``%bibliographic.elements;`` parameter entity. More tweaks. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@557 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ca5bb0aaa..0253908b5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -10,13 +10,15 @@ A Guide to the Docutils DTD :Revision: $Revision$ :Date: $Date$ + .. contents:: :depth: 1 -This document describes the XML data structure of Docutils_ documents, -the relationships and semantics of elements. The Docutils document -structure is formally defined by the `Docutils Generic DTD`_ XML -document type definition, docutils.dtd_, which is the definitive -source for details of element structural relationships. + +This document describes the XML data structure of Docutils_ documents: +the relationships and semantics of elements and attributes. The +Docutils document structure is formally defined by the `Docutils +Generic DTD`_ XML document type definition, docutils.dtd_, which is +the definitive source for details of element structural relationships. This document does not discuss implementation details. Those can be found in internal documentation (docstrings) for the @@ -803,7 +805,7 @@ reStructuredText source:: A paragraph. -Complete pseudo-XML_ result after parsing and transforms applied:: +Complete pseudo-XML_ result after parsing and applying transforms:: <document id="title" name="title"> <title> @@ -1205,6 +1207,25 @@ The ``%additional.basic.atts;`` parameter entity can be used by wrapper DTDs to extend ``%basic.atts;``. +``%bibliographic.elements;`` +============================ + +The ``%bibliographic.elements;`` parameter entity contains an OR-list of all +`bibliographic elements`_. + +Entity definition: + +.. parsed-literal:: + + author_ | authors_ | organization_ | contact_ + | version_ | revision_ | status_ | date_ | copyright_ + | field_ + %additional.bibliographic.elements; + +The ``%additional.bibliographic.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%bibliographic.elements;``. + + ``%body.elements;`` =================== -- cgit v1.2.1 From ac8f51c8f6be541125dbd57742b7a43ff0acaeb8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 16:14:22 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@558 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 46 +++++++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6eadeac0a..f8b1707cd 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -448,18 +448,38 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`misc.raw` + - _`misc.raw`: See `Raw Data Pass-Through`__ in rst/directives.txt. + + __ http://docutils.sf.net/spec/rst/directives.html + #raw-data-pass-through - _`misc.include`: ``#include`` one file in another. But how to - parse wrt sections, reference names, conflicts? Parse it in the - current document's context (C-preprocessor semantics), or - separately and then merge? - - 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 + parse wrt sections, reference names, conflicts? For now, we'll + parse it in the current document's context (C-preprocessor + semantics). Perhaps later, when there's a need, we'll figure out + how to provide separate parsing (parse separately and then merge). + + A "raw" flag (attribute with no value) would inform us that the + imported data is raw (already in native format, like HTML). + Perhaps there should be an attribute value, saying what the native + format is. See misc.raw_. + + .. include:: path/subdocument.txt + :raw: (true if set) + + Implementation ideas: Model the directive parsing on the "images" + directive. A separate, nested parse is probably needed, since + it's not a good idea to alter the already-read data. Use + ``state.nested_parse()`` (see directives/admonitions.py), and pass + in ``match_titles=1``. The reporting mechanism will have to be + revamped to include the file which is the source of system + messages. + + YAGNI for now: 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?) - _`misc.exec`: Execute Python code & insert the results. Perhaps @@ -744,15 +764,15 @@ Front-End Tools All references to files (stylesheet, source file [in footer], PEP template) are interpreted relative to the current working directory, and adjusted relative to the destination directory. For example:: - + cd /work html.py -s --stylesheet=default.css /src/test.txt /dst/text.html - + This will interpret the stylesheet as "work/default.css", so the stylesheet link in the HTML (which is in the /dst dir) will read "../work/default.css", and the source link (-s option) will read "../src/test.txt". - + Perhaps the current behavior should be optional ("--relative-paths" or something). The default should probably be not to process paths at all, just use them verbatim. -- cgit v1.2.1 From c6dbb94a3e92ae607cc0a04186f71c60d1d1dcab Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 16:16:07 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@559 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f8b1707cd..bba9e3c8a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -462,10 +462,10 @@ Directives A "raw" flag (attribute with no value) would inform us that the imported data is raw (already in native format, like HTML). Perhaps there should be an attribute value, saying what the native - format is. See misc.raw_. + format is. See misc.raw_. Example:: .. include:: path/subdocument.txt - :raw: (true if set) + :raw: Implementation ideas: Model the directive parsing on the "images" directive. A separate, nested parse is probably needed, since -- cgit v1.2.1 From 39e3801062512042229efaebced62484c3901bc1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 16:27:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@560 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bba9e3c8a..09441f077 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -462,7 +462,9 @@ Directives A "raw" flag (attribute with no value) would inform us that the imported data is raw (already in native format, like HTML). Perhaps there should be an attribute value, saying what the native - format is. See misc.raw_. Example:: + format is. Instead, perhaps the "raw" directive should take an + "include" parameter (explicit attribute or second parameter in its + directive data). See misc.raw_. Example:: .. include:: path/subdocument.txt :raw: -- cgit v1.2.1 From 408dc71030378fa9541310582a98df85b43ed8e9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 17:13:15 +0000 Subject: updated/fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@561 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 4 ++-- docs/ref/rst/introduction.txt | 31 ++++++++++++++++--------------- 2 files changed, 18 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index e241ed557..f90320a03 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -645,8 +645,8 @@ used square brackets for phrase-links. I changed my mind because: for example when quoting Python repr-equivalent syntax that uses backquotes. -3. The processing of identifiers (funtion/method/attribute/module/etc. - names) into hyperlinks is a useful feature. PyDoc recognizes +3. The processing of identifiers (function/method/attribute/module + etc. names) into hyperlinks is a useful feature. PyDoc recognizes identifiers heuristically, but it doesn't take much imagination to come up with counter-examples where PyDoc's heuristics would result in embarassing failure. I wanted to do it deterministically, and diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 3ca6de778..ea5c6ca90 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -19,9 +19,9 @@ application domains. Its parser is a component of Docutils_. This document defines the goals_ of reStructuredText and provides a history_ of the project. It is written using the reStructuredText markup, and therefore serves as an example of its use. Please also -see an analysis of the `problems with StructuredText`_ and the -`reStructuredText markup specification`_ itself at project's web page, -http://docutils.sourceforge.net/rst.html. +see an analysis of the `Problems With StructuredText`_ and the +`reStructuredText Markup Specification`_ itself at the subproject's +web page, http://docutils.sourceforge.net/rst.html. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: @@ -145,8 +145,8 @@ History reStructuredText_, the specification, is based on StructuredText_ and Setext_. StructuredText was developed by Jim Fulton of `Zope Corporation`_ (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source 'Z Object Publishing -Environment' (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ +It is now released as a part of the open-source "Z Object Publishing +Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ specification was either an influence on StructuredText or, by their similarities, at least evidence of the correctness of this approach. @@ -157,13 +157,13 @@ I was not able to get pythondoc to work for me, I found StructuredText to be almost ideal for my needs. I joined the Python Doc-SIG_ (Documentation Special Interest Group) mailing list and found an ongoing discussion of the shortcomings of the StructuredText -'standard'. This discussion has been going on since the inception of +"standard". This discussion has been going on since the inception of the mailing list in 1996, and possibly predates it. I decided to modify the original module with my own extensions and some suggested by the Doc-SIG members. I soon realized that the module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the 're' regular +general reworking, including adapting it to the "re" regular expression module (the original inspiration for the name of this project). Soon after I completed the modifications, I discovered that StructuredText.py was up to version 1.23 in the ZOPE distribution. @@ -178,7 +178,7 @@ StructuredText. I decided that a complete rewrite was in order, and even started a `reStructuredText SourceForge project`_ (now inactive). My -motivations (the 'itches' I aim to 'scratch') are as follows: +motivations (the "itches" I aim to "scratch") are as follows: - I need a standard format for inline documentation of the programs I write. This inline documentation has to be convertible to other @@ -229,7 +229,7 @@ June 2001, including posting the second draft of the spec [#spec-2]_ and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the Doc-SIG. These documents and the project implementation proceeded to evolve at a rapid pace. Implementation history details can be found -in the project file, HISTORY.txt_. +in the `project history file`_. In November 2001, the reStructuredText parser was nearing completion. Development of the parser continued with the addition of small @@ -253,7 +253,8 @@ followed. .. __: `reStructuredText SourceForge project`_ -.. [#spec-2] +.. [#spec-2] The second draft of the spec: + - `An Introduction to reStructuredText`__ - `Problems With StructuredText`__ - `reStructuredText Markup Specification`__ @@ -265,7 +266,8 @@ followed. __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html -.. [#peps-1] +.. [#peps-1] First drafts of the PEPs: + - `PEP 256: Docstring Processing System Framework`__ - `PEP 258: DPS Generic Implementation Details`__ - `PEP 257: Docstring Conventions`__ @@ -286,11 +288,10 @@ followed. .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ .. _StructuredTextNG: http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _HISTORY.txt: - http://docutils.sourceforge.net/HISTORY.txt -.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.txt +.. _project history file: http://docutils.sourceforge.net/HISTORY.html +.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.html .. _Docstring Processing System framework: - http://docutils.sourceforge.net/spec/pep-0256.txt + http://docutils.sourceforge.net/spec/pep-0256.html .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ -- cgit v1.2.1 From abac0fa413311365e8db58fde6dc403759778fe6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Aug 2002 17:34:43 +0000 Subject: more tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 0253908b5..6ee5d1e97 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -113,26 +113,27 @@ Structural subelements are child elements of structural elements, but contain no further structure of their own (except for text and inline elements). -Category members: title_, subtitle_, transition_ +Category members: title_, subtitle_, docinfo_, decoration_, +transition_ Bibliographic Elements ----------------------- +`````````````````````` The docinfo_ element is an optional child of document_. It groups bibliographic elements together. -Category members: docinfo_, author_, authors_, contact_, copyright_, -date_, organization_, revision_, status_, version_ +Category members: author_, authors_, contact_, copyright_, date_, +organization_, revision_, status_, version_ Decorative Elements -------------------- +``````````````````` The decoration_ element is also an optional child of document_. It groups together elements used to generate page headers and footers. -Category members: decoration_, footer_, header_ +Category members: footer_, header_ Body Elements -- cgit v1.2.1 From 8bc9ccd896a49fbc07aef3fcd4d3178e0f2e58c7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Aug 2002 15:38:06 +0000 Subject: tweaked the subsections some more git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@563 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 134 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 79 insertions(+), 55 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 6ee5d1e97..622243ec5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -124,7 +124,7 @@ The docinfo_ element is an optional child of document_. It groups bibliographic elements together. Category members: author_, authors_, contact_, copyright_, date_, -organization_, revision_, status_, version_ +field_, organization_, revision_, status_, version_ Decorative Elements @@ -166,7 +166,7 @@ target_ Compound Body Elements ---------------------- -Compound body elements contain local substructure (component parts) +Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. Category members: attention_, block_quote_, bullet_list_, caution_, @@ -175,21 +175,24 @@ field_list_, figure_, footnote_, hint_, important_, note_, option_list_, system_message_, table_, tip_, warning_ -Compound Body Subelements -````````````````````````` +Body Subelements +```````````````` -Compound body elements contain specific compound body subelements -(e.g. bullet_list_ contains list_item_). Subelements may themselves -be compound elements (containing further child elements, like field_) -or simple data elements (containing text data, like field_name_). -These subelements always occur within specific parent elements, never -at the body element level (just below sections, etc.). +Compound body elements contain specific subelements (e.g. bullet_list_ +contains list_item_). Subelements may themselves be compound elements +(containing further child elements, like field_) or simple data +elements (containing text data, like field_name_). These subelements +always occur within specific parent elements, never at the body +element level (beside paragraphs, etc.). -Category members: caption_, classifier_, colspec_, definition_, -definition_list_item_, description_, entry_, field_, field_argument_, -field_body_, field_name_, label_, legend_, list_item_, option_, -option_argument_, option_group_, option_list_item_, option_string_, -row_, tbody_, term_, tgroup_, thead_ +Category members (simple): caption_, classifier_, colspec_, +field_argument_, field_name_, label_, option_argument_, +option_string_, term_ + +Category members (compound): definition_, definition_list_item_, +description_, entry_, field_, field_body_, legend_, list_item_, +option_, option_group_, option_list_item_, row_, tbody_, tgroup_, +thead_ Inline Elements @@ -201,7 +204,7 @@ body elements. Most inline elements have a "mixed content model". Category members: citation_reference_, emphasis_, footnote_reference_, generated_, image_, interpreted_, literal_, problematic_, reference_, -strong_, substitution_reference_, target_, raw_. +strong_, substitution_reference_, target_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -217,11 +220,14 @@ strong_, substitution_reference_, target_, raw_. :depth: 1 Each element in the DTD (document type definition) is described in its -own section below. Each section contains the following subsections -and items: +own section below. Each section contains an introduction plus the +following subsections: + +* Details (of element relationships and semantics): -* The initial text contains a description of the semantics of the - element, plus: + - Category: One or more references to the element categories in + `Element Hierarchy`_ above. Some elements belong to more than one + category. - Parents: A list of elements which may contain the element. @@ -234,7 +240,9 @@ and items: - Processing: Lists formatting or rendering recommendations for the element. -* Content Model: from the `Docutils DTD`_. +* Content Model: + + The formal XML content model from the `Docutils DTD`_, followed by: - Attributes: Describes (or refers to descriptions of) the possible values and semantics of each attribute. @@ -242,29 +250,31 @@ and items: - Parameter Entities: Lists the parameter entities which include the element described. -* Example: Where possible, a reStructuredText example is shown along - with a fragment of the document tree resulting from parsing. +* Examples: reStructuredText examples are shown along with + fragments of the document trees resulting from parsing. _`Pseudo-XML` is used for the results of parsing and processing. Pseudo-XML is a representation of XML where nesting is indicated by indentation and end-tags are not shown. Some of the precision of - real XML is traded for easier readability. For example, the - following are equivalent. XML:: + real XML is given up in exchange for easier readability. For + example, the following are equivalent: - <document> - <section id="a-title" name="a title"> - <title>A Title - A paragraph. -
- + - Real XML:: - Pseudo-XML:: + +
+ A Title + A paragraph. +
+ + + - Pseudo-XML:: - -
- - A Title - <paragraph> - A paragraph. + <document> + <section id="a-title" name="a title"> + <title> + A Title + <paragraph> + A paragraph. -------------------- @@ -414,20 +424,24 @@ its writing. ``document`` ============ -Element category: `structural elements`_. - The ``document`` element is the root (topmost) element of the Docutils document tree. ``document`` is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document. + +Details +------- + +Category + `Structural Elements`_ + Parents The ``document`` element has no parents. Children - ``document`` elements may contain the following elements: title_, - subtitle_, docinfo_, decoration_, topic_, transition_, section_, - and `body elements`_. + ``document`` elements may contain `structural subelements`_, + `structural elements`_, and `body elements`_. Analogies ``document`` is analogous to the HTML "html" element and several @@ -459,8 +473,8 @@ Attributes id_, name_, dupname_, source_, and class_. -Example -------- +Examples +-------- reStructuredText source:: @@ -761,12 +775,17 @@ document title:: ``subtitle`` ============ -Element category: `structural subelements`_. - The ``subtitle`` element stores the subtitle of a document_. + +Details +------- + +Category + `Structural Subelements`_ + Parents - The following elements may contain ``subtitle``: document_. + The following elements may contain ``subtitle``: document_ Children ``subtitle`` elements may contain text data plus `inline @@ -792,8 +811,8 @@ Attributes id_, name_, dupname_, source_, and class_. -Example -------- +Examples +-------- reStructuredText source:: @@ -873,14 +892,19 @@ attributes are stored in the ``subtitle`` element. ``title`` ========= -Element category: `structural subelements`_. - The ``title`` element stores the title of a document_, section_, or topic_. + +Details +------- + +Category + `Structural Subelements`_ + Parents The following elements may contain ``title``: document_, section_, - topic_. + topic_ Children ``title`` elements may contain text data plus `inline elements`_. @@ -907,8 +931,8 @@ Attributes has been numbered automatically. -Example -------- +Examples +-------- reStructuredText source:: -- cgit v1.2.1 From 9a6d962501d8b2aeb79e847555061b849d5ea34c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 02:48:06 +0000 Subject: tweaks & good progress git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@570 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 1051 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 1011 insertions(+), 40 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 622243ec5..26a65c9cb 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -9,6 +9,7 @@ A Guide to the Docutils DTD :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: :depth: 1 @@ -39,14 +40,12 @@ ReStructuredText Primer`_. For complete technical details, see the .. _Docutils: http://docutils.sourceforge.net/ .. _Docutils Generic DTD: .. _Docutils DTD: -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _docutils.dtd: docutils.dtd .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/rst/quickstart.html -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html +.. _A ReStructuredText Primer: ../docs/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/reStructuredText.html ------------------- @@ -123,8 +122,8 @@ Bibliographic Elements The docinfo_ element is an optional child of document_. It groups bibliographic elements together. -Category members: author_, authors_, contact_, copyright_, date_, -field_, organization_, revision_, status_, version_ +Category members: address_, author_, authors_, contact_, copyright_, +date_, field_, organization_, revision_, status_, version_ Decorative Elements @@ -247,8 +246,8 @@ following subsections: - Attributes: Describes (or refers to descriptions of) the possible values and semantics of each attribute. - - Parameter Entities: Lists the parameter entities which include the - element described. + - Parameter Entities: Lists the parameter entities which directly or + indirectly include the element. * Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. @@ -283,6 +282,80 @@ completed`". Please help complete this document by contributing to its writing. +``address`` +=========== + +The ``address`` element holds the surface mailing address information +for the author (individual or group) of the document, or a third-party +contact address. Its structure is identical to that of the +line_block_ element: whitespace is significant, especially newlines. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``address``: docinfo_, authors_ + +Children + ``address`` elements contain text data plus `inline elements`_. + +Analogies + ``address`` is analogous to the DocBook "address" element. + +Processing + As with the line_block_ element, newlines and other whitespace is + significant and must be preserved. However, a monospaced typeface + need not be used. + + See also docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``address`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus `xml:space`_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``address``. + + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Address: 123 Example Ave. + Example, EX + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <address> + 123 Example Ave. + Example, EX + +See docinfo_ for a more complete example, including processing +context. + + ``attention`` ============= @@ -292,13 +365,139 @@ its writing. ``author`` ========== -`To be completed`_. +The ``author`` element holds the name of the author of the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``author``: docinfo_, authors_ + +Children + ``author`` elements may contain text data plus `inline elements`_. + +Analogies + ``author`` is analogous to the DocBook "author" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``author`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``author``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Author: J. Random Hacker + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <author> + J. Random Hacker + +See docinfo_ for a more complete example, including processing +context. ``authors`` =========== -`To be completed`_. +The ``authors`` element is a container for author information for +documents with multiple authors. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``authors``. + +Children + ``authors`` elements may contain the following elements: author_, + organization_, address_, contact_ + +Analogies + ``authors`` is analogous to the DocBook "authors" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + ((author_, organization_?, address_?, contact_?)+) + +Attributes + The ``authors`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``authors``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Authors: J. Random Hacker; Jane Doe + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <authors> + <author> + J. Random Hacker + <author> + Jane Doe + +In reStructuredText, multiple author's names are separated with +semicolons (";") or commas (","); semicolons take precedence. There +is currently no way to represent the author's organization, address, +or contact in a reStructuredText "Authors" field. + +See docinfo_ for a more complete example, including processing +context. ``block_quote`` @@ -358,13 +557,135 @@ its writing. ``contact`` =========== -`To be completed`_. +The ``contact`` element holds contact information for the author +(individual or group) of the document, or a third-party contact. It +is typically used for an email or web address. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + The following elements may contain ``contact``: docinfo_, authors_ + +Children + ``contact`` elements may contain text data plus `inline + elements`_. + +Analogies + ``contact`` is analogous to the DocBook "email" element. The HTML + "address" element serves a similar purpose. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``contact`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``contact``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Contact: jrh@example.com + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + +See docinfo_ for a more complete example, including processing +context. ``copyright`` ============= -`To be completed`_. +The ``copyright`` element contains the document's copyright statement. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``copyright``. + +Children + ``copyright`` elements may contain text data plus `inline + elements`_. + +Analogies + ``copyright`` is analogous to the DocBook "copyright" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``copyright`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``copyright``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <copyright> + This document has been placed in the public domain. + +See docinfo_ for a more complete example, including processing +context. ``danger`` @@ -376,13 +697,131 @@ its writing. ``date`` ======== -`To be completed`_. +The ``date`` element contains the date of publication, release, or +last modification of the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``date``. + +Children + ``date`` elements may contain text data plus `inline elements`_. + +Analogies + ``date`` is analogous to the DocBook "date" element. + +Processing + Often used with the RCS/CVS keyword "Date". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``date`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``date``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Date: 2002-08-20 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <date> + 2002-08-20 + +See docinfo_ for a more complete example, including processing +context. ``decoration`` ============== -`To be completed`_. +The ``decoration`` element is a container for header_ and footer_ +elements and potential future extensions. These elements are used for +page navigation, notes, time/datestamp, etc. Currently only the +footer_ element is implemented, populated with processing information +(datestamp, a link to Docutils_, etc.). + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + Only the document_ element contains ``decoration``. + +Children + ``decoration`` elements may contain `decorative elements`_. + +Analogies + There are no direct analogies to ``decoration`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + +Processing + See the individual `decorative elements`_. + +Content Model +------------- + +.. parsed-literal:: + + (header_?, footer_?) + +Although the content model doesn't specifically require contents, no +empty ``decoration`` elements are ever created. + +Attributes + The ``decoration`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. ``definition`` @@ -412,7 +851,106 @@ its writing. ``docinfo`` =========== -`To be completed`_. +The ``docinfo`` element is a container for document bibliographic +data, or meta-data (data about the document). It corresponds to the +front matter of a book, such as the title page and copyright page. + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + Only the document_ element contains ``docinfo``. + +Children + ``docinfo`` elements contain `bibliographic elements`_. + +Analogies + ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" + etc.). There are no directly analogous HTML elements; the "meta" + element carries some of the same information, albeit invisibly. + +Processing + The ``docinfo`` element may be rendered as a two-column table or + in other styles. It may even be invisible or omitted from the + processed output. Meta-data may be extracted from ``docinfo`` + children; for example, HTML ``<meta>`` tags may be constructed. + + When Docutils_ transforms a reStructuredText_ field_list_ into a + ``docinfo`` element (see the examples below), RCS/CVS keywords are + normally stripped from simple (one paragraph) field bodies. For + complete details, please see `RCS Keywords`_ in the + `reStructuredText Markup Specification`_. + + .. _RCS Keywords: rst/reStructuredText.html#rcs-keywords + + +Content Model +------------- + +.. parsed-literal:: + + (`%bibliographic.elements;`_)+ + +Attributes + The ``docinfo`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +Docinfo is represented in reStructuredText by a field_list_ in a +bibliographic context: the first non-comment element of a document_, +after any document title_/subtitle_. The field list is transformed +into a ``docinfo`` element and its children by a transform. Source:: + + Docinfo Example + =============== + + :Author: J. Random Hacker + :Contact: jrh@example.com + :Date: 2002-08-18 + :Status: Work In Progress + :Version: 1 + :Filename: $RCSfile$ + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="docinfo-example" name="docinfo example"> + <title> + Docinfo Example + <docinfo> + <author> + J. Random Hacker + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + <date> + 2002-08-18 + <status> + Work In Progress + <version> + 1 + <field> + <field_name> + Filename + <field_body> + <paragraph> + doctree.txt + <copyright> + This document has been placed in the public domain. + +Note that "Filename" is a non-standard ``docinfo`` field, so becomes a +generic ``field`` element. Also note that the "RCSfile" keyword +syntax has been stripped from the "Filename" data. + +See field_list_ for an example in a non-bibliographic context. Also +see the individual examples for the various `bibliographic elements`_. ``doctest_block`` @@ -444,8 +982,8 @@ Children `structural elements`_, and `body elements`_. Analogies - ``document`` is analogous to the HTML "html" element and several - DocBook elements such as "book". + ``document`` is analogous to the HTML "html" element and to + several DocBook elements such as "book". Content Model @@ -468,6 +1006,9 @@ become the document subtitle_. The "docinfo_" may be transformed from an initial field_list_, and "decoration_" is usually constructed programmatically. +See the `%structure.model;`_ parameter entity for details of the body +of a ``document``. + Attributes The ``document`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -553,19 +1094,72 @@ document title:: ``field_name`` ============== -`To be completed`_. +`To be completed`_. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +The ``footer`` element is a container element whose contents are meant +to appear at the bottom of a web page, or repeated at the bottom of +every printed page. Currently the ``footer`` element may contain +processing information (datestamp, a link to Docutils_, etc.). + + +Details +------- + +Category + `Decorative Elements`_ + +Parents + Only the decoration_ element contains ``footer``. + +Children + ``footer`` elements may contain `body elements`_. + +Analogies + There are no direct analogies to ``footer`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``footer`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. -``figure`` -========== +Examples +-------- -`To be completed`_. +reStructuredText source:: + A paragraph. -``footer`` -========== +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: -`To be completed`_. + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. ``footnote`` @@ -589,7 +1183,45 @@ document title:: ``header`` ========== -`To be completed`_. +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. Docutils does not yet make use of the ``header`` element. + + +Details +------- + +Category + `Decorative Elements`_ + +Parents + Only the decoration_ element contains ``header``. + +Children + ``header`` elements may contain `body elements`_. + +Analogies + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``header`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +None. ``hint`` @@ -697,7 +1329,68 @@ document title:: ``organization`` ================ -`To be completed`_. +The ``organization`` element contains the name of document author's +organization, or the organization responsible for the document. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``organization``. + +Children + ``organization`` elements may contain text data plus `inline + elements`_. + +Analogies + ``organization`` is analogous to the DocBook "orgname", + "corpname", or "publishername" elements. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``organization`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``organization``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Organization: Humankind + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <organization> + Humankind + +See docinfo_ for a more complete example, including processing +context. ``paragraph`` @@ -733,7 +1426,72 @@ document title:: ``revision`` ============ -`To be completed`_. +The ``revision`` element contains the revision number of the document. +It can be used alone or in conjunction with version_. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``revision``. + +Children + ``revision`` elements may contain text data plus `inline + elements`_. + +Analogies + ``revision`` is analogous to but simpler than the DocBook + "revision" element. It closely matches the DocBook "revnumber" + element, but in a simpler context. + +Processing + Often used with the RCS/CVS keyword "Revision". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``revision`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``revision``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Version: 1 + :Revision: b + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <version> + 1 + <revision> + b + +See docinfo_ for a more complete example, including processing +context. ``row`` @@ -745,13 +1503,162 @@ document title:: ``section`` =========== -`To be completed`_. +The ``section`` element is the main unit of hierarchy for Docutils +documents. Docutils ``section`` elements are a recursive structure; a +``section`` may contain other ``section`` elements, without limit. +Paragraphs and other body elements may occur before a ``section``, but +not after it. + + +Details +------- + +Category + `Structural Elements`_ + +Parents + The following elements may contain ``section``: document_, + section_ + +Children + ``section`` elements begin with a title_, and may contain `body + elements`_, and transition_ and topic_ elements. + +Analogies + ``section`` is analogous to HTML "div" elements and to DocBook + recursive "section" elements. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, + `%structure.model;`_) + +See the `%structure.model;`_ parameter entity for details of the body +of a ``section``. + +Attributes + The ``section`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%section.elements;`_ parameter entity directly includes + ``section``. The `%structure.model;`_ parameter entity indirectly + includes ``section``. + + +Examples +-------- + +reStructuredText source:: + + Title 1 + ======= + Paragraph 1. + + Title 2 + ------- + Paragraph 2. + + Title 3 + ======= + Paragraph 3. + + Title 4 + ------- + Paragraph 4. + +Complete pseudo-XML_ result after parsing:: + + <document> + <section id="title-1" name="title 1"> + <title> + Title 1 + <paragraph> + Paragraph 1. + <section id="title-2" name="title 2"> + <title> + Title 2 + <paragraph> + Paragraph 2. + <section id="title-3" name="title 3"> + <title> + Title 3 + <paragraph> + Paragraph 3. + <section id="title-4" name="title 4"> + <title> + Title 4 + <paragraph> + Paragraph 4. ``status`` ========== -`To be completed`_. +The ``status`` element contains a status statement for the document, +such as "Draft", "Final", "Work In Progress", etc. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``status``. + +Children + ``status`` elements may contain text data plus `inline elements`_. + +Analogies + ``status`` is analogous to the DocBook "status" element. + +Processing + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``status`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``status``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Status: Work In Progress + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <status> + Work In Progress + +See docinfo_ for a more complete example, including processing +context. ``strong`` @@ -785,7 +1692,7 @@ Category `Structural Subelements`_ Parents - The following elements may contain ``subtitle``: document_ + Only the document_ element contains ``subtitle``. Children ``subtitle`` elements may contain text data plus `inline @@ -793,7 +1700,7 @@ Children Analogies ``subtitle`` is analogous to HTML header elements ("h2" etc.) and - the DocBook "subtitle" element. + to the DocBook "subtitle" element. Processing A document's subtitle is usually rendered smaller than its title_. @@ -911,7 +1818,7 @@ Children Analogies ``title`` is analogous to HTML "title" and header ("h1" etc.) - elements, and DocBook "title" elements. + elements, and to the DocBook "title" element. Content Model @@ -965,7 +1872,69 @@ Pseudo-XML_ fragment from simple parsing:: ``version`` =========== -`To be completed`_. +The ``version`` element contains the version number of the document. +It can be used alone or in conjunction with revision_. + + +Details +------- + +Category + `Bibliographic Elements`_ + +Parents + Only the docinfo_ element contains ``version``. + +Children + ``version`` elements may contain text data plus `inline + elements`_. + +Analogies + ``version`` may be considered analogous to the DocBook "revision", + "revnumber", or "biblioid" elements. + +Processing + Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ + and revision_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``version`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%bibliographic.elements;`_ parameter entity directly includes + ``version``. + + +Examples +-------- + +reStructuredText source:: + + Document Title + ============== + + :Version: 1.1 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document id="document-title" name="document title"> + <title> + Document Title + <docinfo> + <version> + 1.1 + +See docinfo_ for a more complete example, including processing +context. ``warning`` @@ -1242,7 +2211,7 @@ Entity definition: .. parsed-literal:: - author_ | authors_ | organization_ | contact_ + author_ | authors_ | organization_ | contact_ | address_ | version_ | revision_ | status_ | date_ | copyright_ | field_ %additional.bibliographic.elements; @@ -1255,7 +2224,8 @@ wrapper DTDs to extend ``%bibliographic.elements;``. =================== The ``%body.elements;`` parameter entity contains an OR-list of all -`body elements`_. +`body elements`_. ``%body.elements;`` is itself contained within the +`%structure.model;`_ parameter entity. Entity definition: @@ -1373,8 +2343,9 @@ Entity definition: ``%section.elements;`` ====================== -The ``%section.elements;`` parameter entity contains an OR-list of -all section_-equivalent elements. +The ``%section.elements;`` parameter entity contains an OR-list of all +section_-equivalent elements. ``%section.elements;`` is itself +contained within the `%structure.model;`_ parameter entity. Entity definition: @@ -1391,8 +2362,8 @@ by wrapper DTDs to extend ``%section.elements;``. ===================== The ``%structure.model;`` parameter entity is used by document_ and -section_ elements. It encapsulates the section structure of a -document and of parts of that document. See the discussion of the +section_ elements. It encapsulates the hierarchical structure of a +document and of its constituent parts. See the discussion of the `element hierarchy`_ above. Entity definition: -- cgit v1.2.1 From 084f211ed73cd637e15f6af04e9de105edda5170 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 02:49:16 +0000 Subject: Added "address" element. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@571 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 0e328bb34..8947d9367 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -103,7 +103,7 @@ resolve to either an internal or external reference. <!ENTITY % additional.bibliographic.elements ""> <!ENTITY % bibliographic.elements - " author | authors | organization | contact + " author | authors | organization | address | contact | version | revision | status | date | copyright | field %additional.bibliographic.elements; "> @@ -210,12 +210,17 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT author %text.model;> <!ATTLIST author %basic.atts;> -<!ELEMENT authors ((author, organization?, contact?)+)> +<!ELEMENT authors ((author, organization?, address?, contact?)+)> <!ATTLIST authors %basic.atts;> <!ELEMENT organization %text.model;> <!ATTLIST organization %basic.atts;> +<!ELEMENT address %text.model;> +<!ATTLIST address + %basic.atts; + %fixedspace.att;> + <!ELEMENT contact %text.model;> <!ATTLIST contact %basic.atts;> -- cgit v1.2.1 From 13ed20d392cc6c5e727344dad0c3aca8cea125f1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Aug 2002 03:00:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@572 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 +++++---- docs/ref/rst/restructuredtext.txt | 13 +++++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 09441f077..bc367bc71 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -469,13 +469,14 @@ Directives .. include:: path/subdocument.txt :raw: - Implementation ideas: Model the directive parsing on the "images" + Implementation ideas: Model the directive parsing on the "images" directive. A separate, nested parse is probably needed, since it's not a good idea to alter the already-read data. Use ``state.nested_parse()`` (see directives/admonitions.py), and pass - in ``match_titles=1``. The reporting mechanism will have to be - revamped to include the file which is the source of system - messages. + in ``match_titles=1``. The reporting mechanism has been revamped + to include the file which is the source of system messages; a new + ``utils.Reporter`` object will need to be created for each input + source. YAGNI for now: Use C-preprocessor semantics for locating include files? E.g., ``.. include:: file.txt`` will read another file diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 040393276..f96e86fe6 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -837,10 +837,10 @@ DTD elements: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic. When a field list is the first non-comment element in a document -(after the document title, if there is one), it may have certain -specific fields transformed to document bibliographic data. This -bibliographic data corresponds to the front matter of a book, such as -the title page and copyright page. +(after the document title, if there is one), it may have its fields +transformed to document bibliographic data. This bibliographic data +corresponds to the front matter of a book, such as the title page and +copyright page. Certain registered field names (listed below) are recognized and transformed to the corresponding DTD elements, most becoming child @@ -859,6 +859,7 @@ elements are as follows: - "Authors": authors. - "Organization": organization. - "Contact": contact. +- "Address": address. - "Version": version. - "Status": status. - "Date": date. @@ -876,6 +877,10 @@ single name is interpreted as an "Author". If a single name contains a comma, end it with a semicolon to disambiguate: ":Authors: Doe, Jane;". +The "Address" field is for a multi-line surface mailing address. A +specialized form of line block`_ (see `reStructuredText Directives`_), +newlines and whitespace will be preserved. + The "Dedication" and "Abstract" fields may contain arbitrary body elements. Only one of each is allowed. They become topic elements with "Dedication" or "Abstract" titles (or language equivalents) -- cgit v1.2.1 From 25f06d048879c8730dfddb4af70d665cf6b3b339 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:54:33 +0000 Subject: Added cross-references to/from parameter entities. Added "topic", "transition", & "paragraph". 21 down, 63 to go. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@577 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 304 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 282 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 26a65c9cb..d9c54275b 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1396,7 +1396,58 @@ context. ``paragraph`` ============= -`To be completed`_. +The ``paragraph`` element contains the text and inline elements of a +single paragraph, a fundamental building block of documents. + + +Details +------- + +Category + `Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``paragraph``. + +Children + ``paragraph`` elements may contain text data plus `inline + elements`_. + +Analogies + ``paragraph`` is analogous to the HTML "p" element and the DocBook + "para" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``paragraph`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``paragraph``. The `%structure.model;`_ parameter entity + indirectly includes ``paragraph``. + + +Examples +-------- + +reStructuredText source:: + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + A paragraph. ``pending`` @@ -1522,11 +1573,11 @@ Parents Children ``section`` elements begin with a title_, and may contain `body - elements`_, and transition_ and topic_ elements. + elements`_ and transition_ and topic_ elements. Analogies - ``section`` is analogous to HTML "div" elements and to DocBook - recursive "section" elements. + ``section`` is analogous to DocBook recursive "section" elements, + and to HTML "div" elements combined with "h1" etc. title elements. Content Model @@ -1860,13 +1911,146 @@ Pseudo-XML_ fragment from simple parsing:: ``topic`` ========= -`To be completed`_. +The ``topic`` element is a nonrecursive section_-like construct which +may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``topic`` elements +cannot nest inside body elements, so you can't have a ``topic`` inside +a ``table`` or a ``list``, or inside another ``topic``. + + +Details +------- + +Category + `Structural Elements`_ + +Parents + The following elements may contain ``topic``: document_, section_ + +Children + ``topic`` elements begin with a title_ and may contain `body + elements`_. + +Analogies + ``topic`` is analogous to the DocBook "simplesect" element. + +Processing + A ``topic`` element should be set off from the rest of the + document somehow, such as with indentation or a border. + + +Content Model +------------- + +.. parsed-literal:: + + (title_?, + (`%body.elements;`_)+) + +Attributes + The ``topic`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%structure.model;`_ parameter entity directly includes + ``topic``. + + +Examples +-------- + +The `"topic" directive`_ is used to create a ``topic`` element. +reStructuredText source:: + + .. topic:: Title + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <topic> + <title> + Title + <paragraph> + Body. + +.. _"topic" directive: rst/directives.html#topic ``transition`` ============== -`To be completed`_. +The ``transition`` element is commonly seen in novels and short +fiction, as a gap spanning one or more lines, with or without a type +ornament such as a row of asterisks. Transitions separate other body +elements, dividing a section into untitled divisions. A transition +may not begin or end a section or document, nor may two transitions be +immediately adjacent. + +See `Representation of Horizontal Rules`_ below. + + +Details +------- + +Category + `Structural Subelements`_ + +Parents + The following elements may contain ``transition``: document_, + section_ + +Children + ``transition`` is an empty element and has no children. + +Analogies + ``transition`` is analogous to the HTML "hr" element. + +Processing + The ``transition`` element is typically rendered as vertical + whitespace (more than that separating paragraphs), with or without + a horizontal line or row of asterisks. In novels, transitions are + often represented as a row of three well-spaced asterisks with + vertical space above and below. + + +Content Model +------------- + +:: + + EMPTY + +The ``transition`` element has no content; it is a "point element". + +Attributes + The ``transition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%structure.model;`_ parameter entity directly includes + ``transition``. + + +Examples +-------- + +reStructuredText source:: + + Paragraph 1. + + -------- + + Paragraph 2. + +Complete pseudo-XML_ result after parsing:: + + <document> + <paragraph> + Paragraph 1. + <transition> + <paragraph> + Paragraph 2. ``version`` @@ -1997,7 +2181,8 @@ Attribute types: `Attribute type`_: ``%yesorno;``. Default value: none (implies no). The ``anonymous`` attribute is used for unnamed hyperlinks in the -target_ and reference_ elements. +target_ and reference_ elements (via the `%anonymous.att;`_ parameter +entity). ``auto`` @@ -2005,8 +2190,9 @@ target_ and reference_ elements. `Attribute type`_: ``CDATA``. Default value: none. -The ``auto`` attribute is used to indicate an automatically-numbered -footnote_, footnote_reference_ or title_. +The ``auto`` attribute is used to indicate automatically-numbered +footnote_, footnote_reference_ and title_ elements (via the +`%auto.att;`_ parameter entity). ``backrefs`` @@ -2016,7 +2202,7 @@ footnote_, footnote_reference_ or title_. The ``backrefs`` attribute contains a space-separated list of id_ references, used for backlinks from footnote_, citation_, and -system_message_ elements. +system_message_ elements (via the `%backrefs.att;`_ parameter entity). ``class`` @@ -2075,7 +2261,8 @@ one of the `common attributes`_, shared by all Docutils elements. The ``refid`` attribute contains references to `id`_ attributes in other elements. It is used by the target_, reference_, footnote_reference_, citation_reference_, title_ and problematic_ -elements. +elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter +entities). ``refname`` @@ -2088,7 +2275,8 @@ The ``refname`` attribute contains an internal reference to the ``refname`` indicates an indirect target which may resolve to either an internal or external reference. ``refname`` is used by the target_, reference_, footnote_reference_, citation_reference_, and -substitution_reference_ elements. +substitution_reference_ elements (via the `%refname.att;`_ and +`%reference.atts;`_ parameter entities). ``refuri`` @@ -2098,7 +2286,8 @@ substitution_reference_ elements. The ``refuri`` attribute contains an external reference to a URI/URL. It is used by the target_, reference_, footnote_reference_, and -citation_reference_ elements. +citation_reference_ elements (via the `%reference.atts;`_ parameter +entity). ``source`` @@ -2119,10 +2308,11 @@ the `common attributes`_, shared by all Docutils elements. The ``xml:space`` attribute is a standard XML attribute for whitespace-preserving elements. It is used by the literal_block_, -line_block_, doctest_block_, comment_, and raw_ elements. It is a -fixed attribute, meant to communicate to an XML parser that the -element contains significant whitespace. The attribute value should -not be set in a document instance. +line_block_, doctest_block_, comment_, and raw_ elements (via the +`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant +to communicate to an XML parser that the element contains significant +whitespace. The attribute value should not be set in a document +instance. -------------------- @@ -2153,6 +2343,9 @@ Entity definition: anonymous_ %yesorno; #IMPLIED +The reference_ and target_ elements directly employ the +``%anonymous.att;`` parameter entity in their attribute lists. + ``%auto.att;`` ============== @@ -2166,6 +2359,9 @@ Entity definition: auto_ CDATA #IMPLIED +The footnote_, footnote_reference_, and title_ elements directly +employ the ``%auto.att;`` parameter entity in their attribute lists. + ``%backrefs.att;`` ================== @@ -2179,12 +2375,15 @@ Entity definition: backrefs_ IDREFS #IMPLIED +The citation_, footnote_, and system_message_ elements directly employ +the ``%backrefs.att;`` parameter entity in their attribute lists. + ``%basic.atts;`` ================ The ``%basic.atts;`` parameter entity lists attributes common to all -elements. See `Common Attributes`_. +Docutils elements. See `Common Attributes`_. Entity definition: @@ -2219,6 +2418,9 @@ Entity definition: The ``%additional.bibliographic.elements;`` parameter entity can be used by wrapper DTDs to extend ``%bibliographic.elements;``. +Only the docinfo_ element directly employs the +``%bibliographic.elements;`` parameter entity in its content model. + ``%body.elements;`` =================== @@ -2244,6 +2446,16 @@ Entity definition: The ``%additional.body.elements;`` parameter entity can be used by wrapper DTDs to extend ``%body.elements;``. +The ``%body.elements;`` parameter entity is directly employed in the +content models of the following elements: attention_, block_quote_, +caution_, citation_, danger_, definition_, description_, entry_, +error_, field_body_, footer_, footnote_, header_, hint_, important_, +legend_, list_item_, note_, system_message_, tip_, topic_, warning_ + +Via `%structure.model;`_, the ``%body.elements;`` parameter entity is +indirectly employed in the content models of the document_ and +section_ elements. + ``%fixedspace.att;`` ==================== @@ -2258,6 +2470,10 @@ Entity definition: `xml:space`_ (default | preserve) #FIXED 'preserve' +The ``%fixedspace.att;`` parameter entity is directly employed in the +attribute lists of the following elements: address_, comment_, +doctest_block_, line_block_, literal_block_, raw_ + ``%inline.elements;`` ===================== @@ -2278,6 +2494,14 @@ Entity definition: The ``%additional.inline.elements;`` parameter entity can be used by wrapper DTDs to extend ``%inline.elements;``. +Via `%text.model;`_, the ``%inline.elements;`` parameter entity is +indirectly employed in the content models of the following elements: +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, generated_, interpreted_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ + ``%reference.atts;`` ==================== @@ -2297,6 +2521,10 @@ Entity definition: The ``%additional.reference.atts;`` parameter entity can be used by wrapper DTDs to extend ``%additional.reference.atts;``. +The citation_reference_, footnote_reference_, reference_, and target_ +elements directly employ the ``%reference.att;`` parameter entity in +their attribute lists. + ``%refid.att;`` ================ @@ -2310,6 +2538,13 @@ Entity definition: refid_ CDATA #IMPLIED +The title_ and problematic_ elements directly employ the +``%refid.att;`` parameter entity in their attribute lists. + +Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%refname.att;`` ================= @@ -2326,6 +2561,13 @@ Entity definition: refname_ NMTOKENS #IMPLIED +The substitution_reference_ element directly employs the +``%refname.att;`` parameter entity in its attribute list. + +Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%refuri.att;`` ================ @@ -2339,6 +2581,10 @@ Entity definition: refuri_ CDATA #IMPLIED +Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + ``%section.elements;`` ====================== @@ -2357,14 +2603,17 @@ Entity definition: The ``%additional.section.elements;`` parameter entity can be used by wrapper DTDs to extend ``%section.elements;``. +Via `%structure.model;`_, the ``%section.elements;`` parameter entity +is indirectly employed in the content models of the document_ and +section_ elements. + ``%structure.model;`` ===================== -The ``%structure.model;`` parameter entity is used by document_ and -section_ elements. It encapsulates the hierarchical structure of a -document and of its constituent parts. See the discussion of the -`element hierarchy`_ above. +The ``%structure.model;`` parameter entity encapsulates the +hierarchical structure of a document and of its constituent parts. +See the discussion of the `element hierarchy`_ above. Entity definition: @@ -2385,6 +2634,9 @@ Each document_ or section_ contains either: - one or more sections (whose contents are recursively the same as this model). +The `%structure.model;`_ parameter entity is directly employed in the +content models of the document_ and section_ elements. + ``%text.model;`` ================ @@ -2398,6 +2650,14 @@ Entity definition: (#PCDATA | `%inline.elements;`_)* +The ``%text.model;`` parameter entity is directly employed in the +content models of the following elements: address_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, interpreted_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, status_, +strong_, substitution_definition_, substitution_reference_, subtitle_, +target_, term_, title_, version_ + ---------------------- Miscellaneous Topics -- cgit v1.2.1 From 91678c6fc588e7f3e7e4e59aa44197678202c135 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:55:40 +0000 Subject: cleanup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@578 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 8947d9367..244d4c9d0 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -417,13 +417,13 @@ either the string separating it from the `option` (typically either <!ATTLIST label %basic.atts;> <!-- Empty except when used as an inline element. --> -<!ELEMENT target (%text.model;)> +<!ELEMENT target %text.model;> <!ATTLIST target %basic.atts; %reference.atts; %anonymous.att;> -<!ELEMENT substitution_definition (%text.model;)> +<!ELEMENT substitution_definition %text.model;> <!ATTLIST substitution_definition %basic.atts;> <!ELEMENT comment (#PCDATA)> @@ -490,13 +490,13 @@ following caveats: <literal>, and <image> do not support nesting. --> -<!ELEMENT emphasis (%text.model;)> +<!ELEMENT emphasis %text.model;> <!ATTLIST emphasis %basic.atts;> -<!ELEMENT strong (%text.model;)> +<!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> -<!ELEMENT interpreted (%text.model;)> +<!ELEMENT interpreted %text.model;> <!ATTLIST interpreted %basic.atts; role NMTOKEN #IMPLIED @@ -505,7 +505,7 @@ following caveats: <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> -<!ELEMENT reference (%text.model;)> +<!ELEMENT reference %text.model;> <!ATTLIST reference %basic.atts; %reference.atts; @@ -522,17 +522,17 @@ following caveats: %basic.atts; %reference.atts;> -<!ELEMENT substitution_reference (%text.model;)> +<!ELEMENT substitution_reference %text.model;> <!ATTLIST substitution_reference %basic.atts; %refname.att;> -<!ELEMENT problematic (%text.model;)> +<!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; %refid.att;> -<!ELEMENT generated (%text.model;)> +<!ELEMENT generated %text.model;> <!ATTLIST generated %basic.atts;> <!-- -- cgit v1.2.1 From 90d2f18447dd22f0cb2cbd3b6e121ce9b47a0c44 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:56:02 +0000 Subject: crossrefs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@579 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index e9ac3415f..593460421 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -610,11 +610,11 @@ Docstring Extraction Rules b) Immediately following a simple assignment at the top level of a module, class definition, or ``__init__`` method definition, - after any comments. See "Attribute Docstrings" below. + after any comments. See `Attribute Docstrings`_ below. c) Additional string literals found immediately after the docstrings in (a) and (b) will be recognized, extracted, and - concatenated. See "Additional Docstrings" below. + concatenated. See `Additional Docstrings`_ below. d) @@@ 2.2-style "properties" with attribute docstrings? -- cgit v1.2.1 From f534ae91e6ef5e0d5fcb9c042027086f32925eb4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 01:56:39 +0000 Subject: working out some ideas git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@580 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index 758ce05bc..bb61fb2ff 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -34,7 +34,7 @@ The proposed formal public identifier for this DTD is:: <!ENTITY % additional.inline.elements " | package | module | class | method | function - | variable | parameter | type + | variable | parameter | type | attribute | module_attribute | class_attribute | instance_attribute | exception_class | warning_class "> @@ -58,10 +58,12 @@ http://docutils.sourceforge.net/spec/docutils.dtd. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> -<!ELEMENT package_section (package, fullname?, %structure.model;)> +<!ELEMENT package_section + (package, fullname?, import_list?, %structure.model;)> <!ATTLIST package_section %basic.atts;> -<!ELEMENT module_section (module, fullname?, %structure.model;)> +<!ELEMENT module_section + (module, fullname?, import_list?, %structure.model;)> <!ATTLIST module_section %basic.atts;> <!ELEMENT class_section @@ -79,24 +81,32 @@ http://docutils.sourceforge.net/spec/docutils.dtd. <!ATTLIST function_section %basic.atts;> <!ELEMENT module_attribute_section - (module_attribute, initial_value?, fullname?, %structure.model;)> + (attribute, initial_value?, fullname?, %structure.model;)> <!ATTLIST module_attribute_section %basic.atts;> <!ELEMENT class_attribute_section - (class_attribute, initial_value?, fullname?, overrides?, + (attribute, initial_value?, fullname?, overrides?, %structure.model;)> <!ATTLIST class_attribute_section %basic.atts;> <!ELEMENT instance_attribute_section - (instance_attribute, initial_value?, fullname?, overrides?, + (attribute, initial_value?, fullname?, overrides?, %structure.model;)> <!ATTLIST instance_attribute_section %basic.atts;> -<!ELEMENT fullname (package | module | class | method | function)+> +<!ELEMENT fullname + (package | module | class | method | function | attribute)+> <!ATTLIST fullname %basic.atts;> -<!ELEMENT overrides (fullname+)> -<!ATTLIST overrides %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;> @@ -121,6 +131,9 @@ http://docutils.sourceforge.net/spec/docutils.dtd. <!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;> @@ -163,6 +176,18 @@ Also used as the `class_section` identifier/title, and in the %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. -- cgit v1.2.1 From da1ed9c59bcc92e21b45ed894c8850d669b508d0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Aug 2002 02:03:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@585 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 108 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 98 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bc367bc71..63b51c894 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -90,6 +90,16 @@ General after ``references.Hyperlinks.resolve_indirect()`` but before ``references.Footnotes``. + Ideas: + + - A queue, with entries ``(priority, transform, pending=None)``. + - Transform classes can have ``priority`` class attributes. + - Priorities can be numeric. Integers (0..100? 000..999?)? Floats + (would be easier to squeeze in new ones)? + - Each transform would have a unique priority. Use a look-up table? + No, that would require too many imports to construct. Document + transform priorities. + - @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. @@ -145,12 +155,69 @@ Specification PySource Reader --------------- +General: + - Analyze Tony Ibbs' PySource code. - Analyze Doug Hellmann's HappyDoc project. - Take the best ideas and integrate them into Docutils 0.3. +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. + +- 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 + + .. _additional docstrings: pep-0258.html#additional-docstrings + +- 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" + reStructuredText Parser ----------------------- @@ -450,8 +517,7 @@ Directives - _`misc.raw`: See `Raw Data Pass-Through`__ in rst/directives.txt. - __ http://docutils.sf.net/spec/rst/directives.html - #raw-data-pass-through + __ rst/directives.html#raw-data-pass-through - _`misc.include`: ``#include`` one file in another. But how to parse wrt sections, reference names, conflicts? For now, we'll @@ -762,7 +828,7 @@ Front-End Tools - Implement the "sectnum" directive as a command-line option also? -- Add a "--relative-paths" option? +- @@@ Fix the absolute/relative path handling. All references to files (stylesheet, source file [in footer], PEP template) are interpreted relative to the current working directory, @@ -771,14 +837,36 @@ Front-End Tools cd /work html.py -s --stylesheet=default.css /src/test.txt /dst/text.html - This will interpret the stylesheet as "work/default.css", so the - stylesheet link in the HTML (which is in the /dst dir) will read - "../work/default.css", and the source link (-s option) will read - "../src/test.txt". + This will interpret the stylesheet as "/work/default.css", so the + stylesheet link in the HTML (which is written to the /dst dir) will + read "../work/default.css", and the source link (-s option) will + read "../src/test.txt". + + - Perhaps the current behavior should be optional + ("--relative-paths" or something). The default could be not to + process paths at all, just use them verbatim. + + - We could add an "--verbatim-paths" option, which indicates that + paths should not be modified at all. + + - Use variant options, such as "--stylesheet-url=URL", which + wouldn't be interpreted as paths. + + - Redefine "--stylesheet=URL" as an invariant, uninterpreted. Add + an interpreted "--stylesheet-path=PATH". Similarly for + "--pep-stylesheet". The -path variant would override. + + Paths and URLs should be treated differently. Sometimes a relative + path can be treated as the equivalent of a relative URL, but that's + not the case for absolute paths/URLs. The "--pep-template" value is + *not* a URL, but a local file. "--stylesheet" could be either. + Source links (generated in the footer) may depend on how the HTML is + installed. I've been putting .html files in the same directories as + the source .txt files, but there are other ways to do it, and the + directory layout used at runtime may be different from the installed + layout. - Perhaps the current behavior should be optional ("--relative-paths" - or something). The default should probably be not to process paths - at all, just use them verbatim. + Bug reports by Adam Chodorowski and Kenichi Sato. - ``options._destination`` shouldn't have to be set. It's currently needed to calculate relative paths for the stylesheet link. But the -- cgit v1.2.1 From 19bca75de1d1e09b962424cbeb061e8d455e0e54 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Aug 2002 01:25:06 +0000 Subject: Added descriptions of bullet_list, enumerated_list, definition_list, and subelements. 29 down, 55 to go. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@591 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 631 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 608 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index d9c54275b..68f914875 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -328,7 +328,7 @@ Attributes Parameter Entities The `%bibliographic.elements;`_ parameter entity directly includes ``address``. - + Examples @@ -509,7 +509,83 @@ context. ``bullet_list`` =============== -`To be completed`_. +The ``bullet_list`` element contains list_item_ elements which are +uniformly marked with bullets. Bullets are typically simple dingbats +(symbols) such as circles and squares. + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``bullet_list``. + +Children + ``bullet_list`` elements contain one or more list_item_ elements. + +Analogies + ``bullet_list`` is analogous to the HTML "ul" element and to the + DocBook "itemizedlist" element. HTML's "ul" is short for + "unordered list", which we consider to be a misnomer. "Unordered" + implies that the list items may be randomly rearranged without + affecting the meaning of the list. Bullet lists *are* often + ordered; the ordering is simply left implicit. + +Processing + Each list item should begin a new vertical block, prefaced by a + bullet/dingbat. + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_+) + +Attributes + The ``bullet_list`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus bullet_. + + ``bullet`` is used to record the style of bullet from the input + data. In reStructuredText, it contains one of "-", "+", or "*". + It may be ignored in processing. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``bullet_list``. The `%structure.model;`_ parameter entity + indirectly includes ``bullet_list``. + + +Examples +-------- + +reStructuredText source:: + + - Item 1, paragraph 1. + + Item 1, paragraph 2. + + - Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <bullet_list bullet="-"> + <list_item> + <paragraph> + Item 1, paragraph 1. + <paragraph> + Item 1, paragraph 2. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. ``caption`` @@ -539,7 +615,72 @@ context. ``classifier`` ============== -`To be completed`_. +The ``classifier`` element contains the classification or type of the +term_ being defined in a definition_list_. For example, it can be +used to indicate the type of a variable. + + +Details +------- + +Category + `Body Subelements`_ (simple) + +Parents + Only the definition_list_item_ element contains ``classifier``. + +Children + ``classifier`` elements may contain text data plus `inline elements`_. + +Analogies + ``classifier`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``classifier`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +Here is a hypothetical data dictionary. reStructuredText source:: + + name : string + Customer name. + i : int + Temporary index variable. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + name + <classifier> + string + <definition> + <paragraph> + Customer name. + <definition_list_item> + <term> + i + <classifier> + int + <definition> + <paragraph> + Temporary index variable. ``colspec`` @@ -782,9 +923,9 @@ Children ``decoration`` elements may contain `decorative elements`_. Analogies - There are no direct analogies to ``decoration`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. + There are no direct analogies to ``decoration`` in HTML or in + DocBook. Equivalents are typically constructed from primitives + and/or generated by the processing system. Processing See the individual `decorative elements`_. @@ -827,19 +968,213 @@ setting has been supplied:: ``definition`` ============== -`To be completed`_. +The ``definition`` element is a container for the body elements used +to define a term_ in a definition_list_. + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + Only definition_list_item_ elements contain ``definition``. + +Children + ``definition`` elements may contain `body elements`_. + +Analogies + ``definition`` is analogous to the HTML "dd" element and to the + DocBook "listitem" element (inside a "variablelistentry" element). + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``definition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. ``definition_list`` =================== -`To be completed`_. +The ``definition_list`` element contains a list of terms and their +definitions. It can be used for glossaries or dictionaries, to +describe or classify things, for dialogues, or to itemize subtopics +(such as in this reference). + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``definition_list``. + +Children + ``definition_list`` elements contain one or more + definition_list_item_ elements. + +Analogies + ``definition_list`` is analogous to the HTML "dl" element and to + the DocBook "variablelist" element. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (definition_list_item_+) + +Attributes + The ``definition_list`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``definition_list``. The `%structure.model;`_ parameter entity + indirectly includes ``definition_list``. + + +Examples +-------- + +reStructuredText source:: + + Term + Definition. + + Term : classifier + The ' : ' indicates a classifier in + definition list item terms only. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Term + <definition> + <paragraph> + Definition. + <definition_list_item> + <term> + Term + <classifier> + classifier + <definition> + <paragraph> + The ' : ' indicates a classifier in + definition list item terms only. + +See definition_list_item_ and classifier_ for further examples. ``definition_list_item`` ======================== -`To be completed`_. +The ``definition_list_item`` element contains a single +term_/definition_ pair (with optional classifier_). + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + Only the definition_list_ element contains + ``definition_list_item``. + +Children + ``definition_list_item`` elements each contain a single term_, + an optional classifier_, and a definition_. + +Analogies + ``definition_list_item`` is analogous to the DocBook + "variablelistentry" element. + +Processing + The optional classifier_ can be rendered differently from the + term_. They should be separated visually, typically by spaces + plus a colon or dash. + + +Content Model +------------- + +.. parsed-literal:: + + (term_, classifier_?, definition_) + +Attributes + The ``definition_list_item`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + Tyrannosaurus Rex : carnivore + Big and scary; the "Tyrant King". + + Brontosaurus : herbivore + Small at one end, big in the middle, + and small again at the other end. + + -- Anne Elk, Miss + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Tyrannosaurus Rex + <classifier> + carnivore + <definition> + <paragraph> + Big and scary; the "Tyrant King". + <definition_list_item> + <term> + Brontosaurus + <classifier> + herbivore + <definition> + <paragraph> + Small at one end, big in the middle, + and small again at the other end. + <paragraph> + -- Anne Elk, Miss + +See definition_list_ and classifier_ for further examples. ``description`` @@ -1058,7 +1393,107 @@ document title:: ``enumerated_list`` =================== -`To be completed`_. +The ``enumerated_list`` element contains list_item_ elements which are +uniformly marked with enumerator labels. + + +Details +------- + +Category + `Compound Body Elements`_ + +Parents + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``enumerated_list``. + +Children + ``enumerated_list`` elements contain one or more list_item_ + elements. + +Analogies + ``enumerated_list`` is analogous to the HTML "ol" element and to + the DocBook "orderedlist" element. + +Processing + Each list item should begin a new vertical block, prefaced by a + enumeration marker (such as "1."). + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_+) + +Attributes + The ``enumerated_list`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus enumtype_, + prefix_, suffix_, and start_. + + ``enumtype`` is used to record the intended enumeration sequence, + one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), + "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., + mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., + MMMMCMXCIX [4999]). + + ``prefix`` stores the formatting characters used before the + enumerator. In documents originating from reStructuredText data, + it will contain either "" (empty string) or "(" (left + parenthesis). It may or may not affect processing. + + ``suffix`` stores the formatting characters used after the + enumerator. In documents originating from reStructuredText data, + it will contain either "." (period) or ")" (right parenthesis). + Depending on the capabilities of the output format, this attribute + may or may not affect processing. + + ``start`` contains the ordinal value of the first item in the + list, in decimal. For lists beginning at value 1 ("1", "a", "A", + "i", or "I"), this attribute may be omitted. + +Parameter Entities + The `%body.elements;`_ parameter entity directly includes + ``enumerated_list``. The `%structure.model;`_ parameter entity + indirectly includes ``enumerated_list``. + + +Examples +-------- + +reStructuredText source:: + + 1. Item 1. + + (A) Item A. + (B) Item B. + (C) Item C. + + 2. Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Item 1. + <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> + <list_item> + <paragraph> + Item A. + <list_item> + <paragraph> + Item B. + <list_item> + <paragraph> + Item C. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. ``error`` @@ -1269,7 +1704,73 @@ None. ``list_item`` ============= -`To be completed`_. +The ``list_item`` element is a container for the elements of a list +item. + + +Details +------- + +Category + `Body Subelements`_ (compound) + +Parents + The bullet_list_ and enumerated_list_ elements contain + ``list_item``. + +Children + ``list_item`` elements may contain `body elements`_. + +Analogies + ``list_item`` is analogous to the HTML "li" element and to the + DocBook "listitem" element. + +Processing + See bullet_list_ or enumerated_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +Attributes + The ``list_item`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText source:: + + 1. Outer list, item 1. + + * Inner list, item 1. + * Inner list, item 2. + + 2. Outer list, item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Outer list, item 1. + <bullet_list bullet="*"> + <list_item> + <paragraph> + Inner list, item 1. + <list_item> + <paragraph> + Inner list, item 2. + <list_item> + <paragraph> + Outer list, item 2. + +See bullet_list_ or enumerated_list_ for further examples. ``literal`` @@ -1404,7 +1905,7 @@ Details ------- Category - `Body Elements`_ + `Simple Body Elements`_ Parents All elements employing the `%body.elements;`_ or @@ -1416,8 +1917,8 @@ Children elements`_. Analogies - ``paragraph`` is analogous to the HTML "p" element and the DocBook - "para" elements. + ``paragraph`` is analogous to the HTML "p" element and to the + DocBook "para" elements. Content Model @@ -1609,15 +2110,15 @@ reStructuredText source:: Title 1 ======= Paragraph 1. - + Title 2 ------- Paragraph 2. - + Title 3 ======= Paragraph 3. - + Title 4 ------- Paragraph 4. @@ -1826,7 +2327,47 @@ attributes are stored in the ``subtitle`` element. ``term`` ======== -`To be completed`_. +The ``term`` element contains a word or phrase being defined in a +definition_list_. + + +Details +------- + +Category + `Body Subelements`_ (simple) + +Parents + Only the definition_list_item_ element contains ``term``. + +Children + ``term`` elements may contain text data plus `inline elements`_. + +Analogies + ``term`` is analogous to the HTML "dt" element and to the DocBook + "term" element. + +Processing + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +Attributes + The ``term`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. ``tgroup`` @@ -2038,9 +2579,9 @@ Examples reStructuredText source:: Paragraph 1. - + -------- - + Paragraph 2. Complete pseudo-XML_ result after parsing:: @@ -2174,6 +2715,9 @@ Attribute types: is a parameter entity which resolves to a ``NMTOKEN`` attribute type. +enumeration + The attribute value may be one of a specified list of values. + ``anonymous`` ============= @@ -2205,6 +2749,14 @@ references, used for backlinks from footnote_, citation_, and system_message_ elements (via the `%backrefs.att;`_ parameter entity). +``bullet`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``bullet`` attribute is used in the bullet_list_ element. + + ``class`` ========= @@ -2230,6 +2782,15 @@ not both. ``dupname`` is one of the `common attributes`_, shared by all Docutils elements. +``enumtype`` +============ + +`Attribute type`_: enumeration, one of "arabic", "loweralpha", +"upperalpha", "lowerroman", or "upperroman". Default value: none. + +The ``enumtype`` attribute is used in the enumerated_list_ element. + + ``id`` ====== @@ -2253,6 +2814,14 @@ of the ``name`` or ``dupname`` attributes, but not both. ``name`` is one of the `common attributes`_, shared by all Docutils elements. +``prefix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``prefix`` attribute is used in the enumerated_list_ element. + + ``refid`` ========= @@ -2300,6 +2869,22 @@ source text that was used to produce the document tree. It is one of the `common attributes`_, shared by all Docutils elements. +``start`` +========= + +`Attribute type`_: ``%number;``. Default value: none. + +The ``start`` attribute is used in the enumerated_list_ element. + + +``suffix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``suffix`` attribute is used in the enumerated_list_ element. + + ``xml:space`` ============= @@ -2315,9 +2900,9 @@ whitespace. The attribute value should not be set in a document instance. --------------------- - Parameter Entities --------------------- +---------------------------- + Parameter Entity Reference +---------------------------- .. contents:: :local: :depth: 1 -- cgit v1.2.1 From 473739633ba059db86d233b2b383bc0108d65083 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Aug 2002 01:27:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@592 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 45 --------------------------------------------- docs/user/tools.txt | 24 ++++++++++++++++++++---- 2 files changed, 20 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 63b51c894..548f96ab5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -828,51 +828,6 @@ Front-End Tools - Implement the "sectnum" directive as a command-line option also? -- @@@ Fix the absolute/relative path handling. - - All references to files (stylesheet, source file [in footer], PEP - template) are interpreted relative to the current working directory, - and adjusted relative to the destination directory. For example:: - - cd /work - html.py -s --stylesheet=default.css /src/test.txt /dst/text.html - - This will interpret the stylesheet as "/work/default.css", so the - stylesheet link in the HTML (which is written to the /dst dir) will - read "../work/default.css", and the source link (-s option) will - read "../src/test.txt". - - - Perhaps the current behavior should be optional - ("--relative-paths" or something). The default could be not to - process paths at all, just use them verbatim. - - - We could add an "--verbatim-paths" option, which indicates that - paths should not be modified at all. - - - Use variant options, such as "--stylesheet-url=URL", which - wouldn't be interpreted as paths. - - - Redefine "--stylesheet=URL" as an invariant, uninterpreted. Add - an interpreted "--stylesheet-path=PATH". Similarly for - "--pep-stylesheet". The -path variant would override. - - Paths and URLs should be treated differently. Sometimes a relative - path can be treated as the equivalent of a relative URL, but that's - not the case for absolute paths/URLs. The "--pep-template" value is - *not* a URL, but a local file. "--stylesheet" could be either. - Source links (generated in the footer) may depend on how the HTML is - installed. I've been putting .html files in the same directories as - the source .txt files, but there are other ways to do it, and the - directory layout used at runtime may be different from the installed - layout. - - Bug reports by Adam Chodorowski and Kenichi Sato. - -- ``options._destination`` shouldn't have to be set. It's currently - needed to calculate relative paths for the stylesheet link. But the - client shouldn't have to deal with it. It's a file-bias that needs - fixing. - Project Policies ================ diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 565c4d3ea..3534440f0 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -405,12 +405,20 @@ pep_home (PEP/HTML Writer.) Home URL prefix for PEPs. Default: current directory ("."). Options: ``--pep-home``. -------------------- ------------------------------------------------ -pep_stylesheet (PEP/HTML Writer.) Path to CSS stylesheet - [#pwd]_. Overrides HTML stylesheet +pep_stylesheet (PEP/HTML Writer.) CSS stylesheet URL, used + verbatim. Overrides HTML stylesheet (``--stylesheet``). Default: None. Options: ``--pep-stylesheet``. -------------------- ------------------------------------------------ +pep_stylesheet_path (PEP/HTML Writer.) Path to CSS stylesheet + [#pwd]_. Overrides HTML stylesheet + (``--stylesheet``) and PEP stylesheet + (``--pep-stylesheet``). + + Default: None. Options: + ``--pep-stylesheet-path``. +-------------------- ------------------------------------------------ pep_template (PEP/HTML Writer.) Path to PEP template file [#pwd]_. @@ -449,16 +457,23 @@ source_link Include a "View document source" link in the ``--source-link, --no-source-link``. -------------------- ------------------------------------------------ source_url An explicit URL for a "View document source" - link. + link, used verbatim. Default: compute if source_link (None). Options: ``--source-uri, --no-source-link``. -------------------- ------------------------------------------------ -stylesheet (HTML Writer.) Path to CSS stylesheet [#pwd]_. +stylesheet (HTML Writer.) CSS stylesheet URL, used + verbatim. Default: "default.css". Options: ``--stylesheet``. -------------------- ------------------------------------------------ +stylesheet-path (HTML Writer.) Path to CSS stylesheet [#pwd]_. + Overrides "stylesheet" URL option + (``--stylesheet``). + + Default: None. Options: ``--stylesheet``. +-------------------- ------------------------------------------------ toc_backlinks Enable backlinks from section titles to table of contents entries ("entry"), to the top of the TOC ("top"), or disable ("none"). @@ -473,6 +488,7 @@ warning_stream Path to a file for the output of system messages Default: stderr (None). Options: ``--warnings``. +-------------------- ------------------------------------------------ **For Internal Use Only** (setting these in a config file has no effect) ---------------------------------------------------------------------- _directories (``buildhtml.py`` front end.) List of paths to -- cgit v1.2.1 From 244db0bd4cc8375e7347d9cffdfc3f881aae71e6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Aug 2002 16:00:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@594 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 ++ docs/ref/rst/restructuredtext.txt | 9 +++++---- 2 files changed, 7 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3e9d2da41..c44ca0fb7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -474,12 +474,14 @@ For example, the following input would be passed untouched by an HTML Writer:: .. raw:: html + <hr width=50 size=10> A LaTeX Writer could insert the following raw content into its output stream:: .. raw:: latex + \documentclass[twocolumn]{article} diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f96e86fe6..9c6996e80 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1790,10 +1790,11 @@ used after the directive type for these reasons: a literal block, and a level-3 (error) system message generated. Thus "::" is a natural choice. -Any text on the first line after the directive indicator is directive -data. The interpretation of directive data is up to the directive -code. Directive data may be interpreted as arguments to the -directive, or simply as the first line of the directive's text block. +Any text on the first line of the directive, after the directive +indicator, is directive data. The interpretation of directive data is +up to the directive code. Directive data may be interpreted as +arguments to the directive, or simply as the first line of the +directive's text block. Actions taken in response to directives and the interpretation of text in the directive block or subsequent text block(s) are -- cgit v1.2.1 From b1d16b704b41ea75a80f55853131d4d74f3c2b9f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:35:14 +0000 Subject: changed field lists to bullet lists; minor edit git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@595 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 3534440f0..30ff3a88c 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -55,9 +55,9 @@ The Tools buildhtml.py ------------ -:Readers: Standalone, PEP -:Parser: reStructuredText -:Writers: HTML, PEP/HTML +* Readers: Standalone, PEP +* Parser: reStructuredText +* Writers: HTML, PEP/HTML Use ``buildhtml.py`` to generate .html from all the .txt files (including PEPs) in each <directory> given, and their subdirectories @@ -92,9 +92,9 @@ altogether. html.py ------- -:Reader: Standalone -:Parser: reStructuredText -:Writer: HTML +* Reader: Standalone +* Parser: reStructuredText +* Writer: HTML The ``html.py`` front end reads standalone reStructuredText source files and produces HTML 4 (XHTML 1) output compatible with modern @@ -146,9 +146,9 @@ incremental experimentation. pep.py ------ -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML +* Reader: PEP +* Parser: reStructuredText +* Writer: PEP/HTML ``pep.py`` reads a new-style PEP (marked up with reStructuredText) and produces HTML. It requires a template file and a stylesheet. By @@ -169,9 +169,9 @@ for more information. pep2html.py ----------- -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML +* Reader: PEP +* Parser: reStructuredText +* Writer: PEP/HTML ``pep2html.py`` is a modified version of the original script by Fredrik Lundh, with support for Docutils added. It reads the @@ -190,9 +190,9 @@ files. If no arguments are given, all files of the form docutils-xml.py --------------- -:Reader: Standalone -:Parser: reStructuredText -:Writer: XML (Docutils native) +* Reader: Standalone +* Parser: reStructuredText +* Writer: XML (Docutils native) The ``docutils-xml.py`` front end produces Docutils-native XML output. This can be transformed with standard XML tools such as XSLT @@ -202,12 +202,12 @@ processors into arbitrary final forms. publish.py ---------- -:Reader: Standalone -:Parser: reStructuredText -:Writer: Pseudo-XML +* Reader: Standalone +* Parser: reStructuredText +* Writer: Pseudo-XML -``publish.py`` is used for debugging the Docutils Reader -> Transform --> Writer pipeline. It produces a compact pretty-printed +``publish.py`` is used for debugging the Docutils Reader to Transform +to Writer pipeline. It produces a compact pretty-printed "pseudo-XML", where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given. @@ -216,9 +216,9 @@ attributes for any leftover "pending" elements are also given. quicktest.py ------------ -:Reader: N/A -:Parser: reStructuredText -:Writer: N/A +* Reader: N/A +* Parser: reStructuredText +* Writer: N/A The ``quicktest.py`` tool is used for testing the reStructuredText parser. It does not use a Docutils Reader or Writer or the standard -- cgit v1.2.1 From 3f7e74c966e10eae283a349bcb80055fc8723da2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:39:56 +0000 Subject: Updated directive description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@596 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 104 +++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 42 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 9c6996e80..6cb80cf1f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -773,11 +773,11 @@ DTD elements: field_list, field, field_name, field_argument, field_body. Field lists are most often used as part of an extension syntax, such -as attributes for directives_, or database-like records meant for -further processing. They are not intended to be an alternative to -definition lists. Applications of reStructuredText may recognize -field names and transform fields or field bodies in certain contexts. -See `Bibliographic Fields`_ below for one example, or the "image" +as options for directives_, or database-like records meant for further +processing. They are not intended to be an alternative to definition +lists. Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts. See +`Bibliographic Fields`_ below for one example, or the "image" directive in `reStructuredText Directives`_ for another. Field lists are mappings from field names to field bodies, modeled on @@ -1305,9 +1305,9 @@ column. In that case, that line of text is parsed as a continuation line. For this reason, cells in the first column of new rows (*not* continuation lines) *must* contain some text; blank cells would lead to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output. Also, this mechanism -limits cells in the first column to only one line of text. Use `grid -tables`_ if this limitation is unacceptable. +will be omitted from the processed output (see Comments_ below). +Also, this mechanism limits cells in the first column to only one line +of text. Use `grid tables`_ if this limitation is unacceptable. Underlines of '-' may also be used to visually separate rows, even if there are no column spans. This is especially useful in long tables, @@ -1775,10 +1775,11 @@ An admonition (note, caution, etc.) contains other body elements:: - Here is a bullet list. Directives are indicated by an explicit markup start (".. ") followed -by the directive type, two colons, and whitespace. Directive types -are case-insensitive single words (alphanumerics plus internal -hyphens, underscores, and periods; no whitespace). Two colons are -used after the directive type for these reasons: +by the directive type, two colons, and whitespace (together called the +"directive marker"). Directive types are case-insensitive single +words (alphanumerics plus internal hyphens, underscores, and periods; +no whitespace). Two colons are used after the directive type for +these reasons: - To avoid clashes with common comment text like:: @@ -1790,41 +1791,60 @@ used after the directive type for these reasons: a literal block, and a level-3 (error) system message generated. Thus "::" is a natural choice. -Any text on the first line of the directive, after the directive -indicator, is directive data. The interpretation of directive data is -up to the directive code. Directive data may be interpreted as -arguments to the directive, or simply as the first line of the -directive's text block. +The directive block is consists of any text on the first line of the +directive after the directive marker, and any subsequent indented +text. The interpretation of the directive block is up to the +directive code. There are three logical parts to the directive block: + +1. Directive arguments. +2. Directive options. +3. Directive content. + +Individual directives can employ any combination of these parts. +Directive arguments can be filesystem paths, URLs, title text, etc. +Directive options are indicated using `field lists`_; the field names +and contents are directive-specific. Argumens and options must form a +contiguous block beginning on the first or second line of the +directive; a blank line indicates the beginning of the directive +content block. If either arguments and/or options are employed by the +directive, a blank line must separate them from the directive content. +The "figure" directive employs all three parts:: + + .. figure:: larch.png + :scale: 50 + + The larch. + +Simple directives may not require any content. If a directive that +does not employ a content block is followed by indented text anyway, +it is an error. If a block quote should immediately follow a +directive, use an empty comment in-between (see Comments_ below). Actions taken in response to directives and the interpretation of text -in the directive block or subsequent text block(s) are -directive-dependent. Indented text following a directive may be -interpreted as a directive block. Simple directives may not require -any text beyond the directive data (if that), and will not process any -following indented text. - -Directives are meant for the arbitrary processing of their contents -(the directive data & text block), which can be transformed into -something possibly unrelated to the original text. It may also be -possible for directives to be used as pragmas, to modify the behavior -of the parser, such as to experiment with alternate syntax. There is -no parser support for this functionality at present; if a reasonable -need for pragma directives is found, they may be supported. - -Directives do not survive as "directive" elements past the parsing -stage; they are a *parser construct* only, and have no intrinsic -meaning outside of reStructuredText. Instead, the parser will -transform recognized directives into (possibly specialized) document -elements. Unknown directives will trigger level-3 (error) system -messages. +in the directive content block or subsequent text block(s) are +directive-dependent. See `reStructuredText Directives`_ for details. + +Directives are meant for the arbitrary processing of their contents, +which can be transformed into something possibly unrelated to the +original text. It may also be possible for directives to be used as +pragmas, to modify the behavior of the parser, such as to experiment +with alternate syntax. There is no parser support for this +functionality at present; if a reasonable need for pragma directives +is found, they may be supported. + +Directives do not generate "directive" elements; they are a *parser +construct* only, and have no intrinsic meaning outside of +reStructuredText. Instead, the parser will transform recognized +directives into (possibly specialized) document elements. Unknown +directives will trigger level-3 (error) system messages. Syntax diagram:: - +-------+--------------------------+ - | ".. " | directive type "::" data | - +-------+ directive block | - | | - +--------------------------+ + +-------+-------------------------------+ + | ".. " | directive type "::" directive | + +-------+ block | + | | + +-------------------------------+ Substitution Definitions -- cgit v1.2.1 From d109beb80e5e9429ee8ce649dd5d43e65e97e31e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:40:56 +0000 Subject: Added directive: "include". Formalized descriptions of directive details. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@598 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 274 +++++++++++++++++++++++++++++++------------- 1 file changed, 194 insertions(+), 80 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index c44ca0fb7..5f38e9503 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -11,17 +11,22 @@ reStructuredText parser. Directives have the following syntax:: - +-------+--------------------------+ - | ".. " | directive type "::" data | - +-------+ directive block | - | | - +--------------------------+ + +-------+-------------------------------+ + | ".. " | directive type "::" directive | + +-------+ block | + | | + +-------------------------------+ Directives begin with an explicit markup start (two periods and a -space), followed by the directive type, two colons, optional directive -data (on the same line as the directive type) and an optional -directive block (on subsequent lines). The directive block is -indented, aligned with the left edge of the directive type. +space), followed by the directive type and two colons (collectively, +the "directive marker"). The directive block begins immediately after +the directive marker, and includes all subsequent indented lines. The +directive block is divided into arguments, options (a field list), and +content. See the Directives_ section in the `reStructuredText Markup +Specification`_ for syntax details. + +.. _Directives: ./reStructuredText.html#directives +.. _reStructuredText Markup Specification: ./reStructuredText.html .. contents:: @@ -31,11 +36,17 @@ indented, aligned with the left edge of the directive type. Admonitions ------------- -DTD elements: attention, caution, danger, error, hint, important, -note, tip, warning. +* Directive Types: "attention", "caution", "danger", "error", "hint", + "important", "note", "tip", "warning" + +* DTD Elements: attention, caution, danger, error, hint, important, + note, tip, warning + +* Directive Block: -Directive block: directive data and all following indented text -are interpreted as body elements. + - Arguments: None. + - Options: None. + - Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -90,25 +101,30 @@ There are two image directives: "image" and "figure". Image ===== -DTD element: image. +* Directive Type: "image" -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as image URI and optional -attributes. +* DTD Element: image + +* Directive Block: + + - Arguments: One, required (image URI). + - Options: Possible. + - Content: None. An "image" is a simple picture:: .. image:: picture.png -The URI for the image source file is specified in the directive data. -As with hyperlink targets, the image URI may begin on the same line as -the explicit markup start and target name, or it may begin in an -indented text block immediately following, with no intervening blank -lines. If there are multiple lines in the link block, they are -stripped of leading and trailing whitespace and joined together. +The URI for the image source file is specified in the directive +argument. As with hyperlink targets, the image URI may begin on the +same line as the explicit markup start and target name, or it may +begin in an indented text block immediately following, with no +intervening blank lines. If there are multiple lines in the link +block, they are stripped of leading and trailing whitespace and joined +together. Optionally, the image link block may end with a flat field list, the -_`image attributes`. For example:: +_`image options`. For example:: .. image:: picture.jpeg :height: 100 @@ -116,7 +132,7 @@ _`image attributes`. For example:: :scale: 50 :alt: alternate text -The following attributes are recognized: +The following options are recognized: ``alt`` : text Alternate text: a short description of the image, displayed by @@ -136,15 +152,19 @@ The following attributes are recognized: Figure ====== -DTD elements: figure, image, caption, legend. +* Directive Type: "figure" + +* DTD Elements: figure, image, caption, legend -Directive block: directive data and all following indented text are -interpreted as an image URI, optional attributes, a caption, and an -optional legend. +* Directive Block: -A "figure" consists of image_ data (optionally including `image -attributes`_), an optional caption (a single paragraph), and an -optional legend (arbitrary body elements):: + - Arguments: One, required (image URI). + - Options: Possible. + - Content: Interpreted as the figure caption and an optional legend. + +A "figure" consists of image_ data (including `image options`_), an +optional caption (a single paragraph), and an optional legend +(arbitrary body elements):: .. figure:: picture.png :scale: 50 @@ -166,7 +186,7 @@ optional legend (arbitrary body elements):: | .. image:: peak.png | Mountain | +-----------------------+-----------------------+ -There must be a blank line before the caption paragraph and before the +There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. @@ -178,19 +198,25 @@ legend. To specify a legend without a caption, use an empty comment Topic ===== -DTD element: topic. +* Directive Type: "topic" + +* DTD Element: topic + +* Directive Block: -Directive block: directive data and all following indented lines are -collected. The first line is interpreted as the topic title; the -second line must be blank. All subsequent lines are the topic body, -interpreted as body elements. + - Arguments: None. + - Options: None. + - Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body -elements (including topics) may not contain nested topics. For -example:: +elements (including topics) may not contain nested topics. + +The first line of the directive content block is interpreted as the +topic title; the second line must be blank. All subsequent lines make +up the topic body, interpreted as body elements. For example:: topic:: Topic Title @@ -202,10 +228,15 @@ example:: Line Block ========== -DTD element: line_block. +* Directive Type: "line-block" + +* DTD Element: line_block + +* Directive Block: -Directive block: directive data and all following indented text become -the body of the line block. + - Arguments: None. + - Options: None. + - Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -230,10 +261,15 @@ significant. For example, here's a classic:: Parsed Literal Block ==================== -DTD element: literal_block. +* Directive Type: "literal-block" -Directive block: directive data and all following indented text become -the body of the literal block. +* DTD Element: literal_block + +* Directive Block: + + - Arguments: None. + - Options: None. + - Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -242,6 +278,7 @@ typically in a typewriter/monospaced typeface, like an ordinary literal block. Parsed literal blocks are useful for adding hyperlinks to code examples. However, care must be taken with the text, because inline markup is recognized; there is no protection from parsing. +Backslash-escapes may be necessary in places. For example, all the element names in this content model are links:: @@ -261,16 +298,20 @@ For example, all the element names in this content model are links:: Table of Contents ================= -DTD elements: pending, topic. +* Directive Type: "contents" + +* DTD Elements: pending, topic -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as the topic title and optional -attributes. +* Directive Block: + + - Arguments: One, optional: title. + - Options: Possible. + - Content: None. The "contents" directive inserts a table of contents (TOC) in two passes: initial parse and transform. During the initial parse, a "pending" element is generated which acts as a placeholder, storing -the TOC title and any attributes internally. At a later stage in the +the TOC title and any options internally. At a later stage in the processing, the "pending" element is replaced by a "topic" element, a title and the table of contents proper. @@ -290,17 +331,17 @@ The title may span lines, although it is not recommended:: .. contents:: Here's a very long Table of Contents title -Attributes may be specified for the directive, using a field list:: +Options may be specified for the directive, using a field list:: .. contents:: Table of Contents :depth: 2 -If the default title is to be used, the attribute field list may begin +If the default title is to be used, the options field list may begin on the same line as the directive marker:: .. contents:: :depth: 2 -The following attributes are recognized: +The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of @@ -317,26 +358,31 @@ The following attributes are recognized: Automatic Section Numbering =========================== -DTD elements: pending, generated. +* Directive Type: "sectnum" or "section-autonumbering" (synonyms) + +* DTD Elements: pending, generated + +* Directive Block: -Directive block: directive data and following indented lines (up to -the first blank line) are interpreted as optional attributes. + - Arguments: None. + - Options: Possible. + - Content: None. The "sectnum" (or "section-autonumbering") directive automatically -numbers sections and subsections in a document. Section numbers of -the "multiple enumeration" form, where each level has a number, +numbers sections and subsections in a document. Section numbers are +of the "multiple enumeration" form, where each level has a number, separated by periods. For example, the title of section 1, subsection -2, subsubsection 3 would have "1.2.3" prefixed. +2, subsubsection 3 would have "1.2.3" prefixed. -The "sectnum" directive does its work in two passes: initial parse and -transform. During the initial parse, a "pending" element is generated -which acts as a placeholder, storing any attributes internally. At a -later stage in the processing, the "pending" element triggers a +The "sectnum" directive does its work in two passes: the initial parse +and a transform. During the initial parse, a "pending" element is +generated which acts as a placeholder, storing any options internally. +At a later stage in the processing, the "pending" element triggers a transform, which adds section numbers to titles. Section numbers are enclosed in a "generated" element, and titles have their "auto" attribute set to "1". -The following attributes are recognized: +The following options are recognized: ``depth`` : integer The number of section levels that are numbered by this directive. @@ -350,9 +396,15 @@ The following attributes are recognized: Target Footnotes ================ -DTD elements: pending, footnote, footnote_reference. +* Directive Type: "target-notes" -Directive block: unused; directive data must be empty. +* DTD Elements: pending, footnote, footnote_reference + +* Directive Block must be empty: + + - Arguments: None. + - Options: None. + - Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -366,7 +418,15 @@ Footnotes **NOT IMPLEMENTED YET** -DTD elements: pending, topic. +* Directive Type: "footnotes" + +* DTD Elements: pending, topic + +* Directive Block: + + - Arguments: None? + - Options: Possible? + - Content: None. @@@ @@ -376,7 +436,15 @@ Citations **NOT IMPLEMENTED YET** -DTD elements: pending, topic. +* Directive Type: "citations" + +* DTD Elements: pending, topic + +* Directive Block: + + - Arguments: None? + - Options: Possible? + - Content: None. @@@ @@ -388,10 +456,17 @@ DTD elements: pending, topic. Meta ==== -Non-standard element: meta. +. + +* Directive Type: "meta" + +* DTD Element: meta (non-standard) + +* Directive Block: -Directive block: directive data and following indented lines (up to -the first blank line) are parsed for a flat field list. + - Arguments: None. + - Options: None. + - Content: Must contain a flat field list. The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web @@ -452,20 +527,48 @@ Non-standard element: imagemap. Miscellaneous --------------- +Including an External Fragment +============================== + +**NOT IMPLEMENTED YET** + +* Directive Type: "include" + +* DTD Elements: depend on data being included + +* Directive Block: + + - Arguments: One, required (path to include file). + - Options: None. + - Content: None. + +The "include" directive reads a reStructuredText-formatted text file +and parses it in the current document's context at the point of the +directive. For example:: + + .. include:: inclusion.txt + + Raw Data Pass-Through ===================== **NOT IMPLEMENTED YET** -DTD element: pending. +* Directive Type: "raw" + +* DTD Element: pending -Directive block: the directive data is interpreted as an output format -type, and all following indented text is stored verbatim, -uninterpreted. +* Directive Block: + + - Arguments: One or two (?): one required (output format type), and + one optional (source path). + - Options: None? + - Content: Stored verbatim, uninterpreted. None (empty) if a source + path argument given. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is -given in the directive data. During the initial parse, a "pending" +given in the first argument. During the initial parse, a "pending" element is generated which acts as a placeholder, storing the format and raw data internally. The interpretation of the code is up to the Writer. A Writer may ignore any raw output not matching its format. @@ -484,14 +587,25 @@ output stream:: \documentclass[twocolumn]{article} +Raw data can also be read from an external file, specified in an +optional second argument. In this case, the content block must be +empty. For example:: + + .. raw:: html inclusion.html + Restructuredtext-Test-Directive =============================== -DTD element: system_warning. +* Directive Type: "restructuredtext-test-directive" + +* DTD Element: system_warning + +* Directive Block: -Directive block: directive data is stored, and all following indented -text is interpreted as a literal block. + - Arguments: None. + - Options: None. + - Content: Interpreted as a literal block. This directive is provided for test purposes only. (Nobody is expected to type in a name *that* long!) It is converted into a -- cgit v1.2.1 From 80f8cc03017c6845f8a1bb41871caf13b3d04022 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Aug 2002 00:44:32 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@599 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 548f96ab5..f1540df89 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -519,21 +519,12 @@ Directives __ rst/directives.html#raw-data-pass-through - - _`misc.include`: ``#include`` one file in another. But how to - parse wrt sections, reference names, conflicts? For now, we'll - parse it in the current document's context (C-preprocessor - semantics). Perhaps later, when there's a need, we'll figure out - how to provide separate parsing (parse separately and then merge). - - A "raw" flag (attribute with no value) would inform us that the - imported data is raw (already in native format, like HTML). - Perhaps there should be an attribute value, saying what the native - format is. Instead, perhaps the "raw" directive should take an - "include" parameter (explicit attribute or second parameter in its - directive data). See misc.raw_. Example:: - - .. include:: path/subdocument.txt - :raw: + - _`misc.include`: ``#include`` one file in another. See `Including + an External Fragment`__ in rst/directives.txt. But how to parse + wrt sections, reference names, conflicts? For now, we'll parse it + in the current document's context (C-preprocessor semantics). + Perhaps later, when there's a need, we'll figure out how to + provide separate parsing (parse separately and then merge). Implementation ideas: Model the directive parsing on the "images" directive. A separate, nested parse is probably needed, since @@ -551,6 +542,8 @@ Directives from ``docutils/include/``. (Should "quotes" be required around non-standard include files?) + __ rst/directives.html#including-an-external-fragment + - _`misc.exec`: Execute Python code & insert the results. Perhaps dangerous? -- cgit v1.2.1 From f5b14fd1f00f2a71b741df73e8aa6b75bbcc1113 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 00:22:54 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@601 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++-- docs/ref/rst/directives.txt | 2 -- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f1540df89..32446f411 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -94,8 +94,10 @@ General - A queue, with entries ``(priority, transform, pending=None)``. - Transform classes can have ``priority`` class attributes. - - Priorities can be numeric. Integers (0..100? 000..999?)? Floats - (would be easier to squeeze in new ones)? + - Priorities can be numeric. Integers (0..100? 0..999? + 0..9999?)? Floats (would be easier to squeeze in new ones)? + - Priorities can be strings. Numeric (000..999? 0000..9999?)? + Alphanumeric (a..z? 1, 1a, 1b, ...?)? - Each transform would have a unique priority. Use a look-up table? No, that would require too many imports to construct. Document transform priorities. diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5f38e9503..152bb37a7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -456,8 +456,6 @@ Citations Meta ==== -. - * Directive Type: "meta" * DTD Element: meta (non-standard) -- cgit v1.2.1 From b02bac44e33d1df5fcba70c171ea3f38e0fe1c56 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 01:50:41 +0000 Subject: Fixed the quote from Anne Elk (MIss). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@603 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 68f914875..f0d8aec41 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1146,10 +1146,11 @@ reStructuredText source:: Big and scary; the "Tyrant King". Brontosaurus : herbivore - Small at one end, big in the middle, - and small again at the other end. + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. - -- Anne Elk, Miss + -- Anne Elk (Miss) Pseudo-XML_ fragment from simple parsing:: @@ -1169,8 +1170,9 @@ Pseudo-XML_ fragment from simple parsing:: herbivore <definition> <paragraph> - Small at one end, big in the middle, - and small again at the other end. + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. <paragraph> -- Anne Elk, Miss -- cgit v1.2.1 From 10c190454b624095d7e5d88a886b9409d9a5c3ae Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Aug 2002 01:53:32 +0000 Subject: oops git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@604 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f0d8aec41..762d3e4b1 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1174,7 +1174,7 @@ Pseudo-XML_ fragment from simple parsing:: much much thicker in the middle and then thin again at the far end. <paragraph> - -- Anne Elk, Miss + -- Anne Elk (Miss) See definition_list_ and classifier_ for further examples. -- cgit v1.2.1 From 537691e2e0b359558a1aba0acda9c2a6f9e31cc3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 29 Aug 2002 01:44:20 +0000 Subject: Added "--footnote-references" option (superscript or brackets). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@606 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 30ff3a88c..515dfdd86 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -358,6 +358,12 @@ footnote_backlinks Enable or disable backlinks from footnotes and ``--footnote-backlinks, --no-footnote-backlinks``. -------------------- ------------------------------------------------ +footnote_references (HTML Writer.) Format for footnote references, + one of "superscript" or "brackets". + + Default: "superscript". Options: + ``--footnote-references``. +-------------------- ------------------------------------------------ generator Include a "Generated by Docutils" credit and link in the document footer. -- cgit v1.2.1 From a1bd7678f3148c5429eb6021fdddcae31a6421ac Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 Aug 2002 01:38:52 +0000 Subject: Converted to reStructuredText & updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@613 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0257.txt | 425 +++++++++++++++++++++++++------------------------ 1 file changed, 216 insertions(+), 209 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index fc5edbcb0..f34477d07 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -2,255 +2,262 @@ PEP: 257 Title: Docstring Conventions Version: $Revision$ Last-Modified: $Date$ -Author: goodger@users.sourceforge.net (David Goodger), - guido@python.org (Guido van Rossum) +Author: David Goodger <goodger@users.sourceforge.net>, + Guido van Rossum guido@python.org Discussions-To: doc-sig@python.org Status: Active Type: Informational +Content-Type: text/x-rst Created: 29-May-2001 Post-History: 13-Jun-2001 Abstract +======== - This PEP documents the semantics and conventions associated with - Python docstrings. +This PEP documents the semantics and conventions associated with +Python docstrings. Rationale +========= - The aim of this PEP is to standardize the high-level structure of - docstrings: what they should contain, and how to say it (without - touching on any markup syntax within docstrings). The PEP - contains conventions, not laws or syntax. +The aim of this PEP is to standardize the high-level structure of +docstrings: what they should contain, and how to say it (without +touching on any markup syntax within docstrings). The PEP contains +conventions, not laws or syntax. - "A universal convention supplies all of maintainability, - clarity, consistency, and a foundation for good programming - habits too. What it doesn't do is insist that you follow it - against your will. That's Python!" + "A universal convention supplies all of maintainability, clarity, + consistency, and a foundation for good programming habits too. + What it doesn't do is insist that you follow it against your will. + That's Python!" - --Tim Peters on comp.lang.python, 2001-06-16 + -- Tim Peters on comp.lang.python, 2001-06-16 - If you violate the conventions, the worst you'll get is some dirty - looks. But some software (such as the Docutils docstring - processing system [1] [2]) will be aware of the conventions, so - following them will get you the best results. +If you violate these conventions, the worst you'll get is some dirty +looks. But some software (such as the Docutils_ docstring processing +system [1]_ [2]_) will be aware of the conventions, so following them +will get you the best results. Specification +============= - What is a Docstring? - -------------------- +What is a Docstring? +-------------------- - A docstring is a string literal that occurs as the first statement - in a module, function, class, or method definition. Such a - docstring becomes the __doc__ special attribute of that object. +A docstring is a string literal that occurs as the first statement in +a module, function, class, or method definition. Such a docstring +becomes the ``__doc__`` special attribute of that object. - All modules should normally have docstrings, and all functions and - classes exported by a module should also have docstrings. Public - methods (including the __init__ constructor) should also have - docstrings. A package may be documented in the module docstring - of the __init__.py file in the package directory. +All modules should normally have docstrings, and all functions and +classes exported by a module should also have docstrings. Public +methods (including the ``__init__`` constructor) should also have +docstrings. A package may be documented in the module docstring of +the ``__init__.py`` file in the package directory. - String literals occurring elsewhere in Python code may also act as - documentation. They are not recognized by the Python bytecode - compiler and are not accessible as runtime object attributes - (i.e. not assigned to __doc__), but two types of extra docstrings - may be extracted by software tools: - - 1. String literals occurring immediately after a simple assignment - at the top level of a module, class, or __init__ method - are called "attribute docstrings". - - 2. String literals occurring immediately after another docstring - are called "additional docstrings". - - Please see PEP 258 "Docutils Design Specification" [2] for a - detailed description of attribute and additional docstrings. - - XXX Mention docstrings of 2.2 properties. - - For consistency, always use """triple double quotes""" around - docstrings. Use r"""raw triple double quotes""" if you use any - backslashes in your docstrings. For Unicode docstrings, use - u"""Unicode triple-quoted strings""". - - There are two forms of docstrings: one-liners and multi-line - docstrings. - - One-line Docstrings - -------------------- - - One-liners are for really obvious cases. They should really fit - on one line. For example:: - - def kos_root(): - """Return the pathname of the KOS root directory.""" - global _kos_root - if _kos_root: return _kos_root - ... - - Notes: - - - Triple quotes are used even though the string fits on one line. - This makes it easy to later expand it. - - - The closing quotes are on the same line as the opening quotes. - This looks better for one-liners. - - - There's no blank line either before or after the docstring. - - - The docstring is a phrase ending in a period. It prescribes the - function or method's effect as a command ("Do this", "Return - that"), not as a description: e.g. don't write "Returns the - pathname ..." - - - The one-line docstring should NOT be a "signature" reiterating - the function/method parameters (which can be obtained by - introspection). Don't do:: - - def function(a, b): - """function(a, b) -> list""" - - This type of docstring is only appropriate for C functions (such - as built-ins), where introspection is not possible. However, - the nature of the *return value* cannot be determined by - introspection, so it should be mentioned. The preferred form - for such a docstring would be something like:: - - def function(a, b): - """Do X and return a list.""" - - (Of course "Do X" should be replaced by a useful description!) - - Multi-line Docstrings - ---------------------- - - Multi-line docstrings consist of a summary line just like a - one-line docstring, followed by a blank line, followed by a more - elaborate description. The summary line may be used by automatic - indexing tools; it is important that it fits on one line and is - separated from the rest of the docstring by a blank line. The - summary line may be on the same line as the opening quotes or on - the next line. - - The entire docstring is indented the same as the quotes at its - first line (see example below). Docstring processing tools will - strip an amount of indentation from the second and further lines - of the docstring equal to the indentation of the first non-blank - line after the first line of the docstring. Relative indentation - of later lines in the docstring is retained. - - Insert a blank line before and after all docstrings (one-line or - multi-line) that document a class -- generally speaking, the - class's methods are separated from each other by a single blank - line, and the docstring needs to be offset from the first method - by a blank line; for symmetry, put a blank line between the class - header and the docstring. Docstrings documenting functions or - methods generally don't have this requirement, unless the function - or method's body is written as a number of blank-line separated - sections -- in this case, treat the docstring as another section, - and precede it with a blank line. - - The docstring of a script (a stand-alone program) should be usable - as its "usage" message, printed when the script is invoked with - incorrect or missing arguments (or perhaps with a "-h" option, for - "help"). Such a docstring should document the script's function - and command line syntax, environment variables, and files. Usage - messages can be fairly elaborate (several screens full) and should - be sufficient for a new user to use the command properly, as well - as a complete quick reference to all options and arguments for the - sophisticated user. - - The docstring for a module should generally list the classes, - exceptions and functions (and any other objects) that are exported - by the module, with a one-line summary of each. (These summaries - generally give less detail than the summary line in the object's - docstring.) The docstring for a package (i.e., the docstring of - the package's __init__.py module) should also list the modules and - subpackages exported by the package. - - The docstring for a function or method should summarize its - behavior and document its arguments, return value(s), side - effects, exceptions raised, and restrictions on when it can be - called (all if applicable). Optional arguments should be - indicated. It should be documented whether keyword arguments are - part of the interface. - - The docstring for a class should summarize its behavior and list - the public methods and instance variables. If the class is - intended to be subclassed, and has an additional interface for - subclasses, this interface should be listed separately (in the - docstring). The class constructor should be documented in the - docstring for its __init__ method. Individual methods should be - documented by their own docstring. - - If a class subclasses another class and its behavior is mostly - inherited from that class, its docstring should mention this and - summarize the differences. Use the verb "override" to indicate - that a subclass method replaces a superclass method and does not - call the superclass method; use the verb "extend" to indicate that - a subclass method calls the superclass method (in addition to its - own behavior). - - *Do not* use the Emacs convention of mentioning the arguments of - functions or methods in upper case in running text. Python is - case sensitive and the argument names can be used for keyword - arguments, so the docstring should document the correct argument - names. It is best to list each argument on a separate line. For - example:: - - def complex(real=0.0, imag=0.0): - """Form a complex number. - - Keyword arguments: - real -- the real part (default 0.0) - imag -- the imaginary part (default 0.0) - - """ - if imag == 0.0 and real == 0.0: return complex_zero - ... - - The BDFL [3] recommends inserting a blank line between the last - paragraph in a multi-line docstring and its closing quotes, - placing the closing quotes on a line by themselves. This way, - Emacs' fill-paragraph command can be used on it. +String literals occurring elsewhere in Python code may also act as +documentation. They are not recognized by the Python bytecode +compiler and are not accessible as runtime object attributes (i.e. not +assigned to ``__doc__``), but two types of extra docstrings may be +extracted by software tools: + +1. String literals occurring immediately after a simple assignment at + the top level of a module, class, or ``__init__`` method are called + "attribute docstrings". + +2. String literals occurring immediately after another docstring are + called "additional docstrings". + +Please see PEP 258, "Docutils Design Specification" [2]_, for a +detailed description of attribute and additional docstrings. + +XXX Mention docstrings of 2.2 properties. + +For consistency, always use ``"""triple double quotes"""`` around +docstrings. Use ``r"""raw triple double quotes"""`` if you use any +backslashes in your docstrings. For Unicode docstrings, use +``u"""Unicode triple-quoted strings"""``. + +There are two forms of docstrings: one-liners and multi-line +docstrings. + + +One-line Docstrings +-------------------- + +One-liners are for really obvious cases. They should really fit on +one line. For example:: + + def kos_root(): + """Return the pathname of the KOS root directory.""" + global _kos_root + if _kos_root: return _kos_root + ... + +Notes: + +- Triple quotes are used even though the string fits on one line. + This makes it easy to later expand it. + +- The closing quotes are on the same line as the opening quotes. This + looks better for one-liners. + +- There's no blank line either before or after the docstring. + +- The docstring is a phrase ending in a period. It prescribes the + function or method's effect as a command ("Do this", "Return that"), + not as a description; e.g. don't write "Returns the pathname ...". + +- The one-line docstring should NOT be a "signature" reiterating the + function/method parameters (which can be obtained by introspection). + Don't do:: + + def function(a, b): + """function(a, b) -> list""" + + This type of docstring is only appropriate for C functions (such as + built-ins), where introspection is not possible. However, the + nature of the *return value* cannot be determined by introspection, + so it should be mentioned. The preferred form for such a docstring + would be something like:: + + def function(a, b): + """Do X and return a list.""" + + (Of course "Do X" should be replaced by a useful description!) + + +Multi-line Docstrings +---------------------- + +Multi-line docstrings consist of a summary line just like a one-line +docstring, followed by a blank line, followed by a more elaborate +description. The summary line may be used by automatic indexing +tools; it is important that it fits on one line and is separated from +the rest of the docstring by a blank line. The summary line may be on +the same line as the opening quotes or on the next line. + +The entire docstring is indented the same as the quotes at its first +line (see example below). Docstring processing tools will strip an +amount of indentation from the second and further lines of the +docstring equal to the indentation of the first non-blank line after +the first line of the docstring. Relative indentation of later lines +in the docstring is retained. + +Insert a blank line before and after all docstrings (one-line or +multi-line) that document a class -- generally speaking, the class's +methods are separated from each other by a single blank line, and the +docstring needs to be offset from the first method by a blank line; +for symmetry, put a blank line between the class header and the +docstring. Docstrings documenting functions or methods generally +don't have this requirement, unless the function or method's body is +written as a number of blank-line separated sections -- in this case, +treat the docstring as another section, and precede it with a blank +line. + +The docstring of a script (a stand-alone program) should be usable as +its "usage" message, printed when the script is invoked with incorrect +or missing arguments (or perhaps with a "-h" option, for "help"). +Such a docstring should document the script's function and command +line syntax, environment variables, and files. Usage messages can be +fairly elaborate (several screens full) and should be sufficient for a +new user to use the command properly, as well as a complete quick +reference to all options and arguments for the sophisticated user. + +The docstring for a module should generally list the classes, +exceptions and functions (and any other objects) that are exported by +the module, with a one-line summary of each. (These summaries +generally give less detail than the summary line in the object's +docstring.) The docstring for a package (i.e., the docstring of the +package's ``__init__.py`` module) should also list the modules and +subpackages exported by the package. + +The docstring for a function or method should summarize its behavior +and document its arguments, return value(s), side effects, exceptions +raised, and restrictions on when it can be called (all if applicable). +Optional arguments should be indicated. It should be documented +whether keyword arguments are part of the interface. + +The docstring for a class should summarize its behavior and list the +public methods and instance variables. If the class is intended to be +subclassed, and has an additional interface for subclasses, this +interface should be listed separately (in the docstring). The class +constructor should be documented in the docstring for its ``__init__`` +method. Individual methods should be documented by their own +docstring. + +If a class subclasses another class and its behavior is mostly +inherited from that class, its docstring should mention this and +summarize the differences. Use the verb "override" to indicate that a +subclass method replaces a superclass method and does not call the +superclass method; use the verb "extend" to indicate that a subclass +method calls the superclass method (in addition to its own behavior). + +*Do not* use the Emacs convention of mentioning the arguments of +functions or methods in upper case in running text. Python is case +sensitive and the argument names can be used for keyword arguments, so +the docstring should document the correct argument names. It is best +to list each argument on a separate line. For example:: + + def complex(real=0.0, imag=0.0): + """Form a complex number. + + Keyword arguments: + real -- the real part (default 0.0) + imag -- the imaginary part (default 0.0) + + """ + if imag == 0.0 and real == 0.0: return complex_zero + ... + +The BDFL [3]_ recommends inserting a blank line between the last +paragraph in a multi-line docstring and its closing quotes, placing +the closing quotes on a line by themselves. This way, Emacs' +fill-paragraph command can be used on it. References and Footnotes +======================== + +.. [1] PEP 256, Docstring Processing System Framework, Goodger + (http://www.python.org/peps/pep-0256.html) - [1] PEP 256, Docstring Processing System Framework, Goodger - http://www.python.org/peps/pep-0256.html +.. [2] PEP 258, Docutils Design Specification, Goodger + (http://www.python.org/peps/pep-0258.html) - [2] PEP 258, Docutils Design Specification, Goodger - http://www.python.org/peps/pep-0258.html +.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For + Life. - [3] Guido van Rossum, Python's creator and Benevolent Dictator For - Life. +.. _Docutils: http://docutils.sourceforge.net/ - [4] http://www.python.org/doc/essays/styleguide.html +.. _Python Style Guide: + http://www.python.org/doc/essays/styleguide.html - [5] http://www.python.org/sigs/doc-sig/ +.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ Copyright +========= - This document has been placed in the public domain. +This document has been placed in the public domain. Acknowledgements +================ - The "Specification" text comes mostly verbatim from the Python - Style Guide essay by Guido van Rossum [4]. +The "Specification" text comes mostly verbatim from the `Python Style +Guide`_ essay by Guido van Rossum. - This document borrows ideas from the archives of the Python - Doc-SIG [5]. Thanks to all members past and present. +This document borrows ideas from the archives of the Python Doc-SIG_. +Thanks to all members past and present. -Local Variables: -mode: indented-text -indent-tabs-mode: nil -fill-column: 70 -sentence-end-double-space: t -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + fill-column: 70 + sentence-end-double-space: t + End: -- cgit v1.2.1 From 8f497c956b6102f1b7753e321a392ff53bc14c94 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 Aug 2002 01:45:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@614 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 515dfdd86..105115266 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -120,15 +120,17 @@ Stylesheets ``html.py`` inserts into the generated HTML a link to a cascading stylesheet, defaulting to "``default.css``" (override with a -"``--stylesheet``" command-line option or with a configuration file). -The "``tools/default.css``" stylesheet is provided for basic use. To -experiment with styles, rather than editing the default stylesheet -(which will be updated as the project evolves), it is recommended to -use the "``@import``" statement to create a "wrapper" stylesheet. For -example, a "``my.css``" stylesheet could contain the following:: +"``--stylesheet``" or "``--stylesheet-path``" command-line option or +with configuration file settings). The +"``tools/stylesheets/default.css``" stylesheet is provided for basic +use. To experiment with styles, rather than editing the default +stylesheet (which will be updated as the project evolves), it is +recommended to use an "``@import``" statement to create a "wrapper" +stylesheet. For example, a "``my.css``" stylesheet could contain the +following:: @import url(default.css); - + h1, h2, h3, h4, h5, h6, p.topic-title { font-family: sans-serif } @@ -503,11 +505,11 @@ _directories (``buildhtml.py`` front end.) List of paths to (None). No command-line options. -------------------- ------------------------------------------------ _destination Path to output destination, set from positional - arguments. Default: stdout (None). No + arguments. Default: stdout (None). No command-line options. -------------------- ------------------------------------------------ _source Path to input source, set from positional - arguments. Default: stdin (None). No + arguments. Default: stdin (None). No command-line options. ==================== ================================================ -- cgit v1.2.1 From 4ddb87dd5c72db0058352a87b5322484d2b36907 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 Aug 2002 02:13:44 +0000 Subject: minor fixes git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@615 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0257.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index f34477d07..9ce589f88 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -3,7 +3,7 @@ Title: Docstring Conventions Version: $Revision$ Last-Modified: $Date$ Author: David Goodger <goodger@users.sourceforge.net>, - Guido van Rossum guido@python.org + Guido van Rossum <guido@python.org> Discussions-To: doc-sig@python.org Status: Active Type: Informational @@ -214,7 +214,7 @@ to list each argument on a separate line. For example:: The BDFL [3]_ recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing the closing quotes on a line by themselves. This way, Emacs' -fill-paragraph command can be used on it. +``fill-paragraph`` command can be used on it. References and Footnotes -- cgit v1.2.1 From 573c0a4a6e4d06733db75aa4226ad28296d14b46 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 4 Sep 2002 01:28:15 +0000 Subject: Added "line" attribute to ``system_message`` elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@620 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 244d4c9d0..a2d8a9e45 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -464,6 +464,7 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. %basic.atts; %backrefs.att; level &number; #IMPLIED + line &number; #IMPLIED type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> -- cgit v1.2.1 From 3965011e31be38ef15059a1cf16856ab9ce926e7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Sep 2002 03:03:53 +0000 Subject: removed tabs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@625 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 952 ++++++++++++++++++++++---------------------- 1 file changed, 476 insertions(+), 476 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index e32073cb7..b03e11b8b 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -23,8 +23,8 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> - <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Version 0.10 of 2002-08-07</em> + <br align="right"><em>Being a cheat-sheet for reStructuredText</em> + <br align="right"><em>Version 0.10a of 2002-09-04</em> <p>The full details of the markup may be found on the @@ -32,12 +32,12 @@ page. This document is just intended as a reminder. <p>Links that look like "(<a href="#details">details?</a>)" point - into the HTML version of the full <a - href="../../spec/rst/reStructuredText.html">reStructuredText - specification</a> document. These are relative links; if they - don't work, please use the <a - href="http://docutils.sourceforge.net/docs/rst/quickref.html" - >master "Quick reStructuredText"</a> document. + into the HTML version of the full <a + href="../../spec/rst/reStructuredText.html">reStructuredText + specification</a> document. These are relative links; if they + don't work, please use the <a + href="http://docutils.sourceforge.net/docs/rst/quickref.html" + >master "Quick reStructuredText"</a> document. <h2><a name="contents">Contents</a></h2> @@ -67,8 +67,8 @@ </ul> <li><a href="#directives">Directives</a></li> <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> - <li><a href="#comments">Comments</a></li> - <li><a href="#getting-help">Getting Help</a></li> + <li><a href="#comments">Comments</a></li> + <li><a href="#getting-help">Getting Help</a></li> </ul> <h2><a href="#contents" name="inline-markup" class="backref" @@ -78,75 +78,75 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th>Plain text - <th>Typical result - <th>Notes + <tr align="left" bgcolor="#99CCFF"> + <th>Plain text + <th>Typical result + <th>Notes </thead> <tbody> - <tr valign="top"> - <td nowrap><samp>*emphasis*</samp> - <td><em>emphasis</em> - <td>  - - <tr valign="top"> - <td nowrap><samp>**strong emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>  - - <tr valign="top"> - <td nowrap><samp>`interpreted text`</samp> - <td>interpreted text - <td>What interpreted text <em>means</em> is domain dependent. - - <tr valign="top"> - <td nowrap><samp>``inline literal``</samp> - <td><code>inline literal</code> - <td>Spaces should be preserved, but line breaks will not be. - - <tr valign="top"> - <td nowrap><samp>reference_</samp> - <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a href="#hyperlinks">Hyperlinks</a>. - - <tr valign="top"> - <td nowrap><samp>`phrase reference`_</samp> - <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be quoted with backquotes. + <tr valign="top"> + <td nowrap><samp>*emphasis*</samp> + <td><em>emphasis</em> + <td>  + + <tr valign="top"> + <td nowrap><samp>**strong emphasis**</samp> + <td><strong>strong emphasis</strong> + <td>  + + <tr valign="top"> + <td nowrap><samp>`interpreted text`</samp> + <td>interpreted text + <td>What interpreted text <em>means</em> is domain dependent. + + <tr valign="top"> + <td nowrap><samp>``inline literal``</samp> + <td><code>inline literal</code> + <td>Spaces should be preserved, but line breaks will not be. + + <tr valign="top"> + <td nowrap><samp>reference_</samp> + <td><a href="#hyperlink-targets">reference</a> + <td>A simple, one-word hyperlink reference. See <a href="#hyperlinks">Hyperlinks</a>. + + <tr valign="top"> + <td nowrap><samp>`phrase reference`_</samp> + <td><a href="#hyperlink-targets">phrase reference</a> + <td>A hyperlink reference with spaces or punctuation needs to be quoted with backquotes. See <a href="#hyperlink-targets">Hyperlinks</a>. - <tr valign="top"> - <td nowrap><samp>anonymous__</samp> - <td><a href="#hyperlink-targets">anonymous</a> - <td>Both simple and phrase references may be anonymous (two underscores). + <tr valign="top"> + <td nowrap><samp>anonymous__</samp> + <td><a href="#hyperlink-targets">anonymous</a> + <td>Both simple and phrase references may be anonymous (two underscores). See <a href="#hyperlink-targets">Hyperlinks</a>. - <tr valign="top"> - <td nowrap><samp>_`inline internal target`</samp> - <td><a name="inline-internal-target">inline internal target</a> - <td>A crossreference target within text. + <tr valign="top"> + <td nowrap><samp>_`inline internal target`</samp> + <td><a name="inline-internal-target">inline internal target</a> + <td>A crossreference target within text. See <a href="#hyperlink-targets">Hyperlinks</a>. - <tr valign="top"> - <td nowrap><samp>|substitution reference|</samp> - <td>(see note) - <td>The result is substituted in from the <a href="#substitution-references-and-definitions">substitution definition</a>. + <tr valign="top"> + <td nowrap><samp>|substitution reference|</samp> + <td>(see note) + <td>The result is substituted in from the <a href="#substitution-references-and-definitions">substitution definition</a>. It could be text, an image, a hyperlink, or a combination of these and others. - <tr valign="top"> - <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <a href="#footnotes">[1]</a> - <td>See <a href="#footnotes">Footnotes</a>. + <tr valign="top"> + <td nowrap><samp>footnote reference [1]_</samp> + <td>footnote reference <a href="#footnotes">[1]</a> + <td>See <a href="#footnotes">Footnotes</a>. - <tr valign="top"> - <td nowrap><samp>citation reference [CIT2002]_</samp> - <td>citation reference <a href="#citations">[CIT2002]</a> - <td>See <a href="#citations">Citations</a>. + <tr valign="top"> + <td nowrap><samp>citation reference [CIT2002]_</samp> + <td>citation reference <a href="#citations">[CIT2002]</a> + <td>See <a href="#citations">Citations</a>. - <tr valign="top"> - <td nowrap><samp>http://docutils.sf.net/</samp> - <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> - <td>A standalone hyperlink. + <tr valign="top"> + <td nowrap><samp>http://docutils.sf.net/</samp> + <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> + <td>A standalone hyperlink. </table> @@ -163,22 +163,22 @@ inline markup: <ol> <li>The start-string must start a text block or be - immediately preceded by whitespace,  - <samp>' " ( [ {</samp> or  <samp><</samp>. + immediately preceded by whitespace,  + <samp>' " ( [ {</samp> or  <samp><</samp>. <li>The start-string must be immediately followed by non-whitespace. <li>The end-string must be immediately preceded by non-whitespace. <li>The end-string must end a text block or be immediately - followed by whitespace,  - <samp>' " . , : ; ! ? - ) ] }</samp> or  <samp>></samp>. + followed by whitespace,  + <samp>' " . , : ; ! ? - ) ] }</samp> or  <samp>></samp>. <li>If a start-string is immediately preceded by one of  - <samp>' " ( [ {</samp> or  <samp><</samp>, it must not be - immediately followed by the corresponding character from  - <samp>' " ) ] }</samp> or  <samp>></samp>. + <samp>' " ( [ {</samp> or  <samp><</samp>, it must not be + immediately followed by the corresponding character from  + <samp>' " ) ] }</samp> or  <samp>></samp>. <li>An end-string must be separated by at least one - character from the start-string. + character from the start-string. <li>An <a href="#escaping">unescaped</a> backslash preceding a start-string or end-string will - disable markup recognition, except for the end-string of inline - literals. + disable markup recognition, except for the end-string of inline + literals. </ol> <p>Also remember that inline markup may not be nested (well, @@ -199,17 +199,17 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Raw reStructuredText - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Raw reStructuredText + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"><td> - <samp>*escape* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</samp> - <td>*escape* ``with`` "\" + <tr valign="top"><td> + <samp>*escape* ``with`` "\"</samp> + <td><em>escape</em> <samp>with</samp> "" + <tr valign="top"><td> + <samp>\*escape* \``with`` "\\"</samp> + <td>*escape* ``with`` "\" </table> <p>In Python strings it will, of course, be necessary @@ -219,20 +219,20 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Python string - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Python string + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"><td> - <samp>r"""\*escape* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</samp> - <td><em>escape</em> with "" + <tr valign="top"><td> + <samp>r"""\*escape* \`with` "\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\\*escape* \\`with` "\\\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\*escape* \`with` "\\""""</samp> + <td><em>escape</em> with "" </table> <h2><a href="#contents" name="section-structure" class="backref" @@ -242,31 +242,31 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>=====</samp> - <br><samp>Title</samp> - <br><samp>=====</samp> - <br><samp>Subtitle</samp> - <br><samp>--------</samp> - <br><samp>Titles are underlined (or over-</samp> - <br><samp>and underlined) with a printing</samp> - <br><samp>nonalphanumeric 7-bit ASCII</samp> - <br><samp>character. Recommended choices</samp> - <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> - <td> - <font size="+2"><strong>Title</strong></font> - <p><font size="+1"><strong>Subtitle</strong></font> - <p>Titles are underlined (or over- - and underlined) with a printing - nonalphanumeric 7-bit ASCII - character. Recommended choices - are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". + <tr valign="top"> + <td> + <samp>=====</samp> + <br><samp>Title</samp> + <br><samp>=====</samp> + <br><samp>Subtitle</samp> + <br><samp>--------</samp> + <br><samp>Titles are underlined (or over-</samp> + <br><samp>and underlined) with a printing</samp> + <br><samp>nonalphanumeric 7-bit ASCII</samp> + <br><samp>character. Recommended choices</samp> + <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> + <td> + <font size="+2"><strong>Title</strong></font> + <p><font size="+1"><strong>Subtitle</strong></font> + <p>Titles are underlined (or over- + and underlined) with a printing + nonalphanumeric 7-bit ASCII + character. Recommended choices + are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". </table> <h2><a href="#contents" name="paragraphs" class="backref" @@ -276,20 +276,20 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <p><samp>This is a paragraph.</samp> <p><samp>Paragraphs line up at their left</samp> <br><samp>edges, and are normally separated</samp> <br><samp>by blank lines.</samp> - <td> + <td> <p>This is a paragraph. <p>Paragraphs line up at their left edges, and are normally @@ -304,13 +304,13 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>Bullet lists:</samp> <p><samp>- This is item 1</samp> @@ -323,16 +323,16 @@ <p><samp>Note that a blank line is required</samp> <br><samp>before the first item and after the</samp> <br><samp>last, but is optional between items.</samp> - <td>Bullet lists: - <ul> - <li>This is item 1 - <li>This is item 2 - <li>Bullets are "-", "*" or "+". - Continuing text must be aligned - after the bullet and whitespace. - </ul> - <p>Note that a blank line is required before the first - item and after the last, but is optional between items. + <td>Bullet lists: + <ul> + <li>This is item 1 + <li>This is item 2 + <li>Bullets are "-", "*" or "+". + Continuing text must be aligned + after the bullet and whitespace. + </ul> + <p>Note that a blank line is required before the first + item and after the last, but is optional between items. </table> <h2><a href="#contents" name="enumerated-lists" class="backref" @@ -342,13 +342,13 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>Enumerated lists:</samp> <p><samp>3. This is the first item</samp> @@ -359,16 +359,16 @@ <br><samp>   numbered, but need not start at 1</samp> <br><samp>   (although not all formatters will</samp> <br><samp>   honour the first index).</samp> - <td>Enumerated lists: - <ol type="1"> - <li value="3">This is the first item - <li>This is the second item - <li>Enumerators are arabic numbers, single letters, - or roman numerals - <li>List items should be sequentially numbered, - but need not start at 1 (although not all - formatters will honour the first index). - </ol> + <td>Enumerated lists: + <ol type="1"> + <li value="3">This is the first item + <li>This is the second item + <li>Enumerators are arabic numbers, single letters, + or roman numerals + <li>List items should be sequentially numbered, + but need not start at 1 (although not all + formatters will honour the first index). + </ol> </table> <h2><a href="#contents" name="definition-lists" class="backref" @@ -378,13 +378,13 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>Definition lists:</samp> <br> <br><samp>what</samp> @@ -397,19 +397,19 @@ <br><samp>  body elements, indented relative to the</samp> <br><samp>  term. Blank lines are not allowed</samp> <br><samp>  between term and definition.</samp> - <td>Definition lists: - <dl> - <dt><strong>what</strong> - <dd>Definition lists associate a term with - a definition. - - <dt><strong>how</strong> - <dd>The term is a one-line phrase, and the - definition is one or more paragraphs or - body elements, indented relative to the - term. Blank lines are not allowed - between term and definition. - </dl> + <td>Definition lists: + <dl> + <dt><strong>what</strong> + <dd>Definition lists associate a term with + a definition. + + <dt><strong>how</strong> + <dd>The term is a one-line phrase, and the + definition is one or more paragraphs or + body elements, indented relative to the + term. Blank lines are not allowed + between term and definition. + </dl> </table> <h2><a href="#contents" name="field-lists" class="backref" @@ -419,13 +419,13 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>:Authors:</samp> <br><samp>    Tony J. (Tibs) Ibbs,</samp> <br><samp>    David Goodger</samp> @@ -434,16 +434,16 @@ <p><samp>:Version: 1.0 of 2001/08/08</samp> <br><samp>:Dedication: To my father.</samp> - <td> - <table> - <tr valign="top"> - <td><strong>Authors:</strong> - <td>Tony J. (Tibs) Ibbs, - David Goodger - <tr><td><td>(and sundry other good-natured folks) - <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 - <tr><td><strong>Dedication:</strong><td>To my father. - </table> + <td> + <table> + <tr valign="top"> + <td><strong>Authors:</strong> + <td>Tony J. (Tibs) Ibbs, + David Goodger + <tr><td><td>(and sundry other good-natured folks) + <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 + <tr><td><strong>Dedication:</strong><td>To my father. + </table> </table> <h2><a href="#contents" name="option-lists" class="backref" @@ -454,12 +454,12 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <p><samp> -a            command-line option "a" <br>-b file       options can have arguments @@ -470,7 +470,7 @@ <br>/V            DOS/VMS-style options too </samp> - <td> + <td> <table border="0" width="100%"> <tbody valign="top"> <tr> @@ -501,13 +501,13 @@ <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>A paragraph containing only two colons</samp> <br><samp>indicates that the following indented</samp> <br><samp>text is a literal block.</samp> @@ -539,7 +539,7 @@ <br> <br><samp>is possible.</samp> - <td> + <td> <p>A paragraph containing only two colons indicates that the following indented text is a literal block. @@ -581,25 +581,25 @@ This means that something like: <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <samp>Block quotes are just:</samp> <p><samp>    Indented paragraphs,</samp> <p><samp>        and they may nest.</samp> - <td> - Block quotes are just: - <blockquote> - <p>Indented paragraphs, - <blockquote> - <p>and they may nest. - </blockquote> - </blockquote> + <td> + Block quotes are just: + <blockquote> + <p>Indented paragraphs, + <blockquote> + <p>and they may nest. + </blockquote> + </blockquote> </table> <h2><a href="#contents" name="doctest-blocks" class="backref" @@ -610,12 +610,12 @@ This means that something like: <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <p><samp>Doctest blocks are interactive <br>Python sessions. They begin with <br>"``>>>``" and end with a blank line.</samp> @@ -623,7 +623,7 @@ This means that something like: <p><samp>>>> print "This is a doctest block." <br>This is a doctest block.</samp> - <td> + <td> <p>Doctest blocks are interactive Python sessions. They begin with "<samp>>>></samp>" and end with a blank line. @@ -649,13 +649,13 @@ This means that something like: <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <p><samp>Grid table:</samp></p> <p><samp>+------------+------------+-----------+</samp> @@ -669,34 +669,34 @@ This means that something like: <br><samp>+------------+ span rows. | - contain |</samp> <br><samp>| body row 4 |            | - blocks. |</samp> <br><samp>+------------+------------+-----------+</samp></p> - <td> + <td> <p>Grid table:</p> - <table border="1"> - <tr valign="top"> - <th>Header 1 - <th>Header 2 - <th>Header 3 - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - <tr valign="top"> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - <tr valign="top"> - <td>body row 4 - </table> - <tr valign="top"> - <td> + <table border="1"> + <tr valign="top"> + <th>Header 1 + <th>Header 2 + <th>Header 3 + <tr> + <td>body row 1 + <td>column 2 + <td>column 3 + <tr> + <td>body row 2 + <td colspan="2">Cells may span columns. + <tr valign="top"> + <td>body row 3 + <td rowspan="2">Cells may<br>span rows. + <td rowspan="2"> + <ul> + <li>Cells + <li>contain + <li>blocks. + </ul> + <tr valign="top"> + <td>body row 4 + </table> + <tr valign="top"> + <td> <p><samp>Simple table:</samp></p> <p><samp>=====  =====  ======</samp> @@ -710,7 +710,7 @@ This means that something like: <br><samp>True   True   True</samp> <br><samp>=====  =====  ======</samp></p> - <td> + <td> <p>Simple table:</p> <table frame="border" rules="all"> <colgroup> @@ -755,12 +755,12 @@ This means that something like: <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> + <tr valign="top"> + <td> <p><samp> A transition marker is a horizontal line <br>of 4 or more repeated punctuation @@ -772,7 +772,7 @@ A transition marker is a horizontal line <br>section or document, nor should two <br>transitions be immediately adjacent.</samp> - <td> + <td> <p>A transition marker is a horizontal line of 4 or more repeated punctuation characters.</p> @@ -795,82 +795,82 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>Footnote references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp>   there's no colon after the ``]``.</samp> - - <td> - Footnote references, like <sup><a href="#5">[5]</a></sup>. - Note that footnotes may get rearranged, e.g., to the bottom of - the "page". - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. - Note there's no colon after the <samp>]</samp>. + <tr valign="top"> + <td> + <samp>Footnote references, like [5]_.</samp> + <br><samp>Note that footnotes may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> + + <p><samp>.. [5] A numerical footnote. Note</samp> + <br><samp>   there's no colon after the ``]``.</samp> + + <td> + Footnote references, like <sup><a href="#5">[5]</a></sup>. + Note that footnotes may get rearranged, e.g., to the bottom of + the "page". + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. + Note there's no colon after the <samp>]</samp>. </table> - <tr valign="top"> - <td> - <samp>Autonumbered footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. fourth_</samp> - <td> - Autonumbered footnotes are possible, like using <sup><a - href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. - - <p>They may be assigned 'autonumber labels' - for instance, - <sup><a href="#fourth">4</a></sup> and <sup><a - href="#third">3</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. - <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. - <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> - <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> - </table> - - <tr valign="top"> - <td> - <samp>Auto-symbol footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote - <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. - </table> + <tr valign="top"> + <td> + <samp>Autonumbered footnotes are</samp> + <br><samp>possible, like using [#]_ and [#]_.</samp> + <p><samp>.. [#] This is the first one.</samp> + <br><samp>.. [#] This is the second one.</samp> + + <p><samp>They may be assigned 'autonumber</samp> + <br><samp>labels' - for instance, + <br>[#fourth]_ and [#third]_.</samp> + + <p><samp>.. [#third] a.k.a. third_</samp> + <p><samp>.. [#fourth] a.k.a. fourth_</samp> + <td> + Autonumbered footnotes are possible, like using <sup><a + href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. + + <p>They may be assigned 'autonumber labels' - for instance, + <sup><a href="#fourth">4</a></sup> and <sup><a + href="#third">3</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. + <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. + <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> + <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> + </table> + + <tr valign="top"> + <td> + <samp>Auto-symbol footnotes are also</samp> + <br><samp>possible, like this: [*]_ and [*]_.</samp> + <p><samp>.. [*] This is the first one.</samp> + <br><samp>.. [*] This is the second one.</samp> + + <td> + Auto-symbol footnotes are also + possible, like this: <sup><a href="#symbol1">*</a></sup> + and <sup><a href="#symbol2">†</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote + <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. + </table> </table> @@ -888,48 +888,48 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>Citation references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> + <tr valign="top"> + <td> + <samp>Citation references, like [CIT2002]_.</samp> + <br><samp>Note that citations may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> - <p><samp>.. [CIT2002] A citation</samp> - <br><samp>   (as often used in journals).</samp> + <p><samp>.. [CIT2002] A citation</samp> + <br><samp>   (as often used in journals).</samp> - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> + <p><samp>Citation labels contain alphanumerics,</samp> + <br><samp>underlines, hyphens and fullstops.</samp> + <br><samp>Case is not significant.</samp> - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> + <p><samp>Given a citation like [this]_, one</samp> + <br><samp>can also refer to it like this_.</samp> - <p><samp>.. [this] here.</samp> + <p><samp>.. [this] here.</samp> - <td> - Citation references, like <a href="#cit2002">[CIT2002]</a>. + <td> + Citation references, like <a href="#cit2002">[CIT2002]</a>. Note that citations may get rearranged, e.g., to the bottom of the "page". - <p>Citation labels contain alphanumerics, underlines, hyphens - and fullstops. Case is not significant. + <p>Citation labels contain alphanumerics, underlines, hyphens + and fullstops. Case is not significant. - <p>Given a citation like <a href="#this">[this]</a>, one - can also refer to it like <a href="#this">this</a>. + <p>Given a citation like <a href="#this">[this]</a>, one + can also refer to it like <a href="#this">this</a>. - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Citations: --> - <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation - (as often used in journals). - <tr><td><a name="this"><strong>[this]</strong></a><td> here. + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Citations: --> + <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation + (as often used in journals). + <tr><td><a name="this"><strong>[this]</strong></a><td> here. </table> </table> @@ -944,32 +944,32 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>External hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <tr><td>Indirect hyperlinks, like - <a href="http://www.python.org">Python</a>. - <tr bgcolor="#99CCFF"><td><em>Call-out form</em> - <tr><td>External hyperlinks, like - <a href="#labPython"><i>Python</i></a>. - - <p><table> - <tr><td colspan="2"><hr> - <tr><td><a name="labPython"><i>Python:</i></a> - <td> <a href="http://www.python.org/">http://www.python.org/</a> - </table> - </table> + <tr valign="top"> + <td> + <samp>External hyperlinks, like Python_.</samp> + + <p><samp>.. _Python: http://www.python.org/</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <tr><td>Indirect hyperlinks, like + <a href="http://www.python.org">Python</a>. + <tr bgcolor="#99CCFF"><td><em>Call-out form</em> + <tr><td>External hyperlinks, like + <a href="#labPython"><i>Python</i></a>. + + <p><table> + <tr><td colspan="2"><hr> + <tr><td><a name="labPython"><i>Python:</i></a> + <td> <a href="http://www.python.org/">http://www.python.org/</a> + </table> + </table> </table> <p>"<em>Fold-in</em>" is the representation typically used in HTML @@ -983,61 +983,61 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td><samp>Internal crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference target.</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <!-- Note that some browsers may not like an "a" tag that --> - <!-- does not have any content, so we could arbitrarily --> - <!-- use the first word as content - *or* just trust to --> - <!-- luck! --> - <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> - <p><a name="example-foldin">This</a> is an example - crossreference target. - <tr><td bgcolor="#99CCFF"><em>Call-out form</em> - <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> - - <p><a name="example-callout"><i>example:</i></a> - <br>This is an example crossreference target. - </table> + <tr valign="top"> + <td><samp>Internal crossreferences, like example_.</samp> + + <p><samp>.. _example:</samp> + + <p><samp>This is an example crossreference target.</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <!-- Note that some browsers may not like an "a" tag that --> + <!-- does not have any content, so we could arbitrarily --> + <!-- use the first word as content - *or* just trust to --> + <!-- luck! --> + <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> + <p><a name="example-foldin">This</a> is an example + crossreference target. + <tr><td bgcolor="#99CCFF"><em>Call-out form</em> + <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> + + <p><a name="example-callout"><i>example:</i></a> + <br>This is an example crossreference target. + </table> </table> <h3><a href="#contents" name="indirect-hyperlink-targets" class="backref" >Indirect Hyperlink Targets</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details?</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>Python_ is `my favourite + <tr valign="top"> + <td> + <samp>Python_ is `my favourite <br>programming language`__.</samp> - <p><samp>.. _Python: http://www.python.org/</samp> + <p><samp>.. _Python: http://www.python.org/</samp> <p><samp>__ Python_</samp> - <td> - <p><a href="http://www.python.org/">Python</a> is + <td> + <p><a href="http://www.python.org/">Python</a> is <a href="http://www.python.org/">my favourite programming language</a>. @@ -1053,28 +1053,28 @@ A transition marker is a horizontal line <h3><a href="#contents" name="implicit-hyperlink-targets" class="backref" >Implicit Hyperlink Targets</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details?</a>) <p>Section titles, footnotes, and citations automatically generate hyperlink targets (the title text or footnote/citation label is used as the hyperlink name). - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td> - <samp>Titles are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, too`_.</samp> - <td> - <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> - <p>Implict references, like <a href="#Title">Titles are - targets, too</a>. + <tr valign="top"> + <td> + <samp>Titles are targets, too</samp> + <br><samp>=======================</samp> + <br><samp>Implict references, like `Titles are</samp> + <br><samp>targets, too`_.</samp> + <td> + <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> + <p>Implict references, like <a href="#Title">Titles are + targets, too</a>. </table> <h2><a href="#contents" name="directives" class="backref" @@ -1084,19 +1084,19 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td><samp>For instance:</samp> + <tr valign="top"> + <td><samp>For instance:</samp> - <p><samp>.. image:: images/ball1.gif</samp> + <p><samp>.. image:: images/ball1.gif</samp> - <td> - For instance: - <p><img src="images/ball1.gif" alt="ball1"> + <td> + For instance: + <p><img src="images/ball1.gif" alt="ball1"> </table> <h2><a href="#contents" name="substitution-references-and-definitions" @@ -1109,13 +1109,13 @@ A transition marker is a horizontal line <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td><samp> + <tr valign="top"> + <td><samp> The |biohazard| symbol must be used on containers used to dispose of medical waste.</samp> @@ -1123,52 +1123,52 @@ dispose of medical waste.</samp> <p><samp> .. |biohazard| image:: biohazard.png</samp> - <td> + <td> - <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol + <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol must be used on containers used to dispose of medical waste. </table> - <h2><a href="#contents" name="comments" class="backref" + <h2><a href="#contents" name="comments" class="backref" >Comments</a></h2> <p>(<a href="../../spec/rst/reStructuredText.html#comments">details?</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result </thead> <tbody> - <tr valign="top"> - <td><samp>.. This text will not be shown</samp> - <br><samp>   (but, for instance, in HTML might be</samp> - <br><samp>   rendered as an HTML comment)</samp> - - <td>  - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - - <tr valign="top"> - <td> - <samp>An empty "comment" directive does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp>        So this block is not "lost",</samp> - <br><samp>        despite its indentation.</samp> - <td> - An empty "comment" directive does not - "consume" following blocks. - <blockquote> - So this block is not "lost", - despite its indentation. - </blockquote> + <tr valign="top"> + <td><samp>.. This text will not be shown</samp> + <br><samp>   (but, for instance, in HTML might be</samp> + <br><samp>   rendered as an HTML comment)</samp> + + <td>  + <!-- This text will not be shown --> + <!-- (but, for instance in HTML might be --> + <!-- rendered as an HTML comment) --> + + <tr valign="top"> + <td> + <samp>An empty "comment" directive does not</samp> + <br><samp>"consume" following blocks.</samp> + <p><samp>..</samp> + <p><samp>        So this block is not "lost",</samp> + <br><samp>        despite its indentation.</samp> + <td> + An empty "comment" directive does not + "consume" following blocks. + <blockquote> + So this block is not "lost", + despite its indentation. + </blockquote> </table> - <h2><a href="#contents" name="getting-help" class="backref" + <h2><a href="#contents" name="getting-help" class="backref" >Getting Help</a></h2> <p>Users who have questions or need assistance with Docutils or @@ -1183,9 +1183,9 @@ dispose of medical waste.</samp> <p><hr> <address> <p>Authors: - <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or - <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) + <a href="http://www.tibsnjoan.co.uk/">Tibs</a> + (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or + <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) and David Goodger (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) </address> -- cgit v1.2.1 From c1554e0cae13b502620d286b2d7519c7f4c53909 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Sep 2002 03:15:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@631 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 593460421..6c02228ae 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -141,7 +141,7 @@ Examples: Either interpret PEPs' indented sections or convert existing PEPs to reStructuredText (or both?). - The "PEP Reader" is being implemented in module + The "PEP Reader" has been implemented in module ``docutils.readers.pep``. - Wiki: Global reference lookups of "wiki links" incorporated into -- cgit v1.2.1 From cd1e9b4d9c0e90cb2a42c23e70806ef6e531342f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Sep 2002 03:29:58 +0000 Subject: Added a note redirecting newbies to the user docs. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@632 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6cb80cf1f..fac98c63f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -6,6 +6,17 @@ :Revision: $Revision$ :Date: $Date$ +.. Note:: + + This document is a detailed technical specification; it is not a + tutorial or a primer. If this is your first exposure to + reStructuredText, please read `A ReStructuredText Primer`_ and the + `Quick reStructuredText`_ user reference first. + +.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html +.. _Quick reStructuredText: ../../docs/rst/quickref.html + + reStructuredText_ is plaintext that uses simple and intuitive constructs to indicate the structure of a document. These constructs are equally easy to read in raw and processed forms. This document is @@ -2515,10 +2526,8 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Document Tree Structure: - http://docutils.sourceforge.net/spec/doctree.txt -.. _Generic Plaintext Document Interface DTD: - http://docutils.sourceforge.net/spec/gpdi.dtd +.. _Docutils Document Tree Structure: ../doctree.html +.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From c5f12b33792e48d2b90f0e07fb84c8bd77004ca6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 6 Sep 2002 02:12:10 +0000 Subject: minor clarification git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@635 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index c335ac97a..50f7397ce 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -74,7 +74,10 @@ text, it will generally be OK -- ReST is pretty smart. For example, this * asterisk is handled just fine. If you actually want text \*surrounded by asterisks* to **not** be italicised, then you need to indicate that the asterisk is not special. You do this by placing a -backslash just before it, like so "``\*``" (quickref__). +backslash just before it, like so "``\*``" (quickref__), or by +enclosing it in double back-quotes (inline literals), like this:: + + ``\*`` __ quickref.html#escaping -- cgit v1.2.1 From ce0cc744ffdceb30b746c7292f2262a5841a0610 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 6 Sep 2002 02:13:56 +0000 Subject: Expanded description of inline markup start-strings in non-markup contexts. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@637 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index fac98c63f..6129f3f0f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1506,7 +1506,7 @@ marks [#]_: .. [#] This list was inspired by the list of symbols for "Note Reference Marks" in The Chicago Manual of Style, 14th edition, - section 12.51. "Parallels" ("\|\|") were given in CMoS instead of + section 12.51. "Parallels" ("||") were given in CMoS instead of the pilcrow. The last four symbols (the card suits) were added arbitrarily. @@ -2189,8 +2189,21 @@ end-string will not be recognized or processed. literals`_. See `Escaping Mechanism`_ above for details. For example, none of the following are recognized as containing inline -markup start-strings: " * ", '"*"', "'*'", "(*)", "(* ", "[*]", "{*}", -"\*", " ` ", etc. +markup start-strings: + +- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_* +- double asterisks: ** a**b O(N**2) etc. +- backquotes: ` `` etc. +- underscores: _ __ __init__ __init__() etc. +- vertical bars: | || etc. + +It may be desirable to use inline literals for some of these anyhow, +especially if they represent code snippets. It's a judgement call. + +These cases *do* require either literal-quoting or escaping to avoid +misinterpretation:: + + *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt The inline markup recognition rules were devised intentionally to allow 90% of non-markup uses of "*", "`", "_", and "|" *without* -- cgit v1.2.1 From abfba76cb86e08408273238e2af0ace0e5d04827 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 6 Sep 2002 03:47:22 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@639 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 32446f411..9046a2375 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -109,6 +109,15 @@ General HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to ``core.publish_file()``? +- @@@@ All system messages should have a "line" attribute, to improve + diagnostic output. So all elements constructed by the parser should + have internal "line" ("lineno"/"line_number") attributes. Is there + any way we can get this to happen automagically, without having to + add the attribute manually to each object? + +- @@ Standalone Reader: Implement an option to turn off the DocTitle + transform. + Documentation ------------- @@ -775,6 +784,11 @@ HTML Writer - Add more support for <link> elements, especially for navigation bars. +- @@ Add a "don't compact lists" option. + +- @@@ Unindent line blocks. (Authors can indent the directive to get + indented line blocks.) + Front-End Tools --------------- @@ -823,6 +837,10 @@ Front-End Tools - Implement the "sectnum" directive as a command-line option also? +- @@ Add an option to recognize ``PEP \d+`` text as standalone + hyperlinks. Another for ``RFC[- ]?\d+``. Then just set defaults in + readers/pep.py. + Project Policies ================ -- cgit v1.2.1 From 457cedb4121fb79d8e518cba15fe2a48d6a81427 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:28:17 +0000 Subject: Added an admonition against using field lists arbitrarily. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@641 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index b03e11b8b..855d8ef84 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Version 0.10a of 2002-09-04</em> + <br align="right"><em>Version 0.11 of 2002-09-06</em> <p>The full details of the markup may be found on the @@ -446,6 +446,13 @@ </table> </table> + <p>Field lists are used as part of an extension syntax, such as + options for <a href="#directives">directives</a>, or database-like + records meant for further processing. Field lists should only be + used when and where application code specifically expects them; + they should <em>not</em> be used as arbitrary constructs in + documents. + <h2><a href="#contents" name="option-lists" class="backref" >Option Lists</a></h2> -- cgit v1.2.1 From b17e8dc9af34595c69f15972f91ccfcd4cc6ec4b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:29:49 +0000 Subject: Added "compact_lists", "pep_references", and "rfc_references". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@642 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 105115266..9f0a78670 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -38,6 +38,8 @@ input (stdin) is used for the source as well. Getting Help ------------ +First, try the "``--help``" option each front-end tool has. + Users who have questions or need assistance with Docutils or reStructuredText should `post a message`_ to the `Docutils-Users mailing list`_. The `Docutils project web site`_ has more @@ -322,6 +324,15 @@ Some knowledge of Python_ is assumed for some attributes. ==================== ================================================ Config Entry Name Description ==================== ================================================ +compact_lists (HTML Writer.) Remove extra vertical whitespace + between items of bullet lists and enumerated + lists, when list items are "simple" (i.e., all + items each contain one paragraph and/or one + "simple" sublist only). + + Default: enabled (1). Options: + ``--compact-lists, --no-compact-lists``. +-------------------- ------------------------------------------------ config Path to a configuration file to read (if it exists) [#pwd]_. Settings may override defaults and earlier settings. This is only effective as @@ -363,8 +374,8 @@ footnote_backlinks Enable or disable backlinks from footnotes and footnote_references (HTML Writer.) Format for footnote references, one of "superscript" or "brackets". - Default: "superscript". Options: - ``--footnote-references``. + Default: "superscript"; "brackets" in PEP/HTML + Writer. Options: ``--footnote-references``. -------------------- ------------------------------------------------ generator Include a "Generated by Docutils" credit and link in the document footer. @@ -413,6 +424,12 @@ pep_home (PEP/HTML Writer.) Home URL prefix for PEPs. Default: current directory ("."). Options: ``--pep-home``. -------------------- ------------------------------------------------ +pep_references (reStructuredText Parser.) Recognize and link + to PEP references (like "PEP 258") + + Default: disabled (None); enabled (1) in PEP + Reader. Options: ``--pep-references``. +-------------------- ------------------------------------------------ pep_stylesheet (PEP/HTML Writer.) CSS stylesheet URL, used verbatim. Overrides HTML stylesheet (``--stylesheet``). @@ -450,6 +467,12 @@ report_level Verbosity threshold at or above which system Default: warning (2). Options: ``--report, -r, --verbose, --quiet, -q``. -------------------- ------------------------------------------------ +rfc_references (reStructuredText Parser.) Recognize and link + to RFC references (like "RFC 822") + + Default: disabled (None); enabled (1) in PEP + Reader. Options: ``--rfc-references``. +-------------------- ------------------------------------------------ silent (``buildhtml.py`` front end.) Work silently (no progress messages). Independent of "report_level". -- cgit v1.2.1 From 22255487b5b00ef04ccee60b61cf641a813e34a4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:37:29 +0000 Subject: Tweaked the "line-block" description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@648 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 152bb37a7..16e352cf8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -242,20 +242,22 @@ The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. It is equivalent to a `parsed literal block`_ with different rendering: typically in an ordinary serif typeface instead of a -typewriter/monospaced face. Line blocks are useful for address blocks -and verse (poetry, song lyrics), where the structure of lines is -significant. For example, here's a classic:: +typewriter/monospaced face, and not automatically indented. (Have the +line-block directive begin a block quote to get an indented line +block.) Line blocks are useful for address blocks and verse (poetry, +song lyrics), where the structure of lines is significant. For +example, here's a classic:: "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by Ewan McTeagle (for Lassie O'Shea): - .. line-block:: + .. line-block:: - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. + Lend us a couple of bob till Thursday. + I'm absolutely skint. + But I'm expecting a postal order and I can pay you back + as soon as it comes. + Love, Ewan. Parsed Literal Block -- cgit v1.2.1 From 25bf0b8d0031971e15ac206642bc3ca5ef279c33 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:38:25 +0000 Subject: Added pointers to material for new users. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@649 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index ea5c6ca90..0ec112a47 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -18,18 +18,25 @@ application domains. Its parser is a component of Docutils_. This document defines the goals_ of reStructuredText and provides a history_ of the project. It is written using the reStructuredText -markup, and therefore serves as an example of its use. Please also -see an analysis of the `Problems With StructuredText`_ and the -`reStructuredText Markup Specification`_ itself at the subproject's -web page, http://docutils.sourceforge.net/rst.html. +markup, and therefore serves as an example of its use. For a gentle +introduction to using reStructuredText, please read `A +ReStructuredText Primer`_. The `Quick reStructuredText`_ user +reference is also useful. The `reStructuredText Markup +Specification`_ is the definitive reference. There is also an +analysis of the `Problems With StructuredText`_. + +ReStructuredText's web page is +http://docutils.sourceforge.net/rst.html. .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _StructuredText: http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Problems with StructuredText: problems.html +.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html +.. _Quick reStructuredText: ../../docs/rst/quickref.html .. _reStructuredText Markup Specification: reStructuredText.html +.. _Problems with StructuredText: problems.html Goals -- cgit v1.2.1 From 27cbc2015c36bac9e75417045fc0ba2fc949d72c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:39:01 +0000 Subject: Strengthened the admonition against using field lists arbitrarily. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@650 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6129f3f0f..f8ed0e167 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -783,13 +783,15 @@ Field Lists DTD elements: field_list, field, field_name, field_argument, field_body. -Field lists are most often used as part of an extension syntax, such -as options for directives_, or database-like records meant for further +Field lists are used as part of an extension syntax, such as options +for directives_, or database-like records meant for further processing. They are not intended to be an alternative to definition -lists. Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts. See -`Bibliographic Fields`_ below for one example, or the "image" -directive in `reStructuredText Directives`_ for another. +lists or tables. Applications of reStructuredText may recognize field +names and transform fields or field bodies in certain contexts. Field +lists should only be used when and where application code specifically +expects them; they should *not* be used as arbitrary constructs in +documents. See `Bibliographic Fields`_ below for one example, or the +"image" directive in `reStructuredText Directives`_ for another. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -- cgit v1.2.1 From 49373e9eff9b650bd989452f2067cf2b78a5cebe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Sep 2002 02:42:09 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@653 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 13 ++----------- docs/peps/pep-0258.txt | 5 +---- 2 files changed, 3 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 9046a2375..6c3ac2546 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -115,8 +115,8 @@ General any way we can get this to happen automagically, without having to add the attribute manually to each object? -- @@ Standalone Reader: Implement an option to turn off the DocTitle - transform. +- Standalone Reader: Implement an option to turn off the DocTitle + transform? Documentation @@ -784,11 +784,6 @@ HTML Writer - Add more support for <link> elements, especially for navigation bars. -- @@ Add a "don't compact lists" option. - -- @@@ Unindent line blocks. (Authors can indent the directive to get - indented line blocks.) - Front-End Tools --------------- @@ -837,10 +832,6 @@ Front-End Tools - Implement the "sectnum" directive as a command-line option also? -- @@ Add an option to recognize ``PEP \d+`` text as standalone - hyperlinks. Another for ``RFC[- ]?\d+``. Then just set defaults in - readers/pep.py. - Project Policies ================ diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 6c02228ae..5af970734 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -138,11 +138,8 @@ Examples: - Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. - PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs. - Either interpret PEPs' indented sections or convert existing PEPs to - reStructuredText (or both?). - The "PEP Reader" has been implemented in module - ``docutils.readers.pep``. + ``docutils.readers.pep``; see PEP 287 and PEP 12. - Wiki: Global reference lookups of "wiki links" incorporated into transforms. (CamelCase only or unrestricted?) Lazy -- cgit v1.2.1 From 9a91d7c843178280693025015b88590c8355f820 Mon Sep 17 00:00:00 2001 From: chodorowski <chodorowski@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Sep 2002 17:27:35 +0000 Subject: Updated with respect to the 'align' option of the 'image' directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@656 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 16e352cf8..9df09b2d1 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -131,6 +131,7 @@ _`image options`. For example:: :width: 200 :scale: 50 :alt: alternate text + :align: right The following options are recognized: @@ -147,6 +148,12 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size. +``align`` : keyword + The alignment of the image. Allowed values are "top", "middle" and + "bottom" which control the vertical alignment (relative to the text + baseline) in addition to "left", "center" and "right" which control + the horizontal alignment (allowing you to float the image, having the + text flow around it). Figure -- cgit v1.2.1 From 92bce10953abbbdee17337bd6cdcb01208144810 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 10 Sep 2002 03:25:23 +0000 Subject: Clarified the "image" directive's "align" attribute description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@657 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9df09b2d1..897e276eb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -148,12 +148,15 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size. -``align`` : keyword - The alignment of the image. Allowed values are "top", "middle" and - "bottom" which control the vertical alignment (relative to the text - baseline) in addition to "left", "center" and "right" which control - the horizontal alignment (allowing you to float the image, having the - text flow around it). +``align`` : "top", "middle", "bottom", "left", "center", or "right" + The alignment of the image, equivalent to the HTML ``<img>`` tag's + "align" attribute. The values "top", "middle", and "bottom" + control an image's vertical alignment (relative to the text + baseline); they are only useful for inline images (substitutions). + The values "left", "center", and "right" control an image's + horizontal alignment, allowing the image to float and have the + text flow around it. The specific behavior depends upon the + browser or rendering software used. Figure -- cgit v1.2.1 From 516af13e3fd432c21b1d4b76f656ea848ad8f8e0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 11 Sep 2002 02:46:26 +0000 Subject: Removed the admonition against using field lists arbitrarily. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@663 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 855d8ef84..faf38784d 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Version 0.11 of 2002-09-06</em> + <br align="right"><em>Version 0.12 of 2002-09-10</em> <p>The full details of the markup may be found on the @@ -448,10 +448,8 @@ <p>Field lists are used as part of an extension syntax, such as options for <a href="#directives">directives</a>, or database-like - records meant for further processing. Field lists should only be - used when and where application code specifically expects them; - they should <em>not</em> be used as arbitrary constructs in - documents. + records meant for further processing. Field lists may also be + used as generic two-column table constructs in documents. <h2><a href="#contents" name="option-lists" class="backref" >Option Lists</a></h2> -- cgit v1.2.1 From a07bc663d7654004db7594bb1601525b18d46f4a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 11 Sep 2002 02:52:01 +0000 Subject: Removed "field_argument" element & support; "field_name" may contain multiple words and whitespace. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@664 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 9 +------ docs/ref/docutils.dtd | 6 +---- docs/ref/rst/restructuredtext.txt | 57 +++++++++++++++++---------------------- 3 files changed, 26 insertions(+), 46 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 762d3e4b1..16a700ce4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -185,8 +185,7 @@ always occur within specific parent elements, never at the body element level (beside paragraphs, etc.). Category members (simple): caption_, classifier_, colspec_, -field_argument_, field_name_, label_, option_argument_, -option_string_, term_ +field_name_, label_, option_argument_, option_string_, term_ Category members (compound): definition_, definition_list_item_, description_, entry_, field_, field_body_, legend_, list_item_, @@ -1510,12 +1509,6 @@ See list_item_ for another example. `To be completed`_. -``field_argument`` -================== - -`To be completed`_. - - ``field_body`` ============== diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a2d8a9e45..19094bbf2 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -314,16 +314,12 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT field_list (field+)> <!ATTLIST field_list %basic.atts;> -<!ELEMENT field (field_name, field_argument*, field_body)> +<!ELEMENT field (field_name, field_body)> <!ATTLIST field %basic.atts;> <!ELEMENT field_name (#PCDATA)> <!ATTLIST field_name %basic.atts;> -<!-- Support for Javadoc-style tags with arguments. --> -<!ELEMENT field_argument (#PCDATA)> -<!ATTLIST field_argument %basic.atts;> - <!-- May be empty. --> <!ELEMENT field_body (%body.elements;)*> <!ATTLIST field_body %basic.atts;> diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f8ed0e167..96a5449b8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -102,8 +102,8 @@ Here are examples of `body elements`_: database records. They are often part of an extension syntax. - :how: The field marker is a colon, the field name, optional - field arguments, and a colon. + :how: The field marker is a colon, the field name, and a + colon. The field body may contain one or more body elements, indented relative to the field marker. @@ -780,30 +780,26 @@ Syntax diagram:: Field Lists ----------- -DTD elements: field_list, field, field_name, field_argument, -field_body. +DTD elements: field_list, field, field_name, field_body. Field lists are used as part of an extension syntax, such as options for directives_, or database-like records meant for further -processing. They are not intended to be an alternative to definition -lists or tables. Applications of reStructuredText may recognize field -names and transform fields or field bodies in certain contexts. Field -lists should only be used when and where application code specifically -expects them; they should *not* be used as arbitrary constructs in -documents. See `Bibliographic Fields`_ below for one example, or the -"image" directive in `reStructuredText Directives`_ for another. +processing. They may also be used for two-column table-like +structures resembling database records (label & data pairs). +Applications of reStructuredText may recognize field names and +transform fields or field bodies in certain contexts. For examples, +see `Bibliographic Fields`_ below, or the "image" and "meta" +directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -numbers, and punctuation, except colons (":") and whitespace. Field -names are case-insensitive. There may be additional data separated -from the field name, called field arguments. The field name and -optional field argument(s), along with a single colon prefix and -suffix, together form the field marker. The field marker is followed -by whitespace and the field body. The field body may contain multiple -body elements, indented relative to the field marker. The first line -after the field name marker determines the indentation of the field -body. For example:: +numbers, whitespace, and punctuation, except colons (":"). Field +names are case-insensitive. The field name, along with a single colon +prefix and suffix, together form the field marker. The field marker +is followed by whitespace and the field body. The field body may +contain multiple body elements, indented relative to the field marker. +The first line after the field name marker determines the indentation +of the field body. For example:: :Date: 2001-08-16 :Version: 1 @@ -816,16 +812,11 @@ body. For example:: field name marker, and they must line up with each other. :Parameter i: integer -Field arguments are separated from the field name and each other by -whitespace, and may not contain colons (":"). The interpretation of -field arguments is up to the application. For example:: - - :name1 word number=1: - Both "word" and "number=1" are single words. - -The syntax for field arguments may be extended in the future. For -example, quoted phrases may be treated as a single argument, and -direct support for the "name=value" syntax may be added. +The interpretation of individual words in a multi-word field name is +up to the application. The application may specify a syntax for the +field name. For example, second and subsequent words may be treated +as "arguments", quoted phrases may be treated as a single argument, +and direct support for the "name=value" syntax may be added. Standard RFC822_ headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a @@ -836,9 +827,9 @@ used. Syntax diagram (simplified):: - +------------------------------+------------+ - | ":" name (" " argument)* ":" | field body | - +-------+----------------------+ | + +--------------------+----------------------+ + | ":" field name ":" | field body | + +-------+------------+ | | (body elements)+ | +-----------------------------------+ -- cgit v1.2.1 From 2ba8fffc2b3bf0e74aedfd33533f10a54a5b77be Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 11 Sep 2002 02:54:23 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@665 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ docs/user/tools.txt | 18 +++++++++++------- 2 files changed, 18 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6c3ac2546..69cc87a07 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -118,6 +118,13 @@ General - Standalone Reader: Implement an option to turn off the DocTitle transform? +- Add /usr/etc/docutils.conf to config file list? System-wide, + whereas /etc/docutils.conf is machine-specific. + /usr/local/etc/docutils.conf too? See the `Filesystem Hierarchy + Standard`_. + + .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. + Documentation ------------- diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 9f0a78670..31b6a37e9 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -271,17 +271,19 @@ files, in the following order: located in the current directory. The Docutils front end has to be executed from the directory containing this configuration file for it to take effect (note that this may have nothing to do with the - location of the source files). The project-specific configuration - file overrides the system-wide file. + location of the source files). Settings in the project-specific + configuration file will override corresponding settings in the + system-wide file. 3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. This file overrides both the - system-wide and project-specific configuration files. + located in the user's home directory. Settings in this file will + override corresponding settings in both the system-wide and + project-specific configuration files. If more than one configuration file is found, all will be read but later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a -system-wide entry. +"stylesheet" entry in the system-wide file. In addition, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is read after @@ -300,8 +302,10 @@ From its documentation: retrieval. Lines beginning with "#" or ";" are ignored and may be used to provide comments. -Docutils only uses an "[options]" section; all other sections will be -ignored. +Docutils currently only uses an "[options]" section; all other +sections are ignored. + +.. Note:: The configuration file format may change in the future. Configuration entry names correspond to internal option attributes. Underscores ("_") and hyphens ("-") can be used interchangably in -- cgit v1.2.1 From d784ac442aeddc2fa4fe445433bf19b48af3d4f9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 12 Sep 2002 02:16:30 +0000 Subject: Added mention of minimum section title underline lengths. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@666 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 31 +++++++++++++++++++------------ docs/user/rst/quickstart.txt | 6 ++++-- 2 files changed, 23 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index faf38784d..4005b9fd3 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Version 0.12 of 2002-09-10</em> + <br align="right"><em>Updated 2002-09-11</em> <p>The full details of the markup may be found on the @@ -249,16 +249,20 @@ <tbody> <tr valign="top"> <td> - <samp>=====</samp> - <br><samp>Title</samp> - <br><samp>=====</samp> - <br><samp>Subtitle</samp> - <br><samp>--------</samp> - <br><samp>Titles are underlined (or over-</samp> - <br><samp>and underlined) with a printing</samp> - <br><samp>nonalphanumeric 7-bit ASCII</samp> - <br><samp>character. Recommended choices</samp> - <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> +<samp>=====</samp> +<br><samp>Title</samp> +<br><samp>=====</samp> +<br><samp>Subtitle</samp> +<br><samp>--------</samp> +<br><samp>Titles are underlined (or over-</samp> +<br><samp>and underlined) with a printing</samp> +<br><samp>nonalphanumeric 7-bit ASCII</samp> +<br><samp>character. Recommended choices</samp> +<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> +<br><samp>The underline/overline must be at</samp> +<br><samp>least as long as the title text,</samp> +<br><samp>and a minumum of 4 characters long.</samp> + <td> <font size="+2"><strong>Title</strong></font> <p><font size="+1"><strong>Subtitle</strong></font> @@ -267,6 +271,9 @@ nonalphanumeric 7-bit ASCII character. Recommended choices are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". + The underline/overline must be at + least as long as the title text, + and a minumum of 4 characters long. </table> <h2><a href="#contents" name="paragraphs" class="backref" @@ -848,7 +855,7 @@ A transition marker is a horizontal line <p>They may be assigned 'autonumber labels' - for instance, <sup><a href="#fourth">4</a></sup> and <sup><a href="#third">3</a></sup>. - + <p><table> <tr><td colspan="2"><hr> <!-- <tr><td colspan="2">Footnotes: --> diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index 50f7397ce..de35f4eec 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -250,8 +250,10 @@ These are a single line of text (one or more words) with an underline (and optionally an overline) in dashes "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable -with. Be consistent though, since all sections marked with the same -underline style are deemed to be at the same level:: +with. The underline/overline must be at least as long as the title +text, and a minumum of 4 characters long. Be consistent though, since +all sections marked with the same underline style are deemed to be at +the same level:: Chapter 1 Title =============== -- cgit v1.2.1 From e6fbaf6eeb15c5a8e4b7155f6c3d4744cc03b636 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 12 Sep 2002 02:17:28 +0000 Subject: Added "--embed-stylesheet" & "--link-stylesheet". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@667 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 31b6a37e9..dc7e9243e 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -368,6 +368,15 @@ dump_internals (Hidden option.) At the end of processing, Default: don't (None). Options: ``--dump-internals``. -------------------- ------------------------------------------------ +embed_stylesheet (HTML Writer.) Embed the stylesheet in the + output HTML file. The stylesheet file must be + accessible during processing. The stylesheet is + embedded inside a comment, so it must not + contain the text "--" (two hyphens). + + Default: link, don't embed (None). Options: + ``--embed-stylesheet, --link-stylesheet``. +-------------------- ------------------------------------------------ footnote_backlinks Enable or disable backlinks from footnotes and citations to their references. @@ -441,7 +450,8 @@ pep_stylesheet (PEP/HTML Writer.) CSS stylesheet URL, used Default: None. Options: ``--pep-stylesheet``. -------------------- ------------------------------------------------ pep_stylesheet_path (PEP/HTML Writer.) Path to CSS stylesheet - [#pwd]_. Overrides HTML stylesheet + [#pwd]_. Path is adjusted relative to the + output HTML file. Overrides HTML stylesheet (``--stylesheet``) and PEP stylesheet (``--pep-stylesheet``). @@ -505,7 +515,8 @@ stylesheet (HTML Writer.) CSS stylesheet URL, used -------------------- ------------------------------------------------ stylesheet-path (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option - (``--stylesheet``). + (``--stylesheet``). Path is adjusted relative + to the output HTML file. Default: None. Options: ``--stylesheet``. -------------------- ------------------------------------------------ -- cgit v1.2.1 From 98fa562acf890dccb7b004e8be5ffe358e95f53f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 15 Sep 2002 16:31:29 +0000 Subject: converted bullet lists to field lists; updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@680 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index dc7e9243e..2626b2419 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -57,9 +57,9 @@ The Tools buildhtml.py ------------ -* Readers: Standalone, PEP -* Parser: reStructuredText -* Writers: HTML, PEP/HTML +:Readers: Standalone, PEP +:Parser: reStructuredText +:Writers: HTML, PEP/HTML Use ``buildhtml.py`` to generate .html from all the .txt files (including PEPs) in each <directory> given, and their subdirectories @@ -94,9 +94,9 @@ altogether. html.py ------- -* Reader: Standalone -* Parser: reStructuredText -* Writer: HTML +:Reader: Standalone +:Parser: reStructuredText +:Writer: HTML The ``html.py`` front end reads standalone reStructuredText source files and produces HTML 4 (XHTML 1) output compatible with modern @@ -150,9 +150,9 @@ incremental experimentation. pep.py ------ -* Reader: PEP -* Parser: reStructuredText -* Writer: PEP/HTML +:Reader: PEP +:Parser: reStructuredText +:Writer: PEP/HTML ``pep.py`` reads a new-style PEP (marked up with reStructuredText) and produces HTML. It requires a template file and a stylesheet. By @@ -173,9 +173,9 @@ for more information. pep2html.py ----------- -* Reader: PEP -* Parser: reStructuredText -* Writer: PEP/HTML +:Reader: PEP +:Parser: reStructuredText +:Writer: PEP/HTML ``pep2html.py`` is a modified version of the original script by Fredrik Lundh, with support for Docutils added. It reads the @@ -194,9 +194,9 @@ files. If no arguments are given, all files of the form docutils-xml.py --------------- -* Reader: Standalone -* Parser: reStructuredText -* Writer: XML (Docutils native) +:Reader: Standalone +:Parser: reStructuredText +:Writer: XML (Docutils native) The ``docutils-xml.py`` front end produces Docutils-native XML output. This can be transformed with standard XML tools such as XSLT @@ -206,9 +206,9 @@ processors into arbitrary final forms. publish.py ---------- -* Reader: Standalone -* Parser: reStructuredText -* Writer: Pseudo-XML +:Reader: Standalone +:Parser: reStructuredText +:Writer: Pseudo-XML ``publish.py`` is used for debugging the Docutils Reader to Transform to Writer pipeline. It produces a compact pretty-printed @@ -220,9 +220,9 @@ attributes for any leftover "pending" elements are also given. quicktest.py ------------ -* Reader: N/A -* Parser: reStructuredText -* Writer: N/A +:Reader: N/A +:Parser: reStructuredText +:Writer: N/A The ``quicktest.py`` tool is used for testing the reStructuredText parser. It does not use a Docutils Reader or Writer or the standard @@ -479,7 +479,7 @@ report_level Verbosity threshold at or above which system messages are reported. Default: warning (2). Options: ``--report, -r, - --verbose, --quiet, -q``. + --verbose, -v, --quiet, -q``. -------------------- ------------------------------------------------ rfc_references (reStructuredText Parser.) Recognize and link to RFC references (like "RFC 822") -- cgit v1.2.1 From 7cbb92de5ba3bbe3a995f9b73f5775d7ef1c4d9e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 15 Sep 2002 16:34:13 +0000 Subject: updated "raw" and "include" directive descriptions; converted bullet lists to field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@682 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 250 +++++++++++++++++++------------------------- 1 file changed, 109 insertions(+), 141 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 897e276eb..c78e572c2 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,17 +36,14 @@ Specification`_ for syntax details. Admonitions ------------- -* Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning" - -* DTD Elements: attention, caution, danger, error, hint, important, - note, tip, warning - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Interpreted as body elements. +:Directive Types: "attention", "caution", "danger", "error", "hint", + "important", "note", "tip", "warning" +:DTD Elements: attention, caution, danger, error, hint, important, + note, tip, warning +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -101,15 +98,12 @@ There are two image directives: "image" and "figure". Image ===== -* Directive Type: "image" - -* DTD Element: image - -* Directive Block: - - - Arguments: One, required (image URI). - - Options: Possible. - - Content: None. +:Directive Type: "image" +:DTD Element: image +:Directive Block: + :Arguments: One, required (image URI). + :Options: Possible. + :Content: None. An "image" is a simple picture:: @@ -162,15 +156,13 @@ The following options are recognized: Figure ====== -* Directive Type: "figure" - -* DTD Elements: figure, image, caption, legend +:Directive Type: "figure" +:DTD Elements: figure, image, caption, legend +:Directive Block: -* Directive Block: - - - Arguments: One, required (image URI). - - Options: Possible. - - Content: Interpreted as the figure caption and an optional legend. + :Arguments: One, required (image URI). + :Options: Possible. + :Content: Interpreted as the figure caption and an optional legend. A "figure" consists of image_ data (including `image options`_), an optional caption (a single paragraph), and an optional legend @@ -208,15 +200,12 @@ legend. To specify a legend without a caption, use an empty comment Topic ===== -* Directive Type: "topic" - -* DTD Element: topic - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Interpreted as the topic title and body. +:Directive Type: "topic" +:DTD Element: topic +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -238,15 +227,12 @@ up the topic body, interpreted as body elements. For example:: Line Block ========== -* Directive Type: "line-block" - -* DTD Element: line_block - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Becomes the body of the line block. +:Directive Type: "line-block" +:DTD Element: line_block +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -273,15 +259,12 @@ example, here's a classic:: Parsed Literal Block ==================== -* Directive Type: "literal-block" - -* DTD Element: literal_block - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Becomes the body of the literal block. +:Directive Type: "literal-block" +:DTD Element: literal_block +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -310,15 +293,12 @@ For example, all the element names in this content model are links:: Table of Contents ================= -* Directive Type: "contents" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: One, optional: title. - - Options: Possible. - - Content: None. +:Directive Type: "contents" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: One, optional: title. + :Options: Possible. + :Content: None. The "contents" directive inserts a table of contents (TOC) in two passes: initial parse and transform. During the initial parse, a @@ -370,15 +350,12 @@ The following options are recognized: Automatic Section Numbering =========================== -* Directive Type: "sectnum" or "section-autonumbering" (synonyms) - -* DTD Elements: pending, generated - -* Directive Block: - - - Arguments: None. - - Options: Possible. - - Content: None. +:Directive Type: "sectnum" or "section-autonumbering" (synonyms) +:DTD Elements: pending, generated +:Directive Block: + :Arguments: None. + :Options: Possible. + :Content: None. The "sectnum" (or "section-autonumbering") directive automatically numbers sections and subsections in a document. Section numbers are @@ -408,15 +385,12 @@ The following options are recognized: Target Footnotes ================ -* Directive Type: "target-notes" - -* DTD Elements: pending, footnote, footnote_reference - -* Directive Block must be empty: - - - Arguments: None. - - Options: None. - - Content: None. +:Directive Type: "target-notes" +:DTD Elements: pending, footnote, footnote_reference +:Directive Block: + :Arguments: None. + :Options: None. + :Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -430,15 +404,12 @@ Footnotes **NOT IMPLEMENTED YET** -* Directive Type: "footnotes" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: None? - - Options: Possible? - - Content: None. +:Directive Type: "footnotes" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: None? + :Options: Possible? + :Content: None. @@@ @@ -448,15 +419,12 @@ Citations **NOT IMPLEMENTED YET** -* Directive Type: "citations" - -* DTD Elements: pending, topic - -* Directive Block: - - - Arguments: None? - - Options: Possible? - - Content: None. +:Directive Type: "citations" +:DTD Elements: pending, topic +:Directive Block: + :Arguments: None? + :Options: Possible? + :Content: None. @@@ @@ -468,15 +436,12 @@ Citations Meta ==== -* Directive Type: "meta" - -* DTD Element: meta (non-standard) - -* Directive Block: - - - Arguments: None. - - Options: None. - - Content: Must contain a flat field list. +:Directive Type: "meta" +:DTD Element: meta (non-standard) +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Must contain a flat field list. The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web @@ -542,15 +507,12 @@ Including an External Fragment **NOT IMPLEMENTED YET** -* Directive Type: "include" - -* DTD Elements: depend on data being included - -* Directive Block: - - - Arguments: One, required (path to include file). - - Options: None. - - Content: None. +:Directive Type: "include" +:DTD Elements: depend on data being included +:Directive Block: + :Arguments: One, required (path to include file). + :Options: Possible. + :Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the @@ -558,23 +520,25 @@ directive. For example:: .. include:: inclusion.txt +The following options are recognized: + +``literal`` : empty + The entire included text is inserted into the document as a single + literal block (useful for program listings). + Raw Data Pass-Through ===================== **NOT IMPLEMENTED YET** -* Directive Type: "raw" - -* DTD Element: pending - -* Directive Block: - - - Arguments: One or two (?): one required (output format type), and - one optional (source path). - - Options: None? - - Content: Stored verbatim, uninterpreted. None (empty) if a source - path argument given. +:Directive Type: "raw" +:DTD Element: pending +:Directive Block: + :Arguments: One, required (output format type). + :Options: Possible + :Content: Stored verbatim, uninterpreted. None (empty) if a + "file" or "url" option given. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is @@ -598,24 +562,28 @@ output stream:: \documentclass[twocolumn]{article} Raw data can also be read from an external file, specified in an -optional second argument. In this case, the content block must be -empty. For example:: - - .. raw:: html inclusion.html +option. In this case, the content block must be empty. For example:: + .. raw:: html + :file: inclusion.html -Restructuredtext-Test-Directive -=============================== +The following options are recognized: -* Directive Type: "restructuredtext-test-directive" +``file`` : string + The filesystem path of a raw data file to be included. +``url`` : string + An Internet URL reference to a raw data file to be included. -* DTD Element: system_warning -* Directive Block: +Restructuredtext-Test-Directive +=============================== - - Arguments: None. - - Options: None. - - Content: Interpreted as a literal block. +:Directive Type: "restructuredtext-test-directive" +:DTD Element: system_warning +:Directive Block: + :Arguments: None. + :Options: None. + :Content: Interpreted as a literal block. This directive is provided for test purposes only. (Nobody is expected to type in a name *that* long!) It is converted into a -- cgit v1.2.1 From 30c9c811f9bc05a1a2e88252668eaf14a73a9107 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 15 Sep 2002 16:40:40 +0000 Subject: added a "Parallel Projects" subsection to "Project Policies"; updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@684 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 69cc87a07..6f68d85d0 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -40,11 +40,16 @@ Bugs Idea: two-pass hyperlink resolution, ignoring errors on the first pass? -- Section headers must have underlines at least 4 characters long. +- @@@ Section headers must have underlines at least 4 characters long. But when the section title is only 3 characters long, it's natural to underline with "===" (I just did). The parser should produce a warning in such cases. + Or should the parser simply recognize such short underlines? A + zero-tolerance policy might work: over/underlines of 3 or fewer + characters which are shorter than the "title" text are not + recognized as titles, and should generate an "info" message. + - 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 @@ -115,6 +120,20 @@ General any way we can get this to happen automagically, without having to add the attribute manually to each object? + Change stderr Reporter output to the GNU urilities format:: + + file:line: message + + or the BSD 4.3 cc format:: + + file(line): message + + The GNU utilities format doesn't work well on MacOS 9 & earlier, + where directory separators are colons. "filename.txt:1:" looks like + a file or directory path. Does MacOS X still use colons, or has it + switched to slashes? In any case, the ubiquity of the GNU utilities + probably overweighs any such problem. + - Standalone Reader: Implement an option to turn off the DocTitle transform? @@ -565,6 +584,19 @@ Directives - _`misc.exec`: Execute Python code & insert the results. Perhaps dangerous? + - _`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. @@ -791,6 +823,8 @@ HTML Writer - Add more support for <link> elements, especially for navigation bars. +- ``<meta>`` tags should be XML empty tags: ``<meta />``. + Front-End Tools --------------- @@ -1002,7 +1036,8 @@ 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_, and `reasonably complete`_. Adding to the `main source -tree`_ implies a commitment to the Docutils user community. +tree`_ or to a `parallel project`_ implies a commitment to the +Docutils user community. - Why the sandbox? @@ -1091,6 +1126,47 @@ structure is recommended:: # 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`_. + + +.. _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. + Release Checklist ================= -- cgit v1.2.1 From 3726101cf3b5aaab4e52591a64de77f7dc0fcbcc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:38:22 +0000 Subject: Removed the 4-character minimum for section title underlines. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@688 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 10 ++++------ docs/user/rst/quickref.html | 8 +++----- docs/user/rst/quickstart.txt | 5 ++--- 3 files changed, 9 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 96a5449b8..46673010b 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -452,12 +452,10 @@ matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any -non-alphanumeric printable 7-bit ASCII character [#]_. An -underline/overline must be at least 4 characters long (to avoid -mistaking ellipses ["..."] for overlines). When an overline is used, -the length and character used must match the underline. There may be -any number of levels of section titles, although some output formats -may have limits (HTML has 6 levels). +non-alphanumeric printable 7-bit ASCII character [#]_. When an +overline is used, the length and character used must match the +underline. There may be any number of levels of section titles, +although some output formats may have limits (HTML has 6 levels). .. [#] The following are all valid section title adornment characters:: diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 4005b9fd3..2cea6caed 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2002-09-11</em> + <br align="right"><em>Updated 2002-09-18</em> <p>The full details of the markup may be found on the @@ -260,8 +260,7 @@ <br><samp>character. Recommended choices</samp> <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> <br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text,</samp> -<br><samp>and a minumum of 4 characters long.</samp> +<br><samp>least as long as the title text.</samp> <td> <font size="+2"><strong>Title</strong></font> @@ -272,8 +271,7 @@ character. Recommended choices are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". The underline/overline must be at - least as long as the title text, - and a minumum of 4 characters long. + least as long as the title text. </table> <h2><a href="#contents" name="paragraphs" class="backref" diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index de35f4eec..ea97a7550 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -251,9 +251,8 @@ These are a single line of text (one or more words) with an underline "``======``", tildes "``~~~~~~``" or any of the non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable with. The underline/overline must be at least as long as the title -text, and a minumum of 4 characters long. Be consistent though, since -all sections marked with the same underline style are deemed to be at -the same level:: +text. Be consistent though, since all sections marked with the same +underline style are deemed to be at the same level:: Chapter 1 Title =============== -- cgit v1.2.1 From b95ac892ffd6bcd165b5459b0b0f656099c896cf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:46:40 +0000 Subject: converted definition lists to field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@693 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 399 ++++++++++++++++++++++++--------------------------- 1 file changed, 185 insertions(+), 214 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 16a700ce4..c490e5044 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -293,19 +293,18 @@ line_block_ element: whitespace is significant, especially newlines. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``address``: docinfo_, authors_ -Children +:Children: ``address`` elements contain text data plus `inline elements`_. -Analogies +:Analogies: ``address`` is analogous to the DocBook "address" element. -Processing +:Processing: As with the line_block_ element, newlines and other whitespace is significant and must be preserved. However, a monospaced typeface need not be used. @@ -320,11 +319,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``address`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus `xml:space`_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``address``. @@ -370,19 +369,18 @@ The ``author`` element holds the name of the author of the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``author``: docinfo_, authors_ -Children +:Children: ``author`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``author`` is analogous to the DocBook "author" element. -Processing +:Processing: See docinfo_. @@ -393,11 +391,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``author`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``author``. @@ -435,20 +433,19 @@ documents with multiple authors. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``authors``. -Children +:Children: ``authors`` elements may contain the following elements: author_, organization_, address_, contact_ -Analogies +:Analogies: ``authors`` is analogous to the DocBook "authors" element. -Processing +:Processing: See docinfo_. @@ -459,11 +456,11 @@ Content Model ((author_, organization_?, address_?, contact_?)+) -Attributes +:Attributes: The ``authors`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``authors``. @@ -516,18 +513,17 @@ uniformly marked with bullets. Bullets are typically simple dingbats Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``bullet_list``. -Children +:Children: ``bullet_list`` elements contain one or more list_item_ elements. -Analogies +:Analogies: ``bullet_list`` is analogous to the HTML "ul" element and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" @@ -535,7 +531,7 @@ Analogies affecting the meaning of the list. Bullet lists *are* often ordered; the ordering is simply left implicit. -Processing +:Processing: Each list item should begin a new vertical block, prefaced by a bullet/dingbat. @@ -547,7 +543,7 @@ Content Model (list_item_+) -Attributes +:Attributes: The ``bullet_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus bullet_. @@ -555,7 +551,7 @@ Attributes data. In reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``bullet_list``. The `%structure.model;`_ parameter entity indirectly includes ``bullet_list``. @@ -622,20 +618,19 @@ used to indicate the type of a variable. Details ------- -Category - `Body Subelements`_ (simple) +:Category: `Body Subelements`_ (simple) -Parents +:Parents: Only the definition_list_item_ element contains ``classifier``. -Children +:Children: ``classifier`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``classifier`` has no direct analogues in common DTDs. It can be emulated with primitives or type effects. -Processing +:Processing: See definition_list_item_. @@ -646,7 +641,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``classifier`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -705,21 +700,20 @@ is typically used for an email or web address. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: The following elements may contain ``contact``: docinfo_, authors_ -Children +:Children: ``contact`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``contact`` is analogous to the DocBook "email" element. The HTML "address" element serves a similar purpose. -Processing +:Processing: See docinfo_. @@ -730,11 +724,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``contact`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``contact``. @@ -772,20 +766,19 @@ The ``copyright`` element contains the document's copyright statement. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``copyright``. -Children +:Children: ``copyright`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``copyright`` is analogous to the DocBook "copyright" element. -Processing +:Processing: See docinfo_. @@ -796,11 +789,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``copyright`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``copyright``. @@ -844,19 +837,18 @@ last modification of the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``date``. -Children +:Children: ``date`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``date`` is analogous to the DocBook "date" element. -Processing +:Processing: Often used with the RCS/CVS keyword "Date". See docinfo_. @@ -867,11 +859,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``date`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``date``. @@ -912,21 +904,20 @@ footer_ element is implemented, populated with processing information Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``decoration``. -Children +:Children: ``decoration`` elements may contain `decorative elements`_. -Analogies +:Analogies: There are no direct analogies to ``decoration`` in HTML or in DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. -Processing +:Processing: See the individual `decorative elements`_. Content Model @@ -939,7 +930,7 @@ Content Model Although the content model doesn't specifically require contents, no empty ``decoration`` elements are ever created. -Attributes +:Attributes: The ``decoration`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -974,20 +965,19 @@ to define a term_ in a definition_list_. Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: Only definition_list_item_ elements contain ``definition``. -Children +:Children: ``definition`` elements may contain `body elements`_. -Analogies +:Analogies: ``definition`` is analogous to the HTML "dd" element and to the DocBook "listitem" element (inside a "variablelistentry" element). -Processing +:Processing: See definition_list_item_. @@ -998,7 +988,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``definition`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1022,23 +1012,22 @@ describe or classify things, for dialogues, or to itemize subtopics Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``definition_list``. -Children +:Children: ``definition_list`` elements contain one or more definition_list_item_ elements. -Analogies +:Analogies: ``definition_list`` is analogous to the HTML "dl" element and to the DocBook "variablelist" element. -Processing +:Processing: See definition_list_item_. @@ -1049,11 +1038,11 @@ Content Model (definition_list_item_+) -Attributes +:Attributes: The ``definition_list`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``definition_list``. The `%structure.model;`_ parameter entity indirectly includes ``definition_list``. @@ -1103,22 +1092,21 @@ term_/definition_ pair (with optional classifier_). Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: Only the definition_list_ element contains ``definition_list_item``. -Children +:Children: ``definition_list_item`` elements each contain a single term_, an optional classifier_, and a definition_. -Analogies +:Analogies: ``definition_list_item`` is analogous to the DocBook "variablelistentry" element. -Processing +:Processing: The optional classifier_ can be rendered differently from the term_. They should be separated visually, typically by spaces plus a colon or dash. @@ -1131,7 +1119,7 @@ Content Model (term_, classifier_?, definition_) -Attributes +:Attributes: The ``definition_list_item`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1195,21 +1183,20 @@ front matter of a book, such as the title page and copyright page. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``docinfo``. -Children +:Children: ``docinfo`` elements contain `bibliographic elements`_. -Analogies +:Analogies: ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. -Processing +:Processing: The ``docinfo`` element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from ``docinfo`` @@ -1231,7 +1218,7 @@ Content Model (`%bibliographic.elements;`_)+ -Attributes +:Attributes: The ``docinfo`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1307,17 +1294,16 @@ tree. It is the starting point for a document. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The ``document`` element has no parents. -Children +:Children: ``document`` elements may contain `structural subelements`_, `structural elements`_, and `body elements`_. -Analogies +:Analogies: ``document`` is analogous to the HTML "html" element and to several DocBook elements such as "book". @@ -1345,7 +1331,7 @@ programmatically. See the `%structure.model;`_ parameter entity for details of the body of a ``document``. -Attributes +:Attributes: The ``document`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1401,23 +1387,22 @@ uniformly marked with enumerator labels. Details ------- -Category - `Compound Body Elements`_ +:Category: `Compound Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``enumerated_list``. -Children +:Children: ``enumerated_list`` elements contain one or more list_item_ elements. -Analogies +:Analogies: ``enumerated_list`` is analogous to the HTML "ol" element and to the DocBook "orderedlist" element. -Processing +:Processing: Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1."). @@ -1429,7 +1414,7 @@ Content Model (list_item_+) -Attributes +:Attributes: The ``enumerated_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus enumtype_, prefix_, suffix_, and start_. @@ -1455,7 +1440,7 @@ Attributes list, in decimal. For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``enumerated_list``. The `%structure.model;`_ parameter entity indirectly includes ``enumerated_list``. @@ -1545,16 +1530,15 @@ processing information (datestamp, a link to Docutils_, etc.). Details ------- -Category - `Decorative Elements`_ +:Category: `Decorative Elements`_ -Parents +:Parents: Only the decoration_ element contains ``footer``. -Children +:Children: ``footer`` elements may contain `body elements`_. -Analogies +:Analogies: There are no direct analogies to ``footer`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1567,7 +1551,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``footer`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1621,16 +1605,15 @@ page. Docutils does not yet make use of the ``header`` element. Details ------- -Category - `Decorative Elements`_ +:Category: `Decorative Elements`_ -Parents +:Parents: Only the decoration_ element contains ``header``. -Children +:Children: ``header`` elements may contain `body elements`_. -Analogies +:Analogies: There are no direct analogies to ``header`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1643,7 +1626,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``header`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1706,21 +1689,20 @@ item. Details ------- -Category - `Body Subelements`_ (compound) +:Category: `Body Subelements`_ (compound) -Parents +:Parents: The bullet_list_ and enumerated_list_ elements contain ``list_item``. -Children +:Children: ``list_item`` elements may contain `body elements`_. -Analogies +:Analogies: ``list_item`` is analogous to the HTML "li" element and to the DocBook "listitem" element. -Processing +:Processing: See bullet_list_ or enumerated_list_. @@ -1731,7 +1713,7 @@ Content Model (`%body.elements;`_)+ -Attributes +:Attributes: The ``list_item`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -1832,21 +1814,20 @@ organization, or the organization responsible for the document. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``organization``. -Children +:Children: ``organization`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``organization`` is analogous to the DocBook "orgname", "corpname", or "publishername" elements. -Processing +:Processing: See docinfo_. @@ -1857,11 +1838,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``organization`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``organization``. @@ -1899,19 +1880,18 @@ single paragraph, a fundamental building block of documents. Details ------- -Category - `Simple Body Elements`_ +:Category: `Simple Body Elements`_ -Parents +:Parents: All elements employing the `%body.elements;`_ or `%structure.model;`_ parameter entities in their content models may contain ``paragraph``. -Children +:Children: ``paragraph`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``paragraph`` is analogous to the HTML "p" element and to the DocBook "para" elements. @@ -1923,11 +1903,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``paragraph`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%body.elements;`_ parameter entity directly includes ``paragraph``. The `%structure.model;`_ parameter entity indirectly includes ``paragraph``. @@ -1980,22 +1960,21 @@ It can be used alone or in conjunction with version_. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``revision``. -Children +:Children: ``revision`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``revision`` is analogous to but simpler than the DocBook "revision" element. It closely matches the DocBook "revnumber" element, but in a simpler context. -Processing +:Processing: Often used with the RCS/CVS keyword "Revision". See docinfo_. @@ -2006,11 +1985,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``revision`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``revision``. @@ -2060,18 +2039,17 @@ not after it. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The following elements may contain ``section``: document_, section_ -Children +:Children: ``section`` elements begin with a title_, and may contain `body elements`_ and transition_ and topic_ elements. -Analogies +:Analogies: ``section`` is analogous to DocBook recursive "section" elements, and to HTML "div" elements combined with "h1" etc. title elements. @@ -2087,11 +2065,11 @@ Content Model See the `%structure.model;`_ parameter entity for details of the body of a ``section``. -Attributes +:Attributes: The ``section`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%section.elements;`_ parameter entity directly includes ``section``. The `%structure.model;`_ parameter entity indirectly includes ``section``. @@ -2153,19 +2131,18 @@ such as "Draft", "Final", "Work In Progress", etc. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``status``. -Children +:Children: ``status`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``status`` is analogous to the DocBook "status" element. -Processing +:Processing: See docinfo_. @@ -2176,11 +2153,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``status`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``status``. @@ -2235,21 +2212,20 @@ The ``subtitle`` element stores the subtitle of a document_. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: Only the document_ element contains ``subtitle``. -Children +:Children: ``subtitle`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``subtitle`` is analogous to HTML header elements ("h2" etc.) and to the DocBook "subtitle" element. -Processing +:Processing: A document's subtitle is usually rendered smaller than its title_. @@ -2260,7 +2236,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``subtitle`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -2329,20 +2305,19 @@ definition_list_. Details ------- -Category - `Body Subelements`_ (simple) +:Category: `Body Subelements`_ (simple) -Parents +:Parents: Only the definition_list_item_ element contains ``term``. -Children +:Children: ``term`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``term`` is analogous to the HTML "dt" element and to the DocBook "term" element. -Processing +:Processing: See definition_list_item_. @@ -2353,7 +2328,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``term`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. @@ -2393,17 +2368,16 @@ topic_. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: The following elements may contain ``title``: document_, section_, topic_ -Children +:Children: ``title`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``title`` is analogous to HTML "title" and header ("h1" etc.) elements, and to the DocBook "title" element. @@ -2415,7 +2389,7 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``title`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus refid_ and auto_. @@ -2457,20 +2431,19 @@ a ``table`` or a ``list``, or inside another ``topic``. Details ------- -Category - `Structural Elements`_ +:Category: `Structural Elements`_ -Parents +:Parents: The following elements may contain ``topic``: document_, section_ -Children +:Children: ``topic`` elements begin with a title_ and may contain `body elements`_. -Analogies +:Analogies: ``topic`` is analogous to the DocBook "simplesect" element. -Processing +:Processing: A ``topic`` element should be set off from the rest of the document somehow, such as with indentation or a border. @@ -2483,11 +2456,11 @@ Content Model (title_?, (`%body.elements;`_)+) -Attributes +:Attributes: The ``topic`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%structure.model;`_ parameter entity directly includes ``topic``. @@ -2529,20 +2502,19 @@ See `Representation of Horizontal Rules`_ below. Details ------- -Category - `Structural Subelements`_ +:Category: `Structural Subelements`_ -Parents +:Parents: The following elements may contain ``transition``: document_, section_ -Children +:Children: ``transition`` is an empty element and has no children. -Analogies +:Analogies: ``transition`` is analogous to the HTML "hr" element. -Processing +:Processing: The ``transition`` element is typically rendered as vertical whitespace (more than that separating paragraphs), with or without a horizontal line or row of asterisks. In novels, transitions are @@ -2559,11 +2531,11 @@ Content Model The ``transition`` element has no content; it is a "point element". -Attributes +:Attributes: The ``transition`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%structure.model;`_ parameter entity directly includes ``transition``. @@ -2599,21 +2571,20 @@ It can be used alone or in conjunction with revision_. Details ------- -Category - `Bibliographic Elements`_ +:Category: `Bibliographic Elements`_ -Parents +:Parents: Only the docinfo_ element contains ``version``. -Children +:Children: ``version`` elements may contain text data plus `inline elements`_. -Analogies +:Analogies: ``version`` may be considered analogous to the DocBook "revision", "revnumber", or "biblioid" elements. -Processing +:Processing: Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ and revision_. @@ -2625,11 +2596,11 @@ Content Model `%text.model;`_ -Attributes +:Attributes: The ``version`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. -Parameter Entities +:Parameter Entities: The `%bibliographic.elements;`_ parameter entity directly includes ``version``. -- cgit v1.2.1 From a017e088a148600bf4ec7e20e0dd8967ea9837d0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:47:24 +0000 Subject: simplified data field lists git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@694 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 117 +++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 66 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index c78e572c2..cb22c621b 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -40,10 +40,9 @@ Specification`_ for syntax details. "important", "note", "tip", "warning" :DTD Elements: attention, caution, danger, error, hint, important, note, tip, warning -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as body elements. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as body elements. Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. @@ -100,10 +99,9 @@ Image :Directive Type: "image" :DTD Element: image -:Directive Block: - :Arguments: One, required (image URI). - :Options: Possible. - :Content: None. +:Directive Arguments: One, required (image URI). +:Directive Options: Possible. +:Directive Content: None. An "image" is a simple picture:: @@ -158,11 +156,10 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend -:Directive Block: - - :Arguments: One, required (image URI). - :Options: Possible. - :Content: Interpreted as the figure caption and an optional legend. +:Directive Arguments: One, required (image URI). +:Directive Options: Possible. +:Directive Content: Interpreted as the figure caption and an optional + legend. A "figure" consists of image_ data (including `image options`_), an optional caption (a single paragraph), and an optional legend @@ -202,10 +199,9 @@ Topic :Directive Type: "topic" :DTD Element: topic -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as the topic title and body. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the topic title and body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -229,10 +225,9 @@ Line Block :Directive Type: "line-block" :DTD Element: line_block -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Becomes the body of the line block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace (including linebreaks) is significant and inline markup is supported. @@ -261,10 +256,9 @@ Parsed Literal Block :Directive Type: "literal-block" :DTD Element: literal_block -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Becomes the body of the literal block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for inline markup. @@ -278,11 +272,11 @@ Backslash-escapes may be necessary in places. For example, all the element names in this content model are links:: .. parsed-literal:: - + ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, + subtitle_?)?, + docinfo_?, + decoration_?, `%structure.model;`_) @@ -295,10 +289,9 @@ Table of Contents :Directive Type: "contents" :DTD Elements: pending, topic -:Directive Block: - :Arguments: One, optional: title. - :Options: Possible. - :Content: None. +:Directive Arguments: One, optional: title. +:Directive Options: Possible. +:Directive Content: None. The "contents" directive inserts a table of contents (TOC) in two passes: initial parse and transform. During the initial parse, a @@ -352,10 +345,9 @@ Automatic Section Numbering :Directive Type: "sectnum" or "section-autonumbering" (synonyms) :DTD Elements: pending, generated -:Directive Block: - :Arguments: None. - :Options: Possible. - :Content: None. +:Directive Arguments: None. +:Directive Options: Possible. +:Directive Content: None. The "sectnum" (or "section-autonumbering") directive automatically numbers sections and subsections in a document. Section numbers are @@ -387,10 +379,9 @@ Target Footnotes :Directive Type: "target-notes" :DTD Elements: pending, footnote, footnote_reference -:Directive Block: - :Arguments: None. - :Options: None. - :Content: None. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: None. The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote references after each @@ -406,10 +397,9 @@ Footnotes :Directive Type: "footnotes" :DTD Elements: pending, topic -:Directive Block: - :Arguments: None? - :Options: Possible? - :Content: None. +:Directive Arguments: None? +:Directive Options: Possible? +:Directive Content: None. @@@ @@ -421,10 +411,9 @@ Citations :Directive Type: "citations" :DTD Elements: pending, topic -:Directive Block: - :Arguments: None? - :Options: Possible? - :Content: None. +:Directive Arguments: None? +:Directive Options: Possible? +:Directive Content: None. @@@ @@ -438,10 +427,9 @@ Meta :Directive Type: "meta" :DTD Element: meta (non-standard) -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Must contain a flat field list. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Must contain a flat field list. The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web @@ -509,10 +497,9 @@ Including an External Fragment :Directive Type: "include" :DTD Elements: depend on data being included -:Directive Block: - :Arguments: One, required (path to include file). - :Options: Possible. - :Content: None. +:Directive Arguments: One, required (path to include file). +:Directive Options: Possible. +:Directive Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the @@ -534,11 +521,10 @@ Raw Data Pass-Through :Directive Type: "raw" :DTD Element: pending -:Directive Block: - :Arguments: One, required (output format type). - :Options: Possible - :Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. +:Directive Arguments: One, required (output format type). +:Directive Options: Possible +:Directive Content: Stored verbatim, uninterpreted. None (empty) if a + "file" or "url" option given. The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is @@ -580,10 +566,9 @@ Restructuredtext-Test-Directive :Directive Type: "restructuredtext-test-directive" :DTD Element: system_warning -:Directive Block: - :Arguments: None. - :Options: None. - :Content: Interpreted as a literal block. +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as a literal block. This directive is provided for test purposes only. (Nobody is expected to type in a name *that* long!) It is converted into a -- cgit v1.2.1 From c2291595af5c117f10061fd9bf68fa0ff69d74fa Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Sep 2002 00:51:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@695 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6f68d85d0..d1500a7ed 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -40,16 +40,6 @@ Bugs Idea: two-pass hyperlink resolution, ignoring errors on the first pass? -- @@@ Section headers must have underlines at least 4 characters long. - But when the section title is only 3 characters long, it's natural - to underline with "===" (I just did). The parser should produce a - warning in such cases. - - Or should the parser simply recognize such short underlines? A - zero-tolerance policy might work: over/underlines of 3 or fewer - characters which are shorter than the "title" text are not - recognized as titles, and should generate an "info" message. - - 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 -- cgit v1.2.1 From 9af81413d14f2f8e27b1ce1230c7f59872b40c39 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 20 Sep 2002 02:49:37 +0000 Subject: spellchecked & updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@698 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 46673010b..0538d23c9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -54,7 +54,7 @@ elements, and may be structured into sections. Sections_ are indicated through title style (underlines & optional overlines). Sections contain body elements and/or subsections. Some body elements contain further elements, such as lists containing list items, which -in turn may contain paragraphs and other body elemens. Others, such +in turn may contain paragraphs and other body elements. Others, such as paragraphs, contain text and `inline markup`_ elements. Here are examples of `body elements`_: @@ -325,7 +325,7 @@ the field names):: :Hello: This field has a short field name, so aligning the field body with the first line is feasible. - :Number-of-African-swallows-requried-to-carry-a-coconut: It would + :Number-of-African-swallows-required-to-carry-a-coconut: It would be very difficult to align the field body with the left edge of the first line. It may even be preferable not to begin the body on the same line as the marker. @@ -370,11 +370,11 @@ Reference Names =============== Simple reference names are single words consisting of alphanumerics -plus internal hypens, underscores, and periods; no whitespace or other -characters are allowed. Footnote labels (Footnotes_ & `Footnote -References`_), citation labels (Citations_ & `Citation References`_), -`interpreted text`_ roles, and some `hyperlink references`_ use the -simple reference name syntax. +plus isolated (no two adjacent) internal hyphens, underscores, and +periods; no whitespace or other characters are allowed. Footnote +labels (Footnotes_ & `Footnote References`_), citation labels +(Citations_ & `Citation References`_), `interpreted text`_ roles, and +some `hyperlink references`_ use the simple reference name syntax. Reference names using punctuation or whose names are phrases (two or more space-separated words) are called "phrase-references". @@ -566,7 +566,7 @@ enforced, nor do differences in transition markers accomplish anything. It is recommended that a single consistent style be used. The processing system is free to render transitions in output in any -way it likes. For example, horizontal rules (``<HR>``) in HTML output +way it likes. For example, horizontal rules (``<hr>``) in HTML output would be an obvious choice. @@ -633,7 +633,7 @@ Here are examples of **incorrectly** formatted bullet lists:: (Warning) - The following line appears to be a new sublist, but it is not: - - This is a paragraph contination, not a sublist (since there's + - This is a paragraph continuation, not a sublist (since there's no blank line). This line is also incorrectly indented. - Warnings may be issued by the implementation. @@ -919,7 +919,7 @@ The RCS keyword processing only kicks in when all of these conditions hold: 1. The field list is in bibliographic context (first non-comment - contstruct in the document, after a document title if there is + construct in the document, after a document title if there is one). 2. The field name is a recognized bibliographic field name. @@ -949,7 +949,7 @@ descriptions, documenting a program's options. For example:: This is the second. Blank lines may be omitted between options (as above) or left in (as here and below). - --very-long-option A VMS-syle option. Note the adjustment for + --very-long-option A VMS-style option. Note the adjustment for the required two spaces. --an-even-longer-option @@ -1628,7 +1628,7 @@ indirect. After processing into HTML, the hyperlink might be expressed as:: - See the <A HREF="http://www.python.org">Python</A> home page + See the <a href="http://www.python.org">Python</a> home page for info. An external hyperlink's URI may begin on the same line as the @@ -1805,8 +1805,8 @@ directive code. There are three logical parts to the directive block: Individual directives can employ any combination of these parts. Directive arguments can be filesystem paths, URLs, title text, etc. Directive options are indicated using `field lists`_; the field names -and contents are directive-specific. Argumens and options must form a -contiguous block beginning on the first or second line of the +and contents are directive-specific. Arguments and options must form +a contiguous block beginning on the first or second line of the directive; a blank line indicates the beginning of the directive content block. If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content. @@ -1982,7 +1982,7 @@ Styles [#]_ Interpreted text is unsuitable for this purpose because the set of style names cannot be predefined - it is the domain of the content author, not the author of the parser and output - formatter - and there is no way to associate a stylename + formatter - and there is no way to associate a style name argument with an interpreted text style role. Also, it may be desirable to use the same mechanism for styling blocks:: @@ -2189,7 +2189,7 @@ markup start-strings: - vertical bars: | || etc. It may be desirable to use inline literals for some of these anyhow, -especially if they represent code snippets. It's a judgement call. +especially if they represent code snippets. It's a judgment call. These cases *do* require either literal-quoting or escaping to avoid misinterpretation:: @@ -2293,7 +2293,7 @@ references`_, we can add "index entry", "acronym", "class", "red", A role marker consists of a colon, the role name, and another colon. A role name is a single word consisting of alphanumerics plus internal -hypens, underscores, and periods; no whitespace or other characters +hyphens, underscores, and periods; no whitespace or other characters are allowed. @@ -2470,7 +2470,7 @@ as the link's text. For example:: would be marked up in HTML as:: - See <A HREF="http://www.python.org">http://www.python.org</A> for + See <a href="http://www.python.org">http://www.python.org</a> for info. Two forms of URI are recognized: @@ -2507,7 +2507,7 @@ Two forms of URI are recognized: recognize any absolute URI, as defined in RFC2396_ and RFC2732_. 2. Standalone email addresses, which are treated as if they were - ablsolute URIs with a "mailto:" scheme. Example:: + absolute URIs with a "mailto:" scheme. Example:: someone@somewhere.com -- cgit v1.2.1 From 5a81f0dc164410bf86ccd997dc7a59b6815c6ee1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 20 Sep 2002 02:49:52 +0000 Subject: *** empty log message *** git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@699 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0256.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index e6715eb14..8dc00f72e 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -184,7 +184,7 @@ The docstring processing system framework is broken up as follows: - Docstring extraction rules. - - Readers, which encapsulate the input context . + - Readers, which encapsulate the input context. - Parsers. -- cgit v1.2.1 From 1e92920c6d84d99f6c6009f1e024260eec434914 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 20 Sep 2002 02:53:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@701 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index d1500a7ed..7c70c4d71 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -106,9 +106,34 @@ General - @@@@ All system messages should have a "line" attribute, to improve diagnostic output. So all elements constructed by the parser should - have internal "line" ("lineno"/"line_number") attributes. Is there - any way we can get this to happen automagically, without having to - add the attribute manually to each object? + have internal "line" ("lineno"/"line_number") attributes. They'd + also need internal "source" attributes as well (populating the + external "source" attribute would clutter up the output). + + Is there any way we can get this to happen automagically, without + having to add the attribute manually to each object? System + messages get their "source" attribute from the Reporter object (new + one for each source). + + - Add an observer subject interface to StateMachine, called whenever + next_line, previous_line, or goto_line is called? + + - Who to notify? Publisher? Document object? Singleton? + + - Document object: add ``note_source``, ``note_line_number`` + methods. ``note_line_number`` is called by + ``StateMachine.notify_observer``. Whatever reads the source + calls ``note_source`` (``utils.new_document()``, "include" + directive (see misc.include_). + + - Add a ``line=None`` parameter to ``nodes.Node``; if unspecified, + it will get the line number from the observer. + + - Perhaps ``Element.append()`` etc. can also set the ``.document`` + attribute of each node added. The document object could hold the + current line number and source description, which would also be + copied over to the node. Consolodate all assignments (parent, + document, source, line) into a single method. Change stderr Reporter output to the GNU urilities format:: @@ -122,7 +147,7 @@ General where directory separators are colons. "filename.txt:1:" looks like a file or directory path. Does MacOS X still use colons, or has it switched to slashes? In any case, the ubiquity of the GNU utilities - probably overweighs any such problem. + probably outweighs any such problem. - Standalone Reader: Implement an option to turn off the DocTitle transform? @@ -483,6 +508,13 @@ __ rst/alternatives.html#or-not-to-do (And arguably invalid, since in Japanese the word "haiku" contains three syllables.) +- Modify acceptable "simple reference name" syntax to allow for + ``object.__method__`` without requiring inline literals? Simple + reference names currently allow any of "-", "_", and "." internally; + if we limit this to one at a time, problem solved. I.e., none of + these would be recognized as simple names: "one..two", "one-.two", + "one._two", "one__two". + Directives `````````` @@ -560,7 +592,7 @@ Directives in ``match_titles=1``. The reporting mechanism has been revamped to include the file which is the source of system messages; a new ``utils.Reporter`` object will need to be created for each input - source. + source. (Need to notify YAGNI for now: Use C-preprocessor semantics for locating include files? E.g., ``.. include:: file.txt`` will read another file -- cgit v1.2.1 From 794964358a1bb001f592d7e7c8b77559fe9ad24f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:21:48 +0000 Subject: Changed public identifier to docutils.sf.net. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@715 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 4 ++-- docs/ref/docutils.dtd | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index bb61fb2ff..02d754358 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -16,9 +16,9 @@ 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/spec/pysource.dtd. -The proposed formal public identifier for this DTD is:: +The formal public identifier for this DTD is:: - +//IDN python.org//DTD Docutils Python Source//EN//XML + +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML --> <!-- diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 19094bbf2..97efa9477 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -14,9 +14,9 @@ Docutils project can be found at http://docutils.sourceforge.net/. The latest version of this DTD is available from http://docutils.sourceforge.net/spec/docutils.dtd. -The proposed formal public identifier for this DTD is:: +The formal public identifier for this DTD is:: - +//IDN python.org//DTD Docutils Generic//EN//XML + +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML --> <!-- -- cgit v1.2.1 From 40e2dd54976161f6884757dfc13325bee259f686 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:22:07 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@716 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index c490e5044..b7901b370 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -108,9 +108,7 @@ Category members: document_, section_, topic_ Structural Subelements ---------------------- -Structural subelements are child elements of structural elements, but -contain no further structure of their own (except for text and inline -elements). +Structural subelements are child elements of structural elements. Category members: title_, subtitle_, docinfo_, decoration_, transition_ -- cgit v1.2.1 From e1d2f1face2a58f022aa0bb0e9b3b6fb11adf900 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Sep 2002 02:24:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@717 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 ++++++++++------- docs/ref/rst/directives.txt | 2 +- docs/ref/rst/introduction.txt | 2 +- 3 files changed, 12 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7c70c4d71..3c3d81ff6 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -107,8 +107,8 @@ General - @@@@ All system messages should have a "line" attribute, to improve diagnostic output. So all elements constructed by the parser should have internal "line" ("lineno"/"line_number") attributes. They'd - also need internal "source" attributes as well (populating the - external "source" attribute would clutter up the output). + need internal "source" attributes as well (populating the external + "source" attribute would clutter up the output). Is there any way we can get this to happen automagically, without having to add the attribute manually to each object? System @@ -122,20 +122,21 @@ General - Document object: add ``note_source``, ``note_line_number`` methods. ``note_line_number`` is called by - ``StateMachine.notify_observer``. Whatever reads the source + ``StateMachine.notify_observers``. Whatever reads the source calls ``note_source`` (``utils.new_document()``, "include" directive (see misc.include_). - Add a ``line=None`` parameter to ``nodes.Node``; if unspecified, - it will get the line number from the observer. + it will get the line number from the observer. (``source=None`` + too?) - Perhaps ``Element.append()`` etc. can also set the ``.document`` attribute of each node added. The document object could hold the current line number and source description, which would also be - copied over to the node. Consolodate all assignments (parent, + copied over to the node. Consolidate all assignments (parent, document, source, line) into a single method. - Change stderr Reporter output to the GNU urilities format:: +- @@@ Change stderr Reporter output to the GNU utilities format:: file:line: message @@ -592,7 +593,9 @@ Directives in ``match_titles=1``. The reporting mechanism has been revamped to include the file which is the source of system messages; a new ``utils.Reporter`` object will need to be created for each input - source. (Need to notify + source. (Need to notify ``document.note_source(source)`` upon + entering a new source file, and again when returning to the old + source file.) YAGNI for now: Use C-preprocessor semantics for locating include files? E.g., ``.. include:: file.txt`` will read another file diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cb22c621b..242c01564 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -254,7 +254,7 @@ example, here's a classic:: Parsed Literal Block ==================== -:Directive Type: "literal-block" +:Directive Type: "parsed-literal" :DTD Element: literal_block :Directive Arguments: None. :Directive Options: None. diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 0ec112a47..5ff6d2878 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -202,7 +202,7 @@ motivations (the "itches" I aim to "scratch") are as follows: a markup language specification and a reference parser implementation, but it does not aspire to be the entire system. I don't want reStructuredText or a hypothetical Python documentation - processor to die stillborn because of overambition. + processor to die stillborn because of over-ambition. - Most of all, I want to help ease the documentation chore, the bane of many a programmer. -- cgit v1.2.1 From 456d58fa344070e7b3d782ecd44ea5f4c793eb2c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Sep 2002 03:02:00 +0000 Subject: fixed typos git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@718 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 97efa9477..41eb5d791 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -430,7 +430,7 @@ either the string separating it from the `option` (typically either <!ELEMENT pending EMPTY> <!ATTLIST pending %basic.atts;> -<!ELEMENT figure (image, ((caption, legend?) | legend) > +<!ELEMENT figure (image, ((caption, legend?) | legend)) > <!ATTLIST figure %basic.atts;> <!-- Also an inline element. --> @@ -439,9 +439,9 @@ either the string separating it from the `option` (typically either %basic.atts; uri CDATA #REQUIRED alt CDATA #IMPLIED - height &number; #IMPLIED - width &number; #IMPLIED - scale &number; #IMPLIED> + height %number; #IMPLIED + width %number; #IMPLIED + scale %number; #IMPLIED> <!ELEMENT caption %text.model;> <!ATTLIST caption %basic.atts;> @@ -459,8 +459,8 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry. <!ATTLIST system_message %basic.atts; %backrefs.att; - level &number; #IMPLIED - line &number; #IMPLIED + level %number; #IMPLIED + line %number; #IMPLIED type NMTOKEN #IMPLIED> <!-- Used to pass raw data through the system. Also inline. --> -- cgit v1.2.1 From 2570dd555418b4a1402dc828a5a6f5a158ea29fe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Sep 2002 03:03:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@720 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3c3d81ff6..a9436ce4c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -563,6 +563,10 @@ Directives "local" concept comes in. This part of the implementation can be left for later. + - _`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"? + - 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 -- cgit v1.2.1 From 94712189fa21bb13cf4d85953f65216079339dc6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 26 Sep 2002 02:02:29 +0000 Subject: (cosmetic) changed "-" bullets to "*". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@722 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 176 +++++++++++++++++++++++++++--------------------------- 1 file changed, 88 insertions(+), 88 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a9436ce4c..85f3323c8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -25,7 +25,7 @@ you'd like to tackle, please do! Bugs ---- -- The "contents" directive now automatically names the "topic" +* The "contents" directive now automatically names the "topic" produced (using its title), so that it can be referred to by name. However, this naming happens late in the game, after most references have been resolved. So the following indirect target produces a @@ -40,7 +40,7 @@ Bugs Idea: two-pass hyperlink resolution, ignoring errors on the first pass? -- The parser doesn't know anything about double-width characters such +* 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. @@ -49,7 +49,7 @@ Bugs General ------- -- Refactor +* Refactor - Rename methods & variables according to the `coding conventions`_ below. @@ -58,28 +58,28 @@ General checked for correctness and refactored. I'm afraid it's a bit of a spaghetti mess now. -- Add validation? See http://pytrex.sourceforge.net, RELAX NG. +* Add validation? See http://pytrex.sourceforge.net, RELAX NG. -- Ask Python-dev for opinions (GvR for a pronouncement) on special +* 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 reader.get_reader_class (& parser & writer too), should we be +* In reader.get_reader_class (& parser & writer 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 +* 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"?) -- Need a Unicode to HTML entities codec for HTML writer? +* Need a Unicode to HTML entities codec for HTML writer? -- Perhaps the ``Component.supports`` method should deal with +* Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- @@@ Transforms need a priority system. The "first reader" ... +* @@@ Transforms need a priority system. The "first reader" ... "last writer" system is no longer adequate for pending transforms. For example, the ``references.TargetNotes`` transform needs to run after ``references.Hyperlinks.resolve_indirect()`` but before @@ -97,14 +97,14 @@ General No, that would require too many imports to construct. Document transform priorities. -- @@@ Break up ``references.Hyperlinks`` into multiple smaller +* @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. -- Make it easier to say, "Here's a reStructuredText string; give me +* Make it easier to say, "Here's a reStructuredText string; give me HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to ``core.publish_file()``? -- @@@@ All system messages should have a "line" attribute, to improve +* @@@@ All system messages should have a "line" attribute, to improve diagnostic output. So all elements constructed by the parser should have internal "line" ("lineno"/"line_number") attributes. They'd need internal "source" attributes as well (populating the external @@ -136,7 +136,7 @@ General copied over to the node. Consolidate all assignments (parent, document, source, line) into a single method. -- @@@ Change stderr Reporter output to the GNU utilities format:: +* @@@ Change stderr Reporter output to the GNU utilities format:: file:line: message @@ -150,10 +150,10 @@ General switched to slashes? In any case, the ubiquity of the GNU utilities probably outweighs any such problem. -- Standalone Reader: Implement an option to turn off the DocTitle +* Standalone Reader: Implement an option to turn off the DocTitle transform? -- Add /usr/etc/docutils.conf to config file list? System-wide, +* Add /usr/etc/docutils.conf to config file list? System-wide, whereas /etc/docutils.conf is machine-specific. /usr/local/etc/docutils.conf too? See the `Filesystem Hierarchy Standard`_. @@ -164,34 +164,34 @@ General Documentation ------------- -- User docs. +* User docs. Implementation Docs ``````````````````` -- Internal module documentation (docstrings). +* Internal module documentation (docstrings). -- spec/doctree.txt: DTD element structural relationships, semantics, +* spec/doctree.txt: DTD element structural relationships, semantics, and attributes. -- How a Writer works & how to write one +* How a Writer works & how to write one -- Howto: Transforms +* Howto: Transforms -- Howto: Directives +* Howto: Directives -- Document the ``pending`` elements, how they're generated and when +* Document the ``pending`` elements, how they're generated and when they're triggered ("first reader", "last writer", etc.). -- Document the transforms (perhaps in docstrings?): how they're used, +* Document the transforms (perhaps in docstrings?): how they're used, what they do, dependencies & order considerations. Specification ````````````` -- Complete PEP 258 Docutils Design Specification. +* Complete PEP 258 Docutils Design Specification. - Fill in the blanks in API details. @@ -201,7 +201,7 @@ Specification there on how it all hangs together - the DTD is not enough (indeed, is it still meant to be correct? [Yes, it is.]). -- Rework PEP 257, separating style from spec from tools, wrt Docutils? +* Rework PEP 257, separating style from spec from tools, wrt Docutils? See Doc-SIG from 2001-06-19/20. @@ -210,15 +210,15 @@ PySource Reader General: -- Analyze Tony Ibbs' PySource code. +* Analyze Tony Ibbs' PySource code. -- Analyze Doug Hellmann's HappyDoc project. +* Analyze Doug Hellmann's HappyDoc project. -- Take the best ideas and integrate them into Docutils 0.3. +* Take the best ideas and integrate them into Docutils 0.3. Miscellaneous ideas: -- If we can detect that a comment block begins with ``##``, a la +* 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:: @@ -239,7 +239,7 @@ Miscellaneous ideas: # etc. -- HappyDoc's idea of using comment blocks when there's no docstring +* 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:: @@ -260,9 +260,9 @@ Miscellaneous ideas: .. _additional docstrings: pep-0258.html#additional-docstrings -- Multi-file output should be divisible at arbitrary level. +* Multi-file output should be divisible at arbitrary level. -- Support all forms of ``import`` statements: +* Support all forms of ``import`` statements: - ``import module``: listed as "module" - ``import module as alias``: "alias (module)" @@ -279,22 +279,22 @@ Also see the `... Or Not To Do?`__ list. __ rst/alternatives.html#or-not-to-do -- Clean up the code; refactor as required. +* Clean up the code; refactor as required. -- Add motivation sections for constructs in spec. +* Add motivation sections for constructs in spec. -- Allow very long titles (on two or more lines)? +* Allow very long titles (on two or more lines)? -- And for the sake of completeness, should definition list terms be +* 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? +* 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. -- Add _`character processing`? For example: +* Add _`character processing`? For example: - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). (Look for pre-existing conventions.) @@ -313,31 +313,31 @@ __ rst/alternatives.html#or-not-to-do Which component is responsible for this, the parser, the reader, or the writer? -- Implement the header row separator modification to table.el. (Wrote +* 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 +* 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. -- Alan Jaffray suggested (and I agree) that it would be sensible to: +* Alan Jaffray suggested (and I agree) that it would be sensible to: - have a directive to specify a default role for interpreted text - allow the reST processor to take an argument for the default role - issue a warning when processing documents with no default role which contain interpreted text with no explicitly specified role -- Perhaps the default implicit role for interpreted text could be +* Perhaps the default implicit role for interpreted text could be "title", as in, "title of a book". It'd be a text-only reference, no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. -- @@ Fix the parser's indentation handling to conform with the +* @@ 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 +* @@ 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 @@ -367,7 +367,7 @@ __ rst/alternatives.html#or-not-to-do 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 +* 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:: @@ -392,13 +392,13 @@ __ rst/alternatives.html#or-not-to-do See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's "Structuring: a summary; and an attempt at EBNF", item 4. -- Make the parser modular. Allow syntax constructs to be added or +* 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 +* Continue to report (info, level 1) enumerated lists whose start value is not ordinal-1? -- Generalize the "doctest block" construct (which is overly +* 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: @@ -424,7 +424,7 @@ __ rst/alternatives.html#or-not-to-do Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback"). -- Generalize the "literal block" construct to allow blocks with a +* Generalize the "literal block" construct to allow blocks with a per-line quoting to avoid indentation? For example, in this email reply quoting the original, the block quoted with "``>``" (and prefaced by "``::``") would be treated as a literal block:: @@ -441,7 +441,7 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. -- @@@ Decide whether or not to implement Simon Budig's "inline +* @@@ Decide whether or not to implement Simon Budig's "inline external targets" syntax idea, and if so, how? - As a regular directive affecting its indented text block:: @@ -471,13 +471,13 @@ __ rst/alternatives.html#or-not-to-do - Or as a full-blown addition to the spec & parser. -- Add support for pragma (syntax-altering) directives. +* Add support for pragma (syntax-altering) directives. -- Remove leading numbers from section titles for implicit link names? +* 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 the "line-block" directive? How about a +* Syntax for the "line-block" directive? How about a literal-block-like prefix, perhaps "``;;``"? (It is, after all, a *semi-literal* literal block, no?) Example:: @@ -509,7 +509,7 @@ __ rst/alternatives.html#or-not-to-do (And arguably invalid, since in Japanese the word "haiku" contains three syllables.) -- Modify acceptable "simple reference name" syntax to allow for +* Modify acceptable "simple reference name" syntax to allow for ``object.__method__`` without requiring inline literals? Simple reference names currently allow any of "-", "_", and "." internally; if we limit this to one at a time, problem solved. I.e., none of @@ -520,11 +520,11 @@ __ rst/alternatives.html#or-not-to-do Directives `````````` -- Allow directives to be added at run-time? +* Allow directives to be added at run-time? -- Use the language module for directive attribute names? +* Use the language module for directive attribute names? -- Implement attributes on existing directives: +* Implement attributes on existing directives: - _`images.image`: "align", "border"? @@ -567,7 +567,7 @@ Directives suppress contents display for sections in a branch from that point down. Or a new directive, like "prune-contents"? -- Implement directives. Each of the list items below begins with an +* 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. @@ -797,9 +797,9 @@ 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 +* duplicate reference and/or substitution names that need to be made unique; and/or -- duplicate footnote numbers that need to be renumbered. +* 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 @@ -846,19 +846,19 @@ Index HTML Writer ----------- -- @@ Construct a _`templating system`, as in ht2html/yaptu, using +* @@ Construct a _`templating system`, as in ht2html/yaptu, using directives and substitutions for dynamic stuff. -- Add more support for <link> elements, especially for navigation +* Add more support for <link> elements, especially for navigation bars. -- ``<meta>`` tags should be XML empty tags: ``<meta />``. +* ``<meta>`` tags should be XML empty tags: ``<meta />``. Front-End Tools --------------- -- What about if we don't know which Reader and/or Writer we are +* 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?) @@ -895,12 +895,12 @@ Front-End Tools conflicts) to splitting common and component-specific options apart. -- Parameterize help text & defaults somehow? Perhaps a callback? Or +* Parameterize help text & defaults somehow? Perhaps a callback? Or initialize ``cmdline_options`` in ``__init__`` or ``init_options``? -- Disable common options that don't apply? +* Disable common options that don't apply? -- Implement the "sectnum" directive as a command-line option also? +* Implement the "sectnum" directive as a command-line option also? Project Policies @@ -955,19 +955,19 @@ 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. Indent continuation lines +* 4 spaces per indentation level. No tabs. Indent continuation lines according to the Emacs python-mode standard. -- No one-liner compound statements (i.e., no ``if x: return``: use two +* 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. +* Lines should be no more than 78 characters long. -- Use "StudlyCaps" for class names (except for element classes in +* Use "StudlyCaps" for class names (except for element classes in docutils.nodes). -- Use "lowercase" or "lowercase_with_underscores" for function, +* 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 @@ -975,7 +975,7 @@ least important): "note_explicit_target", "explicit_target"). If in doubt, use underscores. -- Use 'single quotes' for string literals, and """triple double +* Use 'single quotes' for string literals, and """triple double quotes""" for docstrings. .. _Style Guide for Python Code: @@ -996,10 +996,10 @@ 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 +* 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 +* 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. @@ -1025,24 +1025,24 @@ 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 +* 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 -- When adding new functionality (or fixing bugs), be sure to add test +* 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 +* 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 +* 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 +* 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. @@ -1068,19 +1068,19 @@ usable_, 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? +* 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 +* _`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 +* _`Usable` means that the code does what it claims to do. An "XYZ Writer" should produce reasonable XYZ. -- _`Reasonably complete` means that the code must handle all input. +* _`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 @@ -1103,12 +1103,12 @@ Mailing Lists Developers should subscribe to the mailing lists: -- The `Python Documentation Special Interest Group (Doc-SIG) mailing +* The `Python Documentation Special Interest Group (Doc-SIG) mailing list`__ for high-level discussions on syntax, strategy, and design (email to Doc-SIG@python.org). -- Docutils-develop__, for implementation discussions +* Docutils-develop__, for implementation discussions (email to docutils-develop@lists.sourceforge.net). -- Docutils-checkins__, to monitor CVS checkin messages (automatically +* Docutils-checkins__, to monitor CVS checkin messages (automatically generated; normally read-only). __ http://mail.python.org/mailman/listinfo/doc-sig -- cgit v1.2.1 From 2aec785bc1ae304360badbf509f5b3a8ef786fb5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 03:22:29 +0000 Subject: Added "replace" directive. Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@748 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 77 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 58 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 242c01564..6f6b1ca88 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -22,8 +22,9 @@ space), followed by the directive type and two colons (collectively, the "directive marker"). The directive block begins immediately after the directive marker, and includes all subsequent indented lines. The directive block is divided into arguments, options (a field list), and -content. See the Directives_ section in the `reStructuredText Markup -Specification`_ for syntax details. +content (in that order), any of which may appear. See the Directives_ +section in the `reStructuredText Markup Specification`_ for syntax +details. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html @@ -199,9 +200,9 @@ Topic :Directive Type: "topic" :DTD Element: topic -:Directive Arguments: None. +:Directive Arguments: 1, required (topic title). :Directive Options: None. -:Directive Content: Interpreted as the topic title and body. +:Directive Content: Interpreted as the topic body. A topic is like a block quote with a title, or a self-contained section with no subsections. Use the "topic" directive to indicate a @@ -209,9 +210,9 @@ self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body elements (including topics) may not contain nested topics. -The first line of the directive content block is interpreted as the -topic title; the second line must be blank. All subsequent lines make -up the topic body, interpreted as body elements. For example:: +The directive's sole argument is interpreted as the topic title; the +next line must be blank. All subsequent lines make up the topic body, +interpreted as body elements. For example:: topic:: Topic Title @@ -331,7 +332,7 @@ The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of contents. The default is unlimited depth. -``local`` : empty +``local`` : flag (empty) Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled. @@ -490,10 +491,8 @@ Non-standard element: imagemap. Miscellaneous --------------- -Including an External Fragment -============================== - -**NOT IMPLEMENTED YET** +Including an External Document Fragment +======================================= :Directive Type: "include" :DTD Elements: depend on data being included @@ -505,11 +504,23 @@ The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the directive. For example:: + This first example will be parsed at the document level, and can + thus contain any construct, including section headers. + .. include:: inclusion.txt + This second will be parsed in a block quote context. + Therefore it may only contain body elements. It may not + contain section headers. + + .. include:: inclusion.txt + +If an included document fragment contains section structure, the title +adornments must match those of the master document. + The following options are recognized: -``literal`` : empty +``literal`` : flag (empty) The entire included text is inserted into the document as a single literal block (useful for program listings). @@ -517,12 +528,10 @@ The following options are recognized: Raw Data Pass-Through ===================== -**NOT IMPLEMENTED YET** - :Directive Type: "raw" :DTD Element: pending :Directive Arguments: One, required (output format type). -:Directive Options: Possible +:Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a "file" or "url" option given. @@ -547,8 +556,9 @@ output stream:: \documentclass[twocolumn]{article} -Raw data can also be read from an external file, specified in an -option. In this case, the content block must be empty. For example:: +Raw data can also be read from an external file, specified in a +directive option. In this case, the content block must be empty. For +example:: .. raw:: html :file: inclusion.html @@ -556,11 +566,40 @@ option. In this case, the content block must be empty. For example:: The following options are recognized: ``file`` : string - The filesystem path of a raw data file to be included. + The local filesystem path of a raw data file to be included. ``url`` : string An Internet URL reference to a raw data file to be included. +Replacement Text +================ + +:Directive Type: "replace" +:DTD Element: pending +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: A single paragraph; may contain inline markup. + +The "replace" directive is used to indicate replacement text for a +substitution reference. It may be used within substitution +definitions only. For example, this directive can be used to expand +abbreviations:: + + .. |reST| replace:: reStructuredText + + Yes, |reST| is a long word, so I can't blame anyone for wanting to + abbreviate it. + +As reStructuredText doesn't support nested inline markup, the only way +to create a reference with styled text is to use substitutions with +the "replace" directive:: + + I recommend you try |Python|_. + + .. |Python| replace:: Python, *the* best language around + .. _Python: http://www.python.org/ + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From 631b6fed566f55d7adfa2a93d103786306c79b06 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 03:23:20 +0000 Subject: Added to project. Original by Dethe Elza, edited & extended by David Goodger. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@749 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 343 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 docs/howto/rst-directives.txt (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt new file mode 100644 index 000000000..a1f40e973 --- /dev/null +++ b/docs/howto/rst-directives.txt @@ -0,0 +1,343 @@ +====================================== + Creating reStructuredText Directives +====================================== + +:Authors: Dethe Elza, David Goodger +:Contact: delza@enfoldingsystems.com +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + +Directives are the primary extension mechanism of reStructuredText. +This document aims to make the creation of new directives as easy and +understandable as possible. There are only a couple of +reStructuredText-specific features the developer needs to know to +create a basic directive. + +The syntax of directives is detailed in the `reStructuredText Markup +Specification`_, and standard directives are described in +`reStructuredText Directives`_. + +.. _reStructuredText Markup Specification: + ../rst/reStructuredText.html#directives +.. _reStructuredText Directives: ../rst/directives.html + + +.. contents:: Table of Contents + + +Define the Directive Function +============================= + +The directive function does any processing that the directive +requires. This may require the use of other parts of the +reStructuredText parser. This is where the directive actually *does* +something. + +The directive implementation itself is a callback function whose +signature is as follows:: + + def directive_fn(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + code... + + # Set function attributes: + directive_fn.arguments = ... + directive_fn.options = ... + direcitve_fn.content = ... + +Function attributes are described below (see `Specify Directive +Arguments, Options, and Content`_). The directive function parameters +are as follows: + +- ``name`` is the directive type or name. + +- ``arguments`` is a list of positional arguments, as specified in the + ``arguments`` function attribute. + +- ``options`` is a dictionary mapping option names to values. The + options handled by a directive function are specified in the + ``options`` function attribute. + +- ``content`` is a list of strings, the directive content. Use the + ``content`` function attribute to allow directive content. + +- ``lineno`` is the line number of the first line of the directive. + +- ``content_offset`` is the line offset of the first line of the + content from the beginning of the current input. Used when + initiating a nested parse. + +- ``block_text`` is a string containing the entire directive. Include + it as the content of a literal block in a system message if there is + a problem. + +- ``state`` is the state which called the directive function. + +- ``state_machine`` is the state machine which controls the state + which called the directive function. + +Directive functions return a list of nodes which will be inserted into +the document tree at the point where the directive was encountered. +This can be an empty list if there is nothing to insert. Directives +have no corresponding element; choose the most appropriate elements +from the existing Docutils elements. See `The Docutils Document +Tree`_ and the ``docutils.nodes`` module. + +.. _The Docutils Document Tree: ../doctree.html + + +Specify Directive Arguments, Options, and Content +================================================= + +Function attributes are interpreted by the directive parser (the +``docutils.parsers.rst.states.Body.parse_directive()`` method). If +unspecified, directive function attributes are assumed to have the +value ``None``. Three directive function attributes are recognized: + +- ``arguments``: A 3-tuple specifying the expected positional + arguments, or ``None`` if the directive has no arguments. The 3 + items in the tuple are: + + 1. The number of required arguments. + 2. The number of optional arguments. + 3. A boolean, indicating if the final argument may contain whitespace. + + Arguments are normally single whitespace-separated words. The final + argument may contain whitespace when indicated by the value 1 (True) + for the third item in the argument spec tuple. In this case, the + final argument in the ``arguments`` parameter to the directive + function will contain spaces and/or newlines, preserved from the + input text. + + If the form of the arguments is more complex, specify only one + argument (either required or optional) and indicate that final + whitespace is OK (1/True); the client code must do any + context-sensitive parsing. + +- ``options``: The option specification. ``None`` or an empty dict + implies no options to parse. + + An option specification must be defined detailing the options + available to the directive. An option spec is a mapping of option + name to conversion function; conversion functions are applied to + each option value to check validity and convert them to the expected + type. Python's built-in conversion functions are often usable for + this, such as ``int``, ``float``, and ``bool`` (included in Python + from version 2.2.1). Other useful conversion functions are included + in the ``docutils.parsers.rst.directives`` package (in the + ``__init__.py`` module): + + - ``flag``: For options with no option arguments. Checks for an + argument (raises ``ValueError`` if found), returns ``None`` for + valid flag options. + + - ``unchanged``: Returns the argument, unchanged. Raises + ``ValueError`` if no argument is found. + + - ``path``: Returns the path argument unwrapped (with newlines + removed). Raises ``ValueError`` if no argument is found or if the + path contains internal whitespace. + + - ``nonnegative_int``: Checks for a nonnegative integer argument, + and raises ``ValueError`` if not. + + A further utility function, ``choice``, is supplied to enable + options whose argument must be a member of a finite set of possible + values. A custom conversion function must be written to use it. + For example:: + + from docutils.parsers.rst import directives + + def yesno(argument): + return directives.choice(argument, ('yes', 'no')) + + For example, here is an option spec for a directive which allows two + options, "name" and "value", each with an option argument:: + + directive_fn.options = {'name': unchanged, 'value': int} + +- ``content``: A boolean; true if content is allowed. Directive + functions must handle the case where content is required but not + present in the input text (an empty content list will be supplied). + +The final step of the ``parse_directive()`` method is to call the +directive function itself. + + +Register the Directive +====================== + +Register the new directive in ``directives/__init__.py``, in the +``_directive_registry`` dictionary. This allows the reStructuredText +parser to find and use the directive. + + +Examples +======== + +For the most direct and accurate information, "Use the Source, Luke!". +All standard directives are documented in `reStructuredText +Directives`_, and the source code implementing them is located in the +``docutils/parsers/rst/directives`` package. The ``__init__.py`` +module contains a mapping of directive name to module & function name. +Several representative directives are described below. + + +Admonitions +----------- + +Admonition directives, such as "note" and "caution", are quite simple. +They have no directive arguments or options. Admonition directive +content is interpreted as ordinary reStructuredText. The directive +function simply hands off control to a generic directive function:: + + def note(*args): + return admonition(nodes.note, *args) + + attention.content = 1 + +Note that the only thing distinguishing the various admonition +directives is the element (node class) generated. In the code above, +the node class is passed as the first argument to the generic +directive function, where the actual processing takes place:: + + def admonition(node_class, name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + text = '\n'.join(content) + admonition_node = node_class(text) + if text: + state.nested_parse(content, content_offset, admonition_node) + return [admonition_node] + else: + warning = state_machine.reporter.warning( + 'The "%s" admonition is empty; content required.' + % (name), '', + nodes.literal_block(block_text, block_text), line=lineno) + return [warning] + +Three things are noteworthy in the function above: + +1. The ``admonition_node = node_class(text)`` line creates the wrapper + element, using the class passed in from the initial (stub) + directive function. + +2. The call to ``state.nested_parse()`` is what does the actual + processing. It parses the directive content and adds any generated + elements as child elements of ``admonition_node``. + +3. If there was no directive content, a warning is generated and + returned. The call to ``state_machine.reporter.warning()`` + includes a literal block containing the entire directive text + (``block_text``) and the line (``lineno``) of the top of the + directive. + + +"image" +------- + +The "image" directive is used to insert a picture into a document. +This directive has one argument, the path to the image file, and +supports several options. There is no directive content. Here's the +image directive function:: + + def image(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + reference = ''.join(arguments[0].split('\n')) + if reference.find(' ') != -1: + error = state_machine.reporter.error( + 'Image URI contains whitespace.', '', + nodes.literal_block(block_text, block_text), + line=lineno) + return [error] + options['uri'] = reference + image_node = nodes.image(block_text, **options) + return [image_node] + + image.arguments = (1, 0, 1) + image.options = {'alt': directives.unchanged, + 'height': directives.nonnegative_int, + 'width': directives.nonnegative_int, + 'scale': directives.nonnegative_int, + 'align': align} + +Several things are noteworthy in the code above: + +1. The "image" directive requires a single argument, which is allowed + to contain whitespace (see the argument spec above, + ``image.arguments = (1, 0, 1)``). This is to allow for long URLs + which may span multiple lines. The first line of the ``image`` + function joins the URL, discarding any embedded newlines. Then the + result is checked for embedded spaces, which are *not* allowed. + +2. The reference is added to the ``options`` dictionary under the + "uri" key; this becomes an attribute of the ``nodes.image`` element + object. Any other attributes have already been set explicitly in + the source text. + +3. The "align" option depends on the following definitions (which + actually occur earlier in the source code):: + + align_values = ('top', 'middle', 'bottom', 'left', 'center', + 'right') + + def align(argument): + return directives.choice(argument, align_values) + + +"contents" +---------- + +The "contents" directive is used to insert an auto-generated table of +contents (TOC) into a document. It takes one optional argument, a +title for the TOC. If no title is specified, a default title is used +instead. The directive also handles several options. Here's the +code:: + + def contents(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + """Table of contents.""" + if arguments: + title_text = arguments[0] + text_nodes, messages = state.inline_text(title_text, lineno) + title = nodes.title(title_text, '', *text_nodes) + else: + messages = [] + title = None + pending = nodes.pending(parts.Contents, 'first writer', + {'title': title}, block_text) + pending.details.update(options) + state_machine.document.note_pending(pending) + return [pending] + messages + + contents.arguments = (0, 1, 1) + contents.options = {'depth': directives.nonnegative_int, + 'local': directives.flag, + 'backlinks': backlinks} + +Aspects of note include: + +1. The ``contents.arguments = (0, 1, 1)`` function attribute specifies + a single, *optional* argument. If no argument is present, the + ``arguments`` parameter to the directive function will be an empty + list. + +2. If an argument *is* present, its text is passed to + ``state.inline_text()`` for parsing. Titles may contain inline + markup, such as emphasis or inline literals. + +3. The table of contents is not generated right away. Typically, a + TOC is placed near the beginning of a document, and is a summary or + outline of the section structure of the document. The entire + document must already be processed before a summary can be made. + This directive leaves a ``nodes.pending`` placeholder element in + the document tree, marking the position of the TOC and including a + ``details`` internal attribute containing all the directive + options, effectively communicating the options forward. The actual + table of contents processing is performed by a transform, + ``docutils.transforms.parts.Contents``, after the rest of the + document has been parsed. [#]_ + +.. [#] Please note that the priority system for transforms, indicated + above by ``'first writer'`` in the call to the ``nodes.pending`` + class, is due for an overhaul. -- cgit v1.2.1 From a3bc9fff9ecee87efe0f053530371b7a408d86a0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 03:25:25 +0000 Subject: Updated with text from a Doc-SIG response to Dallas Mahrt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@750 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/semantics.txt | 85 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index f6ec09ebd..e42c9ea01 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -7,13 +7,78 @@ :Date: $Date$ These are notes for a possible future PEP providing the final piece of -the Python docstring puzzle. +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 ========= -A Python version of the JavaDoc semantics (not syntax). A set of -conventions which are understood by the Docutils. +(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:: @@ -31,11 +96,17 @@ conventions which are understood by the Docutils. it would be quite hard to add a new param to this method without realising you should document it -- Use field lists or definition lists for "tagged blocks". +- Frederic Giacometti's `iPhrase Python documentation conventions`_ is + an attachment to his Doc-SIG post of 2001-05-30. + -- Frederic Giacometti's "iPhrase Python documentation conventions" is - an attachment to his Doc-SIG post of 2001-05-30 - (http://mail.python.org/pipermail/doc-sig/2001-May/001840.html). +.. _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 .. -- cgit v1.2.1 From a9be40d6b5f5902c3b68e4416553fef4583cd7a6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 03:31:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@751 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 57 +++++++++++++++++++------------------------------------ 1 file changed, 19 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 85f3323c8..71af1d1a8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -173,16 +173,17 @@ Implementation Docs * Internal module documentation (docstrings). * spec/doctree.txt: DTD element structural relationships, semantics, - and attributes. + and attributes. In progress; element descriptions to be completed. -* How a Writer works & how to write one +* How-to docs: In spec/howto/? -* Howto: Transforms + - How a Writer works & how to write one -* Howto: Directives + - Transforms * Document the ``pending`` elements, how they're generated and when - they're triggered ("first reader", "last writer", etc.). + they're triggered ("first reader", "last writer", etc.; priority + system due to be reworked, as noted above). * Document the transforms (perhaps in docstrings?): how they're used, what they do, dependencies & order considerations. @@ -294,6 +295,19 @@ __ rst/alternatives.html#or-not-to-do contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. +* 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? + + This may not be just a parser issue though; it may need framework + support. + * Add _`character processing`? For example: - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). @@ -579,37 +593,6 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`misc.raw`: See `Raw Data Pass-Through`__ in rst/directives.txt. - - __ rst/directives.html#raw-data-pass-through - - - _`misc.include`: ``#include`` one file in another. See `Including - an External Fragment`__ in rst/directives.txt. But how to parse - wrt sections, reference names, conflicts? For now, we'll parse it - in the current document's context (C-preprocessor semantics). - Perhaps later, when there's a need, we'll figure out how to - provide separate parsing (parse separately and then merge). - - Implementation ideas: Model the directive parsing on the "images" - directive. A separate, nested parse is probably needed, since - it's not a good idea to alter the already-read data. Use - ``state.nested_parse()`` (see directives/admonitions.py), and pass - in ``match_titles=1``. The reporting mechanism has been revamped - to include the file which is the source of system messages; a new - ``utils.Reporter`` object will need to be created for each input - source. (Need to notify ``document.note_source(source)`` upon - entering a new source file, and again when returning to the old - source file.) - - YAGNI for now: 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?) - - __ rst/directives.html#including-an-external-fragment - - _`misc.exec`: Execute Python code & insert the results. Perhaps dangerous? @@ -852,8 +835,6 @@ HTML Writer * Add more support for <link> elements, especially for navigation bars. -* ``<meta>`` tags should be XML empty tags: ``<meta />``. - Front-End Tools --------------- -- cgit v1.2.1 From e11dfe778b470ccb244767b6f9f2c959db6bec82 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Oct 2002 04:49:26 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@753 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 71af1d1a8..e0a65e596 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -124,7 +124,7 @@ General methods. ``note_line_number`` is called by ``StateMachine.notify_observers``. Whatever reads the source calls ``note_source`` (``utils.new_document()``, "include" - directive (see misc.include_). + directive. - Add a ``line=None`` parameter to ``nodes.Node``; if unspecified, it will get the line number from the observer. (``source=None`` @@ -739,7 +739,8 @@ Directives 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 misc.include_, implement canned macros? E.g.:: + - Combined with the "include" directive, implement canned macros? + E.g.:: .. include:: <macros> -- cgit v1.2.1 From d3256371e06859fd101eacc5e35f21364b74b651 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 01:38:26 +0000 Subject: Added field_list, field, field_name, field_body elements. Changed "Analogies" to "Analogues". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@754 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 270 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 236 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index b7901b370..a67b00db4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -229,7 +229,7 @@ following subsections: - Children: A list of elements which may occur within the element. - - Analogies: Describes analogous elements in well-known document + - Analogues: Describes analogous elements in well-known document models such as HTML_ or DocBook_. Lists similarities and differences. @@ -299,7 +299,7 @@ Details :Children: ``address`` elements contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``address`` is analogous to the DocBook "address" element. :Processing: @@ -375,7 +375,7 @@ Details :Children: ``author`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``author`` is analogous to the DocBook "author" element. :Processing: @@ -440,7 +440,7 @@ Details ``authors`` elements may contain the following elements: author_, organization_, address_, contact_ -:Analogies: +:Analogues: ``authors`` is analogous to the DocBook "authors" element. :Processing: @@ -521,7 +521,7 @@ Details :Children: ``bullet_list`` elements contain one or more list_item_ elements. -:Analogies: +:Analogues: ``bullet_list`` is analogous to the HTML "ul" element and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" @@ -624,7 +624,7 @@ Details :Children: ``classifier`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``classifier`` has no direct analogues in common DTDs. It can be emulated with primitives or type effects. @@ -707,7 +707,7 @@ Details ``contact`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``contact`` is analogous to the DocBook "email" element. The HTML "address" element serves a similar purpose. @@ -773,7 +773,7 @@ Details ``copyright`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``copyright`` is analogous to the DocBook "copyright" element. :Processing: @@ -843,7 +843,7 @@ Details :Children: ``date`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``date`` is analogous to the DocBook "date" element. :Processing: @@ -910,7 +910,7 @@ Details :Children: ``decoration`` elements may contain `decorative elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``decoration`` in HTML or in DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -971,7 +971,7 @@ Details :Children: ``definition`` elements may contain `body elements`_. -:Analogies: +:Analogues: ``definition`` is analogous to the HTML "dd" element and to the DocBook "listitem" element (inside a "variablelistentry" element). @@ -1021,7 +1021,7 @@ Details ``definition_list`` elements contain one or more definition_list_item_ elements. -:Analogies: +:Analogues: ``definition_list`` is analogous to the HTML "dl" element and to the DocBook "variablelist" element. @@ -1100,7 +1100,7 @@ Details ``definition_list_item`` elements each contain a single term_, an optional classifier_, and a definition_. -:Analogies: +:Analogues: ``definition_list_item`` is analogous to the DocBook "variablelistentry" element. @@ -1189,7 +1189,7 @@ Details :Children: ``docinfo`` elements contain `bibliographic elements`_. -:Analogies: +:Analogues: ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. @@ -1301,7 +1301,7 @@ Details ``document`` elements may contain `structural subelements`_, `structural elements`_, and `body elements`_. -:Analogies: +:Analogues: ``document`` is analogous to the HTML "html" element and to several DocBook elements such as "book". @@ -1396,7 +1396,7 @@ Details ``enumerated_list`` elements contain one or more list_item_ elements. -:Analogies: +:Analogues: ``enumerated_list`` is analogous to the HTML "ol" element and to the DocBook "orderedlist" element. @@ -1489,25 +1489,227 @@ See list_item_ for another example. ``field`` ========= -`To be completed`_. +The ``field`` element contains a pair of field_name_ and field_body_ +elements. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + The following elements may contain ``field``: docinfo_, + field_list_ + +:Children: + Each ``field`` element contains one field_name_ and one + field_body_ element. + +:Analogues: + ``field`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (field_name_, field_body_) + +:Attributes: + The ``field`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``field``. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``field_body`` ============== -`To be completed`_. +The ``field_body`` element contains body elements. It is analogous to +a database field's data. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_body``. + +:Children: + ``field_body`` elements may contain `body elements`_. + +:Analogues: + ``field_body`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``field_body`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``field_list`` ============== -`To be completed`_. +The ``field_list`` element contains two-column table-like structures +resembling database records (label & data pairs). Field lists are +often meant for further processing. In reStructuredText, field lists +are used to represent bibliographic fields (contents of the docinfo_ +element) and directive options. + + +Details +------- + +:Category: `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``field_list``. + +:Children: + ``field_list`` elements contain one or more field_ elements. + +:Analogues: + ``field_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + A ``field_list`` is typically rendered as a two-column list, where + the first column contains "labels" (usually with a colon suffix). + However, field lists are often used for extension syntax or + special processing. Such structures do not survive as field lists + to be rendered. + + +Content Model +------------- + +.. parsed-literal:: + + (field_+) + +:Attributes: + The ``field_list`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``field_list``. The `%structure.model;`_ parameter entity + indirectly includes ``field_list``. + + +Examples +-------- + +reStructuredText source:: + + :Author: Me + :Version: 1 + :Date: 2001-08-11 + :Parameter i: integer + +Pseudo-XML_ fragment from simple parsing:: + + <field_list> + <field> + <field_name> + Author + <field_body> + <paragraph> + Me + <field> + <field_name> + Version + <field_body> + <paragraph> + 1 + <field> + <field_name> + Date + <field_body> + <paragraph> + 2001-08-11 + <field> + <field_name> + Parameter i + <field_body> + <paragraph> + integer + +Complete pseudo-XML_ result after parsing and applying transforms:: ``field_name`` ============== -`To be completed`_. +The ``field_name`` element contains text data only. It is analogous +to a database field's name. + + +Details +------- + +:Category: `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_name``. + +:Children: + ``field_name`` elements have no children. They may contain text + data only. + +:Analogues: + ``field_name`` has no direct analogues in common DTDs. + +:Processing: See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``field_name`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. ``figure`` @@ -1536,7 +1738,7 @@ Details :Children: ``footer`` elements may contain `body elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``footer`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1611,7 +1813,7 @@ Details :Children: ``header`` elements may contain `body elements`_. -:Analogies: +:Analogues: There are no direct analogies to ``header`` in HTML or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. @@ -1696,7 +1898,7 @@ Details :Children: ``list_item`` elements may contain `body elements`_. -:Analogies: +:Analogues: ``list_item`` is analogous to the HTML "li" element and to the DocBook "listitem" element. @@ -1821,7 +2023,7 @@ Details ``organization`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``organization`` is analogous to the DocBook "orgname", "corpname", or "publishername" elements. @@ -1889,7 +2091,7 @@ Details ``paragraph`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``paragraph`` is analogous to the HTML "p" element and to the DocBook "para" elements. @@ -1967,7 +2169,7 @@ Details ``revision`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``revision`` is analogous to but simpler than the DocBook "revision" element. It closely matches the DocBook "revnumber" element, but in a simpler context. @@ -2047,7 +2249,7 @@ Details ``section`` elements begin with a title_, and may contain `body elements`_ and transition_ and topic_ elements. -:Analogies: +:Analogues: ``section`` is analogous to DocBook recursive "section" elements, and to HTML "div" elements combined with "h1" etc. title elements. @@ -2137,7 +2339,7 @@ Details :Children: ``status`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``status`` is analogous to the DocBook "status" element. :Processing: @@ -2219,7 +2421,7 @@ Details ``subtitle`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``subtitle`` is analogous to HTML header elements ("h2" etc.) and to the DocBook "subtitle" element. @@ -2311,7 +2513,7 @@ Details :Children: ``term`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``term`` is analogous to the HTML "dt" element and to the DocBook "term" element. @@ -2375,7 +2577,7 @@ Details :Children: ``title`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``title`` is analogous to HTML "title" and header ("h1" etc.) elements, and to the DocBook "title" element. @@ -2438,7 +2640,7 @@ Details ``topic`` elements begin with a title_ and may contain `body elements`_. -:Analogies: +:Analogues: ``topic`` is analogous to the DocBook "simplesect" element. :Processing: @@ -2509,7 +2711,7 @@ Details :Children: ``transition`` is an empty element and has no children. -:Analogies: +:Analogues: ``transition`` is analogous to the HTML "hr" element. :Processing: @@ -2578,7 +2780,7 @@ Details ``version`` elements may contain text data plus `inline elements`_. -:Analogies: +:Analogues: ``version`` may be considered analogous to the DocBook "revision", "revnumber", or "biblioid" elements. -- cgit v1.2.1 From 96b04fd6263cf2a87810a3fdeec2ee023c2392f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 01:56:16 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@756 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index a67b00db4..75f57ef1c 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1666,8 +1666,6 @@ Pseudo-XML_ fragment from simple parsing:: <paragraph> integer -Complete pseudo-XML_ result after parsing and applying transforms:: - ``field_name`` ============== -- cgit v1.2.1 From 35448a37349d3788f2daafb762fd4e730d184b00 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 22:20:13 +0000 Subject: Clarified term/classifier delimiter & inline markup ambiguity (definition lists). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@759 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0538d23c9..88d7a4917 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -733,13 +733,13 @@ definition. Each definition list item contains a term, an optional classifier, and a definition. A term is a simple one-line word or phrase. An -optional classifier may follow the term on the same line, after " : " -(space, colon, space). A definition is a block indented relative to -the term, and may contain multiple paragraphs and other body elements. -There may be no blank line between a term and a definition (this -distinguishes definition lists from `block quotes`_). Blank lines are -required before the first and after the last definition list item, but -are optional in-between. For example:: +optional classifier may follow the term on the same line, after an +inline " : " (space, colon, space). A definition is a block indented +relative to the term, and may contain multiple paragraphs and other +body elements. There may be no blank line between a term line and a +definition block (this distinguishes definition lists from `block +quotes`_). Blank lines are required before the first and after the +last definition list item, but are optional in-between. For example:: term 1 Definition 1. @@ -752,6 +752,10 @@ are optional in-between. For example:: term 3 : classifier Definition 3. +Inline markup is parsed in the term line before the term/classifier +delimiter (" : ") is recognized. The delimiter will only be +recognized if it appears outside of any inline markup. + A definition list may be used in various ways, including: - As a dictionary or glossary. The term is the word itself, a -- cgit v1.2.1 From 54fa9c50bab333a45d75a6a72d5d82a4faf083f4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Oct 2002 22:25:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@763 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 41eb5d791..f55f6bcea 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -340,10 +340,10 @@ http://www.oasis-open.org/html/tm9901.htm). <!ATTLIST option_string %basic.atts;> <!-- -`delimiter` contains the string preceding the `option_argument`: -either the string separating it from the `option` (typically either -"=" or " ") or the string between option arguments (typically either -"," or " "). +`delimiter` contains the text preceding the `option_argument`: either +the text separating it from the `option_string` (typically either "=" +or " ") or the text between option arguments (typically either "," or +" "). --> <!ELEMENT option_argument (#PCDATA)> <!ATTLIST option_argument -- cgit v1.2.1 From d373703eae08290d20056ef966d1edec7b612cc3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Oct 2002 01:18:51 +0000 Subject: typos and minor edits git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@765 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 6 +++--- docs/user/rst/quickstart.txt | 21 ++++++++++----------- 2 files changed, 13 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 2cea6caed..02a1eedde 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2002-09-18</em> + <br align="right"><em>Updated 2002-10-07</em> <p>The full details of the markup may be found on the @@ -43,7 +43,7 @@ <ul> <li><a href="#inline-markup">Inline Markup</a></li> - <li><a href="#escaping">Escaping with Bashslashes</a></li> + <li><a href="#escaping">Escaping with Backslashes</a></li> <li><a href="#section-structure">Section Structure</a></li> <li><a href="#paragraphs">Paragraphs</a></li> <li><a href="#bullet-lists">Bullet Lists</a></li> @@ -187,7 +187,7 @@ nothing is processed). <h2><a href="#contents" name="escaping" class="backref" - >Escaping with Bashslashes</a></h2> + >Escaping with Backslashes</a></h2> <p>(<a href="../../spec/rst/reStructuredText.html#backslashes">details?</a>) diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index ea97a7550..c40c67cdd 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -70,12 +70,12 @@ inside the double back-quotes -- so asterisks "``*``" etc. are left alone. If you find that you want to use one of the "special" characters in -text, it will generally be OK -- ReST is pretty smart. For example, -this * asterisk is handled just fine. If you actually want text -\*surrounded by asterisks* to **not** be italicised, then you need to -indicate that the asterisk is not special. You do this by placing a -backslash just before it, like so "``\*``" (quickref__), or by -enclosing it in double back-quotes (inline literals), like this:: +text, it will generally be OK -- reStructuredText is pretty smart. +For example, this * asterisk is handled just fine. If you actually +want text \*surrounded by asterisks* to **not** be italicised, then +you need to indicate that the asterisk is not special. You do this by +placing a backslash just before it, like so "``\*``" (quickref__), or +by enclosing it in double back-quotes (inline literals), like this:: ``\*`` @@ -309,11 +309,10 @@ results in: .. image:: images/biohazard.png -The ``images/biohazard.png`` part indicates the filname of the image you -wish to appear -in the document. There's no restriction placed on the image (format, size -etc). If the image is to appear in HTML and you wish to supply additional -information, you may:: +The ``images/biohazard.png`` part indicates the filename of the image +you wish to appear in the document. There's no restriction placed on +the image (format, size etc). If the image is to appear in HTML and +you wish to supply additional information, you may:: .. image:: images/biohazard.png :height: 100 -- cgit v1.2.1 From 58036bb54a184a823272be8ddf5f52c619d4f83c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Oct 2002 01:35:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@774 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 18 +++++++++++++++--- docs/user/tools.txt | 14 +++++++++++--- 2 files changed, 26 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e0a65e596..749188f6d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -89,13 +89,25 @@ General - A queue, with entries ``(priority, transform, pending=None)``. - Transform classes can have ``priority`` class attributes. + Each transform could have a unique priority. Use a look-up table? + No, that would require too many imports to construct. - Priorities can be numeric. Integers (0..100? 0..999? 0..9999?)? Floats (would be easier to squeeze in new ones)? - Priorities can be strings. Numeric (000..999? 0000..9999?)? Alphanumeric (a..z? 1, 1a, 1b, ...?)? - - Each transform would have a unique priority. Use a look-up table? - No, that would require too many imports to construct. Document - transform priorities. + - Document transform priorities. + - Add a ``Transformer`` class to register and execute transforms. + Perhaps ``Transformer.add_transform(transform, priority=None)``, + where ``priority`` can be used to override the transform class' + ``default_priority`` class attribute (used if ``None``). + - Perhaps a ``Transformer.add_transforms(transform_list)`` method + for quick population. ``docutils.Component`` could be the host + for the "transforms" class attribute and an ``add_transforms()``. + A ``self.add_transforms()`` call could be added to component + initialization routines. + - How to handle ``pending`` elements? Perhaps a + ``Transformer.add_transform(transform, priority=None)`` method? + Just call it from ``nodes.document.note_pending()``. * @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 2626b2419..6422eab05 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -328,6 +328,13 @@ Some knowledge of Python_ is assumed for some attributes. ==================== ================================================ Config Entry Name Description ==================== ================================================ +expose_internals (Hidden option, for development use only.) List + of internal attribues to expose as external + attributes (with "internal:" namespace prefix). + + Default: don't (None). Options: + ``--expose-internal-attribute``. +-------------------- ------------------------------------------------ compact_lists (HTML Writer.) Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all @@ -361,9 +368,10 @@ debug Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. -------------------- ------------------------------------------------ -dump_internals (Hidden option.) At the end of processing, - print out all internal attributes of the - document (``document.__dict__``). +dump_internals (Hidden option, for development use only.) At + the end of processing, print out all internal + attributes of the document + (``document.__dict__``). Default: don't (None). Options: ``--dump-internals``. -- cgit v1.2.1 From 383b5f2df15a495db48a857018a8ba4e44fa55aa Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Oct 2002 00:43:47 +0000 Subject: many improvements, thanks to Jorge Gonzalez git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@775 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 141 ++++++++++++++++++++++++++++---------------- 1 file changed, 91 insertions(+), 50 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 02a1eedde..65f4f7bb8 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2002-10-07</em> + <br align="right"><em>Updated 2002-10-08</em> <p>The full details of the markup may be found on the @@ -56,18 +56,21 @@ <li><a href="#doctest-blocks">Doctest Blocks</a></li> <li><a href="#tables">Tables</a></li> <li><a href="#transitions">Transitions</a></li> + <li><a href="#explicit-markup">Explicit Markup</a> + <ul> <li><a href="#footnotes">Footnotes</a></li> <li><a href="#citations">Citations</a></li> - <li><a href="#hyperlink-targets">Hyperlink Targets</a></li> + <li><a href="#hyperlink-targets">Hyperlink Targets</a> <ul> <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> - </ul> + </ul></li> <li><a href="#directives">Directives</a></li> <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> <li><a href="#comments">Comments</a></li> + </ul></li> <li><a href="#getting-help">Getting Help</a></li> </ul> @@ -76,6 +79,10 @@ <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details?</a>) + <p>Inline markup allows words and phrases within text to have + character styles (like italics and boldface) and functionality + (like hyperlinks). + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> @@ -87,39 +94,47 @@ <tr valign="top"> <td nowrap><samp>*emphasis*</samp> <td><em>emphasis</em> - <td>  + <td>Normally rendered as italics. <tr valign="top"> <td nowrap><samp>**strong emphasis**</samp> <td><strong>strong emphasis</strong> - <td>  + <td>Normally rendered as boldface. <tr valign="top"> <td nowrap><samp>`interpreted text`</samp> - <td>interpreted text - <td>What interpreted text <em>means</em> is domain dependent. + <td>(see note at right) + <td>The rendering and <em>meaning</em> of interpreted text is + domain- or application-dependent. It can be used for things + like index entries or explicit descriptive markup (like program + identifiers). <tr valign="top"> <td nowrap><samp>``inline literal``</samp> <td><code>inline literal</code> - <td>Spaces should be preserved, but line breaks will not be. + <td>Normally rendered as monospaced text. Spaces should be + preserved, but line breaks will not be. <tr valign="top"> <td nowrap><samp>reference_</samp> <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a href="#hyperlinks">Hyperlinks</a>. + <td>A simple, one-word hyperlink reference. See <a + href="#hyperlinks" >Hyperlinks</a>. <tr valign="top"> <td nowrap><samp>`phrase reference`_</samp> <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be quoted with backquotes. - See <a href="#hyperlink-targets">Hyperlinks</a>. + <td>A hyperlink reference with spaces or punctuation needs to be + quoted with backquotes. See <a + href="#hyperlink-targets">Hyperlinks</a>. <tr valign="top"> <td nowrap><samp>anonymous__</samp> <td><a href="#hyperlink-targets">anonymous</a> - <td>Both simple and phrase references may be anonymous (two underscores). - See <a href="#hyperlink-targets">Hyperlinks</a>. + <td>With two underscores instead of one, both simple and phrase + references may be anonymous (the reference text is not repeated + at the target). See <a + href="#hyperlink-targets">Hyperlinks</a>. <tr valign="top"> <td nowrap><samp>_`inline internal target`</samp> @@ -129,13 +144,15 @@ <tr valign="top"> <td nowrap><samp>|substitution reference|</samp> - <td>(see note) - <td>The result is substituted in from the <a href="#substitution-references-and-definitions">substitution definition</a>. - It could be text, an image, a hyperlink, or a combination of these and others. + <td>(see note at right) + <td>The result is substituted in from the <a + href="#substitution-references-and-definitions">substitution + definition</a>. It could be text, an image, a hyperlink, or a + combination of these and others. <tr valign="top"> <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <a href="#footnotes">[1]</a> + <td>footnote reference <sup><a href="#footnotes">1</a></sup> <td>See <a href="#footnotes">Footnotes</a>. <tr valign="top"> @@ -159,21 +176,23 @@ (with backslash)</a> or quote them (with double backquotes; i.e. use inline literals). - <p>In detail, the reStructuredText specifications says that in - inline markup: + <p>In detail, the reStructuredText specification says that in + inline markup, the following rules apply to start-strings and + end-strings (inline markup delimiters): + <ol> <li>The start-string must start a text block or be - immediately preceded by whitespace,  - <samp>' " ( [ {</samp> or  <samp><</samp>. + immediately preceded by whitespace or any of  + <samp>' " ( [ {</samp> or <samp><</samp>. <li>The start-string must be immediately followed by non-whitespace. <li>The end-string must be immediately preceded by non-whitespace. - <li>The end-string must end a text block or be immediately - followed by whitespace,  - <samp>' " . , : ; ! ? - ) ] }</samp> or  <samp>></samp>. + <li>The end-string must end a text block (end of document or + followed by a blank line) or be immediately followed by whitespace + or any of <samp>' " . , : ; ! ? - ) ] }</samp> or <samp>></samp>. <li>If a start-string is immediately preceded by one of  - <samp>' " ( [ {</samp> or  <samp><</samp>, it must not be + <samp>' " ( [ {</samp> or <samp><</samp>, it must not be immediately followed by the corresponding character from  - <samp>' " ) ] }</samp> or  <samp>></samp>. + <samp>' " ) ] }</samp> or <samp>></samp>. <li>An end-string must be separated by at least one character from the start-string. <li>An <a href="#escaping">unescaped</a> backslash preceding a start-string or end-string will @@ -798,8 +817,17 @@ A transition marker is a horizontal line gap spanning one or more lines, marking text divisions or signaling changes in subject, time, point of view, or emphasis. - <h2><a href="#contents" name="footnotes" class="backref" - >Footnotes</a></h2> + <h2><a href="#contents" name="explicit-markup" class="backref" + >Explicit Markup</a></h3> + + <p>Explicit markup blocks are used for constructs which float + (footnotes), have no direct paper-document representation, + (hyperlink targets, comments), or require specialized processing + (directives). They all begin with two periods and whitespace, the + "explicit markup start". + + <h3><a href="#contents" name="footnotes" class="backref" + >Footnotes</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details?</a>) @@ -822,7 +850,7 @@ A transition marker is a horizontal line <br><samp>   there's no colon after the ``]``.</samp> <td> - Footnote references, like <sup><a href="#5">[5]</a></sup>. + Footnote references, like <sup><a href="#5">5</a></sup>. Note that footnotes may get rearranged, e.g., to the bottom of the "page". @@ -891,8 +919,8 @@ A transition marker is a horizontal line same relative order. Similarly for auto-symbol footnotes ("<samp>[*]_</samp>"). - <h2><a href="#contents" name="citations" class="backref" - >Citations</a></h2> + <h3><a href="#contents" name="citations" class="backref" + >Citations</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#citations">details?</a>) @@ -944,13 +972,13 @@ A transition marker is a horizontal line </table> - <h2><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h2> + <h3><a href="#contents" name="hyperlink-targets" class="backref" + >Hyperlink Targets</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details?</a>) - <h3><a href="#contents" name="external-hyperlink-targets" class="backref" - >External Hyperlink Targets</a></h3> + <h4><a href="#contents" name="external-hyperlink-targets" class="backref" + >External Hyperlink Targets</a></h4> <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -988,8 +1016,8 @@ A transition marker is a horizontal line printed documents, where the link needs to be presented explicitly, for example as a footnote. - <h3><a href="#contents" name="internal-hyperlink-targets" class="backref" - >Internal Hyperlink Targets</a></h3> + <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" + >Internal Hyperlink Targets</a></h4> <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -1024,8 +1052,8 @@ A transition marker is a horizontal line </table> - <h3><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h3> + <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" + >Indirect Hyperlink Targets</a></h4> <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details?</a>) @@ -1058,10 +1086,14 @@ A transition marker is a horizontal line (<i>indirectly</i> pointing at the Python website via the "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink target</b>. In the text, a double-underscore suffix is used to - indicate an <b>anonymous hyperlink reference</b>. + indicate an <b>anonymous hyperlink reference</b>. In an anonymous + hyperlink target, the reference text is not repeated. This is + useful for references with long text or throw-away references, but + the target should be kept close to the reference to prevent them + going out of sync. - <h3><a href="#contents" name="implicit-hyperlink-targets" class="backref" - >Implicit Hyperlink Targets</a></h3> + <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" + >Implicit Hyperlink Targets</a></h4> <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details?</a>) @@ -1087,11 +1119,17 @@ A transition marker is a horizontal line targets, too</a>. </table> - <h2><a href="#contents" name="directives" class="backref" - >Directives</a></h2> + <h3><a href="#contents" name="directives" class="backref" + >Directives</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#directives">details?</a>) + <p>Directives are a general-purpose extension mechanism, a way of + adding support for new constructs without adding new syntax. For + a description of all standard directives, see <a + href="../../spec/rst/directives.html" >reStructuredText + Directives</a>. + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> @@ -1109,8 +1147,8 @@ A transition marker is a horizontal line <p><img src="images/ball1.gif" alt="ball1"> </table> - <h2><a href="#contents" name="substitution-references-and-definitions" - class="backref" >Substitution References and Definitions</a></h2> + <h3><a href="#contents" name="substitution-references-and-definitions" + class="backref" >Substitution References and Definitions</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details?</a>) @@ -1140,11 +1178,14 @@ dispose of medical waste.</samp> </table> - <h2><a href="#contents" name="comments" class="backref" - >Comments</a></h2> + <h3><a href="#contents" name="comments" class="backref" + >Comments</a></h3> <p>(<a href="../../spec/rst/reStructuredText.html#comments">details?</a>) + <p>Any text which begins with an explicit markup start but doesn't + use the syntax of any of the constructs above, is a comment. + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> <tr align="left" bgcolor="#99CCFF"> @@ -1164,13 +1205,13 @@ dispose of medical waste.</samp> <tr valign="top"> <td> - <samp>An empty "comment" directive does not</samp> + <samp>An empty "comment" does not</samp> <br><samp>"consume" following blocks.</samp> <p><samp>..</samp> <p><samp>        So this block is not "lost",</samp> <br><samp>        despite its indentation.</samp> <td> - An empty "comment" directive does not + An empty "comment" does not "consume" following blocks. <blockquote> So this block is not "lost", -- cgit v1.2.1 From 7413a2c5688f098e12539710604fa046ed41b0c2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Oct 2002 00:49:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@777 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 129 ++++++++++++++++++++++++++---------------------------- 1 file changed, 62 insertions(+), 67 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 749188f6d..e28f59b80 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -87,80 +87,78 @@ General Ideas: - - A queue, with entries ``(priority, transform, pending=None)``. - - Transform classes can have ``priority`` class attributes. - Each transform could have a unique priority. Use a look-up table? - No, that would require too many imports to construct. - - Priorities can be numeric. Integers (0..100? 0..999? - 0..9999?)? Floats (would be easier to squeeze in new ones)? - - Priorities can be strings. Numeric (000..999? 0000..9999?)? - Alphanumeric (a..z? 1, 1a, 1b, ...?)? - - Document transform priorities. - - Add a ``Transformer`` class to register and execute transforms. - Perhaps ``Transformer.add_transform(transform, priority=None)``, - where ``priority`` can be used to override the transform class' - ``default_priority`` class attribute (used if ``None``). - - Perhaps a ``Transformer.add_transforms(transform_list)`` method - for quick population. ``docutils.Component`` could be the host - for the "transforms" class attribute and an ``add_transforms()``. - A ``self.add_transforms()`` call could be added to component - initialization routines. - - How to handle ``pending`` elements? Perhaps a - ``Transformer.add_transform(transform, priority=None)`` method? - Just call it from ``nodes.document.note_pending()``. + - Add a ``Transformer`` class that registers and executes + transforms. -* @@@ Break up ``references.Hyperlinks`` into multiple smaller - transforms. + - Class contains a queue, with entries ``(priority, transform, + pending=None)``. -* Make it easier to say, "Here's a reStructuredText string; give me - HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to - ``core.publish_file()``? + - Perhaps ``Transformer.add_transform(transform, priority=None)``, + where ``priority`` can be used to override the transform class' + ``default_priority`` class attribute (used if ``None``). -* @@@@ All system messages should have a "line" attribute, to improve - diagnostic output. So all elements constructed by the parser should - have internal "line" ("lineno"/"line_number") attributes. They'd - need internal "source" attributes as well (populating the external - "source" attribute would clutter up the output). + - Perhaps a ``Transformer.add_transforms(transform_list)`` method + for quick population. ``docutils.Component`` could be the host + for the ``default_transforms`` class attribute and an + ``add_transforms()`` method. - Is there any way we can get this to happen automagically, without - having to add the attribute manually to each object? System - messages get their "source" attribute from the Reporter object (new - one for each source). + - How to handle ``pending`` elements? Perhaps a + ``Transformer.add_pending(pending, priority=None)`` method? + Just call it from ``nodes.document.note_pending()``. Need to + re-sort the queue whenever a new transform is added. - - Add an observer subject interface to StateMachine, called whenever - next_line, previous_line, or goto_line is called? + - Who creates a ``Transformer`` object? Attach it to the + ``document`` object? Needs to be accessible when instantiating + other components? Or when "runtime initializing" them. - - Who to notify? Publisher? Document object? Singleton? + - Should components initialize the ``Transformer`` object (add + ``self.add_transforms()`` calls to components' ``__init__``), or + should the ``Transformer`` initialize itself, accessing the + transform lists of the components? - - Document object: add ``note_source``, ``note_line_number`` - methods. ``note_line_number`` is called by - ``StateMachine.notify_observers``. Whatever reads the source - calls ``note_source`` (``utils.new_document()``, "include" - directive. + - Pass a ``Transformer`` object at component instantiation time? - - Add a ``line=None`` parameter to ``nodes.Node``; if unspecified, - it will get the line number from the observer. (``source=None`` - too?) + - Transform classes can have ``priority`` class attributes. + Each transform could have a unique priority. Use a look-up table? + No, that would require too many imports to construct. - - Perhaps ``Element.append()`` etc. can also set the ``.document`` - attribute of each node added. The document object could hold the - current line number and source description, which would also be - copied over to the node. Consolidate all assignments (parent, - document, source, line) into a single method. + - Priorities can be numeric. Integers (0..100? 0..999? + 100..999? 0..9999?)? Floats (would be easier to squeeze in new + ones)? -* @@@ Change stderr Reporter output to the GNU utilities format:: + - Priorities can be strings. Numeric (000..999? 100..999? + 0000..9999?)? Alphanumeric (a..z? 1, 1a, 1b, ...?)? - file:line: message + - Document transform priorities. - or the BSD 4.3 cc format:: + - Change ``Transform.transform()`` to ``Transform.apply()``? + + :: + + +--------------------------+ + | Docutils: | + | docutils.core.Publisher, | + | docutils.core.publish() | + +--------------------------+ + / | \ + / | \ + 1,3,5 / 6 | \ 7 + +--------+ +-------------+ +--------+ + | READER | ====> | TRANSFORMER | ===> | WRITER | + +--------+ +-------------+ +--------+ + / \\ | + / \\ | + 2 / 4 \\ 8 | + +-----+ +--------+ +-----+ + | I/O | | PARSER | | I/O | + +-----+ +--------+ +-----+ - file(line): message +* @@@ Break up ``references.Hyperlinks`` into multiple smaller + transforms. - The GNU utilities format doesn't work well on MacOS 9 & earlier, - where directory separators are colons. "filename.txt:1:" looks like - a file or directory path. Does MacOS X still use colons, or has it - switched to slashes? In any case, the ubiquity of the GNU utilities - probably outweighs any such problem. +* Make it easier to say, "Here's a reStructuredText string; give me + HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to + ``core.publish_file()``? * Standalone Reader: Implement an option to turn off the DocTitle transform? @@ -535,12 +533,9 @@ __ rst/alternatives.html#or-not-to-do (And arguably invalid, since in Japanese the word "haiku" contains three syllables.) -* Modify acceptable "simple reference name" syntax to allow for - ``object.__method__`` without requiring inline literals? Simple - reference names currently allow any of "-", "_", and "." internally; - if we limit this to one at a time, problem solved. I.e., none of - these would be recognized as simple names: "one..two", "one-.two", - "one._two", "one__two". +* Implement auto-enumerated lists? See `Auto-Enumerated Lists`__. + + __ rst/alternatives.html#auto-enumerated-lists Directives @@ -616,7 +611,7 @@ Directives 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) -- cgit v1.2.1 From 14bdfad14a8717b9672fe5b7a4e9b1aecb1e02ce Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Oct 2002 00:59:53 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@779 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 65f4f7bb8..b1a1bb3ed 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -821,7 +821,7 @@ A transition marker is a horizontal line >Explicit Markup</a></h3> <p>Explicit markup blocks are used for constructs which float - (footnotes), have no direct paper-document representation, + (footnotes), have no direct paper-document representation (hyperlink targets, comments), or require specialized processing (directives). They all begin with two periods and whitespace, the "explicit markup start". -- cgit v1.2.1 From 71cd002d07424cfa16059a3069f16bc4efac13a1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Oct 2002 01:39:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@780 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e28f59b80..b29f6d10d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -133,7 +133,7 @@ General - Change ``Transform.transform()`` to ``Transform.apply()``? - :: + Updated project model under consideration for PEP 258:: +--------------------------+ | Docutils: | -- cgit v1.2.1 From bceac09bdf0941abdbdb4690f76cac31fee63176 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Oct 2002 03:02:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@782 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 97 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b29f6d10d..96ed3ac28 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -70,7 +70,7 @@ General 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 +* 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"?) @@ -170,11 +170,100 @@ General .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. +* Add object numbering and object references (tables & figures). + + We'll need _`persistent sequences`, such as chapter numbers. See + OpenOffice XML "fields". + + We need to name the objects: + + - "name" attribute for the "figure" directive? :: + + .. figure:: image.png + :name: image's name + + How to name tables, which don't need directives? + + - But this could also be done this way (perhaps more generally):: + + .. _figure name: + + .. figure:: image.png + + Applies equally well to tables. + + We'll also need syntax for object references. See OpenOffice 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? + + - An interpreted text approach is better:: + + See :figure:`figure name` on :page:`figure name`. + + The "figure" and "page" roles could generate some boilerplate + text. The position of the role (prefix or suffix) could also be + utilized. + +* 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 + + + + + + + + (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. + + __ rst/directives.html#including-an-external-document-fragment + Documentation ------------- -* User docs. +* User docs. What's needed? Implementation Docs @@ -185,7 +274,7 @@ Implementation Docs * spec/doctree.txt: DTD element structural relationships, semantics, and attributes. In progress; element descriptions to be completed. -* How-to docs: In spec/howto/? +* How-to docs: In spec/howto/. - How a Writer works & how to write one @@ -210,7 +299,8 @@ Specification [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.]). + (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. @@ -299,8 +389,8 @@ __ rst/alternatives.html#or-not-to-do * 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 +* 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. @@ -547,7 +637,7 @@ Directives * Implement attributes on existing directives: - - _`images.image`: "align", "border"? + - _`images.image`: "border"? - _`parts.sectnum`: "start", "local"? -- cgit v1.2.1 From 62de3120694f48834addfcd85a9c85dc95feac42 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 11 Oct 2002 01:34:35 +0000 Subject: Added "--tab-width" option. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@786 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 6422eab05..0cf585f6e 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -446,7 +446,7 @@ pep_home (PEP/HTML Writer.) Home URL prefix for PEPs. ``--pep-home``. -------------------- ------------------------------------------------ pep_references (reStructuredText Parser.) Recognize and link - to PEP references (like "PEP 258") + to PEP references (like "PEP 258"). Default: disabled (None); enabled (1) in PEP Reader. Options: ``--pep-references``. @@ -490,7 +490,7 @@ report_level Verbosity threshold at or above which system --verbose, -v, --quiet, -q``. -------------------- ------------------------------------------------ rfc_references (reStructuredText Parser.) Recognize and link - to RFC references (like "RFC 822") + to RFC references (like "RFC 822"). Default: disabled (None); enabled (1) in PEP Reader. Options: ``--rfc-references``. @@ -528,6 +528,11 @@ stylesheet-path (HTML Writer.) Path to CSS stylesheet [#pwd]_. Default: None. Options: ``--stylesheet``. -------------------- ------------------------------------------------ +tab_width (reStructuredText Parser.) Number of spaces for + hard tab expansion. + + Default: 8. Options: ``--tab-width``. +-------------------- ------------------------------------------------ toc_backlinks Enable backlinks from section titles to table of contents entries ("entry"), to the top of the TOC ("top"), or disable ("none"). -- cgit v1.2.1 From 8bc9254160b3f3ff159192bfe612168fb89dca6d Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 11 Oct 2002 01:40:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@787 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 41 ++++++++++++++++++++++++++++----------- docs/ref/rst/directives.txt | 6 +++++- docs/ref/rst/restructuredtext.txt | 10 ++++++---- 3 files changed, 41 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 96ed3ac28..f2d33ddb8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -173,7 +173,8 @@ General * Add object numbering and object references (tables & figures). We'll need _`persistent sequences`, such as chapter numbers. See - OpenOffice XML "fields". + `OpenOffice.org XML`_ "fields". Should the sequences be automatic + or manual (user-specifyable)? We need to name the objects: @@ -182,18 +183,32 @@ General .. figure:: image.png :name: image's name - How to name tables, which don't need directives? + To name tables, we could use a "table" directive:: - - But this could also be done this way (perhaps more generally):: + .. table:: optional title here + :name: table's name + + ===== ===== + x not x + ===== ===== + True False + False True + ===== ===== + + This would also allow other attributes to be set, like border + styles. The same technique could be used for other objects. + + - The object could also be done this way:: .. _figure name: .. figure:: image.png - Applies equally well to tables. + 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 XML - "reference fields": + We'll also need syntax for object references. See `OpenOffice.org + XML`_ "reference fields": - Parameterized substitutions? For example:: @@ -210,15 +225,17 @@ General 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? + through? Too complicated. - - An interpreted text approach is better:: + - An interpreted text approach is simpler and better:: See :figure:`figure name` on :page:`figure name`. - The "figure" and "page" roles could generate some boilerplate - text. The position of the role (prefix or suffix) could also be - utilized. + The "figure" and "page" roles could generate appropriate + boilerplate text. The position of the role (prefix or suffix) + could also be utilized. + + .. _OpenOffice.org XML: http://xml.openoffice.org/ * Think about large documents made up of multiple subdocument files. Issues: continuity (`persistent sequences`_ above), cross-references @@ -259,6 +276,8 @@ General __ rst/directives.html#including-an-external-document-fragment +* Change ``document.options`` to ``document.settings``? + Documentation ------------- diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6f6b1ca88..495fec567 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -132,15 +132,19 @@ The following options are recognized: Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users. + ``height`` : integer The height of the image in pixels, used to reserve space or scale the image vertically. + ``width`` : integer The width of the image in pixels, used to reserve space or scale the image horizontally. + ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" symbol is required or allowed). "100" means full-size. + ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ```` tag's "align" attribute. The values "top", "middle", and "bottom" @@ -158,7 +162,7 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). -:Directive Options: Possible. +:Directive Options: Possible; same as those of the `image`_ directive. :Directive Content: Interpreted as the figure caption and an optional legend. diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 88d7a4917..642aace28 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -433,9 +433,9 @@ rearranging the document fragment into a complete document with a title and possibly other metadata elements (author, date, etc.; see `Bibliographic Fields`_). -Specifically, there is no way to specify a document title and subtitle -explicitly in reStructuredText. Instead, a lone top-level section -title (see Sections_ below) can be treated as the document +Specifically, there is no way to indicate a document title and +subtitle explicitly in reStructuredText. Instead, a lone top-level +section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. See the `DocTitle transform`_ for details. @@ -1483,7 +1483,9 @@ may be the only character in the label. For example:: .. [*] This is the footnote. A transform will insert symbols as labels into corresponding footnotes -and footnote references. +and footnote references. The number of references must be equal to +the number of footnotes. One symbol footnote cannot have multiple +references. The standard Docutils system uses the following symbols for footnote marks [#]_: -- cgit v1.2.1 From e8e13a29e1e04d22c0f89c6e792db273f4946731 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 11 Oct 2002 22:56:47 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@792 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 81 ++++++++++++++++++++++++++++++++++++++++++++++++-- docs/peps/pep-0258.txt | 8 +++-- 2 files changed, 84 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f2d33ddb8..f170e85be 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -197,7 +197,7 @@ General This would also allow other attributes to be set, like border styles. The same technique could be used for other objects. - + - The object could also be done this way:: .. _figure name: @@ -243,7 +243,7 @@ General below). When writing a book, the author probably wants to split it up into - files, perhaps one per chapter (but perhaps even more detailed). + 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 @@ -276,6 +276,51 @@ General __ 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. + * Change ``document.options`` to ``document.settings``? @@ -802,7 +847,7 @@ Directives 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 application of + 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 @@ -844,6 +889,36 @@ Directives 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:: + + + + Here's a 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:: + + + Here's a paragraph. + + - _`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" diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 5af970734..15a3317cb 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -223,14 +223,18 @@ Writers produce the final output (HTML, XML, TeX, etc.). Writers translate the internal document tree structure into the final data format, possibly running Writer-specific transforms_ first. +By the time the document gets to the Writer, it should be in final +form. The Writer's job is simply (and only) to translate from the +Docutils doctree structure to the target format. Some small +transforms may be required, but they should be local and +format-specific. + Each writer is a module or package exporting a "Writer" class with a "write" method. The base "Writer" class can be found in the ``docutils/writers/__init__.py`` module. Responsibilities: -- Run transforms over the doctree(s). - - Translate doctree(s) into specific output formats. - Transform references into format-native forms. -- cgit v1.2.1 From 4d2d22cb30463cc94d84909bea9be6d23847e049 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 12 Oct 2002 03:03:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@794 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f170e85be..90d6328e6 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -323,6 +323,22 @@ General * Change ``document.options`` to ``document.settings``? +* Add functional testing to Docutils: Readers, Writers, front ends. + +* 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] + Documentation ------------- @@ -436,6 +452,10 @@ Miscellaneous ideas: 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! + reStructuredText Parser ----------------------- -- cgit v1.2.1 From a6b131e106913f99334c8bfbffff5ab2f0be62e3 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 12 Oct 2002 17:35:48 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@796 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 90d6328e6..e7bcf670a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -133,7 +133,7 @@ General - Change ``Transform.transform()`` to ``Transform.apply()``? - Updated project model under consideration for PEP 258:: + Updated project dataflow model under consideration for PEP 258:: +--------------------------+ | Docutils: | @@ -148,10 +148,10 @@ General +--------+ +-------------+ +--------+ / \\ | / \\ | - 2 / 4 \\ 8 | - +-----+ +--------+ +-----+ - | I/O | | PARSER | | I/O | - +-----+ +--------+ +-----+ + 2 / 4 \\ 8 | + +-------+ +--------+ +--------+ + | INPUT | | PARSER | | OUTPUT | + +-------+ +--------+ +--------+ * @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. @@ -321,7 +321,7 @@ General As I said earlier in chapter :chapter:`objects`, the reference count gets increased every time a binding is made. -* Change ``document.options`` to ``document.settings``? +* Change all occurrences of "options" to "settings"? * Add functional testing to Docutils: Readers, Writers, front ends. @@ -339,6 +339,22 @@ General the very least, there ought to be error checking higher up in the call chain. [Aahz] + ``Publisher.set_options`` 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. + Documentation ------------- -- cgit v1.2.1 From 80745027b66d8622155b91d846ea220d4e60c7ed Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 17 Oct 2002 01:31:37 +0000 Subject: Docutils Internationalization git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@806 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/howto/i18n.txt (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt new file mode 100644 index 000000000..9aeda9f6a --- /dev/null +++ b/docs/howto/i18n.txt @@ -0,0 +1,91 @@ +================================ + Docutils_ Internationalization +================================ + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: + + +This document describes the internationalization (hereafter "i18n": +"i" + 18 letters + "n") facilities of the Docutils_ project. +`Introduction to i18n`_ by Tomohiro KUBOTA is a good general +reference. + +.. Note:: + + The i18n facilities of Docutils should be considered a "first + draft". They work so far, but improvements are welcome. + Specifically, standard i18n facilities like "gettext" have yet to + be explored. + +Docutils is designed to work flexibly with text in multiple languages +(one language at a time). Language-specific features are (or should +be [#]_) fully parameterized. To enable a new language, two modules +have to be added to the project: one for Docutils itself (the +`Docutils Language Module`_) and one for the reStructuredText parser +(the `reStructuredText Language Module`_). + +Language modules are named using a case-insensitive language +identifier as defined in `RFC 1766`_. A typical language identifier +consists of a 2-letter language code from `ISO 639`_ (3-letter codes +can be used if no 2-letter code exists; RFC 1766 is currently being +revised to allow 3-letter codes). If no language identifier is +specified, the default is "en" for English. Examples of module names +include ``en.py``, ``fr.py``, and ``ja.py`` + +.. [#] If anything in Docutils is insufficiently parameterized, it + should be considered a bug. Please report bugs to the Docutils + project bug tracker on SourceForge at + http://sourceforge.net/tracker/?group_id=38414&atid=422030. + +.. _Docutils: http://docutils.sourceforge.net/ +.. _Introduction to i18n: + http://www.debian.org/doc/manuals/intro-i18n/ +.. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html +.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html + + +Docutils Language Module +======================== + +Modules in ``docutils/languages`` contain language mappings for +markup-independent language-specific features of Docutils: + +``labels`` + This is a mapping of node class names to language-dependent + boilerplate label text. The label text is used by Writer + components when they encounter document tree elements whose class + names are the mapping keys. + +``bibliographic_fields`` + This is a mapping of language-dependent field names (converted to + lower case) to node classes (in ``docutils.nodes``). It is used + when parsing bibliographic fields. + +``author_separators`` + This is a list of strings used to parse the 'Authors' + bibliographic field. They separate individual authors' names, and + are tried in order (i.e., earlier items take priority, and the + first item that matches wins). The English-language module + defines them as ``[';', ',']``; semi-colons can be used to + separate names like "Arthur Pewtie, Esq.". + + +reStructuredText Language Module +================================ + +Modules in ``docutils/parsers/rst/languages`` contain language +mappings for language-specific features of the reStructuredText +parser: + +``directives`` + This is a mapping from language-dependent directive names to + canonical directive names. The canonical directive names are + registered in ``docutils/parsers/rst/directives/__init__.py``, in + ``_directive_registry``. -- cgit v1.2.1 From fd593bed5456e2ef6d58dab0b1379764d0ab3823 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 17 Oct 2002 01:45:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@811 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 34 ++++++++++++++++++++++++++-------- docs/howto/rst-directives.txt | 11 ++++++++++- 2 files changed, 36 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e7bcf670a..4e0a6739d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -102,6 +102,9 @@ General for the ``default_transforms`` class attribute and an ``add_transforms()`` method. + - The ``Transformer`` class could host all universal transforms in + its ``default_transforms`` attribute. + - How to handle ``pending`` elements? Perhaps a ``Transformer.add_pending(pending, priority=None)`` method? Just call it from ``nodes.document.note_pending()``. Need to @@ -109,7 +112,20 @@ General - Who creates a ``Transformer`` object? Attach it to the ``document`` object? Needs to be accessible when instantiating - other components? Or when "runtime initializing" them. + other components? Or when "runtime initializing" them? + + a) ``core.Publisher`` creates a ``Transformer`` object, + initializes it from components (reader, parser, writer, + source, destination), and attaches it to ``document`` (via + ``options``]?). + + b) ``document`` is given a ``Transformer`` object + (``document.transformer``) in ``utils.new_document``. + ``Publisher`` populates ``document.transformer`` from + components after the ``self.reader.read`` call returns (be + sure to use ``self.reader.parser``, not ``self.parser``). + ``document.transformer.apply_all`` is called before + ``self.writer.write``. - Should components initialize the ``Transformer`` object (add ``self.add_transforms()`` calls to components' ``__init__``), or @@ -140,12 +156,12 @@ General | docutils.core.Publisher, | | docutils.core.publish() | +--------------------------+ - / | \ - / | \ - 1,3,5 / 6 | \ 7 - +--------+ +-------------+ +--------+ - | READER | ====> | TRANSFORMER | ===> | WRITER | - +--------+ +-------------+ +--------+ + / | \ + / | \ + 1,3,5 / 6 | \ 7 + +--------+ +-------------+ +--------+ + | READER | ---> | TRANSFORMER | ====> | WRITER | + +--------+ +-------------+ +--------+ / \\ | / \\ | 2 / 4 \\ 8 | @@ -172,7 +188,7 @@ General * Add object numbering and object references (tables & figures). - We'll need _`persistent sequences`, such as chapter numbers. See + We may need _`persistent sequences`, such as chapter numbers. See `OpenOffice.org XML`_ "fields". Should the sequences be automatic or manual (user-specifyable)? @@ -355,6 +371,8 @@ General Writers now), and thus have associated option/setting specs and transforms. +* ``docutils.Component`` + Documentation ------------- diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index a1f40e973..5e30e4334 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -168,10 +168,19 @@ directive function itself. Register the Directive ====================== -Register the new directive in ``directives/__init__.py``, in the +Register the new directive in +``docutils/parsers/rst/directives/__init__.py``, in the ``_directive_registry`` dictionary. This allows the reStructuredText parser to find and use the directive. +Add an entry to ``docutils/parsers/rst/languages/en.py`` for the +directive, mapping the English name to the canonical name (both +lowercase). Usually the English name and the canonical name are the +same. + +Please check for and update any other language modules for languages +in which you are proficient. + Examples ======== -- cgit v1.2.1 From a91984c003e1f1ddff4cb4a6ff885381b0d6c155 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 17 Oct 2002 03:25:29 +0000 Subject: Removed "Representation of Horizontal Rules" to spec/rst/alternatives.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 100 --------------------------------------------------- 1 file changed, 100 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 75f57ef1c..a0eeba191 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -3408,106 +3408,6 @@ strong_, substitution_definition_, substitution_reference_, subtitle_, target_, term_, title_, version_ ----------------------- - Miscellaneous Topics ----------------------- - -Representation of Horizontal Rules -================================== - -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: - - Document - ======== - - Paragraph 1 - - -------- - - Paragraph 2 - -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: - - -
- - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 - -There are several possibilities for the implementation: - -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. - -2. Treating "divisions" uniformly brings us to the second - possibility:: - - <document> - <section name="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. - -3. Implement them as "transitions", empty elements:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 - - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. - -Solution 3 was chosen for incorporation into the document tree model. - - .. Local Variables: -- cgit v1.2.1 From 696b91c5403b0d61ee00a69eb5427f03fa387a20 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 17 Oct 2002 03:26:03 +0000 Subject: updated/fixedAdded "Doctree Representation of Transitions" from spec/doctree.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@816 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 99 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index f90320a03..b8a5aca29 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1622,6 +1622,105 @@ be left up to the author? Perhaps if the syntax is *allowed* but its use strongly *discouraged*, for aesthetic reasons? Or would that just be hypocritical? Dilemma. + +Doctree Representation of Transitions +===================================== + +(Although not reStructuredText-specific, this section fits best in +this document.) + +Having added the "horizontal rule" construct to the `reStructuredText +Markup Specification`_, a decision had to be made as to how to reflect +the construct in the implementation of the document tree. Given this +source:: + + Document + ======== + + Paragraph 1 + + -------- + + Paragraph 2 + +The horizontal rule indicates a "transition" (in prose terms) or the +start of a new "division". Before implementation, the parsed document +tree would be:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + -------- <--- error here + <paragraph> + Paragraph 2 + +There are several possibilities for the implementation: + +1. Implement horizontal rules as "divisions" or segments. A + "division" is a title-less, non-hierarchical section. The first + try at an implementation looked like this:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + <division> + <paragraph> + Paragraph 2 + + But the two paragraphs are really at the same level; they shouldn't + appear to be at different levels. There's really an invisible + "first division". The horizontal rule splits the document body + into two segments, which should be treated uniformly. + +2. Treating "divisions" uniformly brings us to the second + possibility:: + + <document> + <section name="document"> + <title> + Document + <division> + <paragraph> + Paragraph 1 + <division> + <paragraph> + Paragraph 2 + + With this change, documents and sections will directly contain + divisions and sections, but not body elements. Only divisions will + directly contain body elements. Even without a horizontal rule + anywhere, the body elements of a document or section would be + contained within a division element. This makes the document tree + deeper. This is similar to the way HTML_ treats document contents: + grouped within a ``<body>`` element. + +3. Implement them as "transitions", empty elements:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + <transition> + <paragraph> + Paragraph 2 + + A transition would be a "point element", not containing anything, + only identifying a point within the document structure. This keeps + the document tree flatter, but the idea of a "point element" like + "transition" smells bad. A transition isn't a thing itself, it's + the space between two divisions. However, transitions are a + practical solution. + +Solution 3 was chosen for incorporation into the document tree model. + .. Local Variables: -- cgit v1.2.1 From 904a224b8e6591a78892cefe18463d2a875f6167 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 17 Oct 2002 03:32:57 +0000 Subject: fixed references git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@818 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 2 ++ docs/ref/doctree.txt | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index b8a5aca29..05327c71b 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1721,6 +1721,8 @@ There are several possibilities for the implementation: Solution 3 was chosen for incorporation into the document tree model. +.. _HTML: http://www.w3.org/MarkUp/ + .. Local Variables: diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index a0eeba191..5332ab96e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2694,7 +2694,11 @@ elements, dividing a section into untitled divisions. A transition may not begin or end a section or document, nor may two transitions be immediately adjacent. -See `Representation of Horizontal Rules`_ below. +See `Doctree Representation of Transitions`__ in `A Record of +reStructuredText Syntax Alternatives`__. + +__ rst/alternatives.txt#doctree-representation-of-transitions +__ rst/alternatives.txt Details -- cgit v1.2.1 From afeedfb343c2904e9357997d2a50f8f3cabb2568 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Oct 2002 04:55:21 +0000 Subject: Refactored names (options -> settings; .transform() -> .apply(); etc.); updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@825 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 51 ++++++++++++++++++++++++-------------------------- docs/peps/pep-0258.txt | 7 ++++--- docs/user/tools.txt | 45 ++++++++++++++++++++++++-------------------- 3 files changed, 53 insertions(+), 50 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4e0a6739d..e6d202e9a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -117,7 +117,7 @@ General a) ``core.Publisher`` creates a ``Transformer`` object, initializes it from components (reader, parser, writer, source, destination), and attaches it to ``document`` (via - ``options``]?). + ``settings``]?). b) ``document`` is given a ``Transformer`` object (``document.transformer``) in ``utils.new_document``. @@ -147,27 +147,25 @@ General - Document transform priorities. - - Change ``Transform.transform()`` to ``Transform.apply()``? - Updated project dataflow model under consideration for PEP 258:: - +--------------------------+ - | Docutils: | - | docutils.core.Publisher, | - | docutils.core.publish() | - +--------------------------+ - / | \ - / | \ - 1,3,5 / 6 | \ 7 - +--------+ +-------------+ +--------+ - | READER | ---> | TRANSFORMER | ====> | WRITER | - +--------+ +-------------+ +--------+ - / \\ | - / \\ | - 2 / 4 \\ 8 | - +-------+ +--------+ +--------+ - | INPUT | | PARSER | | OUTPUT | - +-------+ +--------+ +--------+ + +---------------------------+ + | Docutils: | + | docutils.core.Publisher, | + | docutils.core.publish_*() | + +---------------------------+ + / | \ + / | \ + 1,3,5 / 6 | \ 7 + +--------+ +-------------+ +--------+ + | READER | ----> | TRANSFORMER | ====> | WRITER | + +--------+ +-------------+ +--------+ + / \\ | + / \\ | + 2 / 4 \\ 8 | + +-------+ +--------+ +--------+ + | INPUT | | PARSER | | OUTPUT | + +-------+ +--------+ +--------+ * @@@ Break up ``references.Hyperlinks`` into multiple smaller transforms. @@ -337,8 +335,6 @@ General As I said earlier in chapter :chapter:`objects`, the reference count gets increased every time a binding is made. -* Change all occurrences of "options" to "settings"? - * Add functional testing to Docutils: Readers, Writers, front ends. * Changes to sandbox/davidg/infrastructure/docutils-update? @@ -355,9 +351,9 @@ General the very least, there ought to be error checking higher up in the call chain. [Aahz] - ``Publisher.set_options`` requires that all components be set up + ``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 + 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. @@ -371,7 +367,7 @@ General Writers now), and thus have associated option/setting specs and transforms. -* ``docutils.Component`` +* Documentation @@ -1076,7 +1072,8 @@ HTML Writer ----------- * @@ Construct a _`templating system`, as in ht2html/yaptu, using - directives and substitutions for dynamic stuff. + directives and substitutions for dynamic stuff. Or a specialized + writer to generate .ht & links.h files for ht2html? * Add more support for <link> elements, especially for navigation bars. @@ -1123,7 +1120,7 @@ Front-End Tools apart. * Parameterize help text & defaults somehow? Perhaps a callback? Or - initialize ``cmdline_options`` in ``__init__`` or ``init_options``? + initialize ``settings_spec`` in ``__init__`` or ``init_options``? * Disable common options that don't apply? diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 15a3317cb..f385cebb6 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -94,8 +94,8 @@ format and writing the formatted data to its destination I/O. Calling the "publish" function (or instantiating a "Publisher" object) with component names will result in default behavior. For custom -behavior (setting component options), create custom component objects -first, and pass *them* to publish/Publisher. +behavior (customizing component settings), create custom component +objects first, and pass *them* to publish/Publisher. Readers @@ -324,7 +324,8 @@ Docutils Package Structure convenience function "publish()". See `Publisher`_ above. - Module "docutils.frontend" provides command-line and option - processing for Docutils front-end tools. + processing for Docutils front-end tools, and runtime settings + support for programmatic use. - Module "docutils.io" provides a uniform API for low-level input and output. See `Input/Output`_ above. diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 0cf585f6e..7e1f597bd 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -321,19 +321,20 @@ options is listed in `Configuration File Entries`_ below. Configuration File Entries -------------------------- -The entry names listed below may be specified in `configuration -files`_. Hyphens may be used in place of underscores in entry names. -Some knowledge of Python_ is assumed for some attributes. +Names in the first column of the table below are runtime settings. +Most may be specified in `configuration files`_, where hyphens may be +used in place of underscores. Some knowledge of Python_ is assumed +for some attributes. ==================== ================================================ -Config Entry Name Description +Setting/Config Entry Description ==================== ================================================ -expose_internals (Hidden option, for development use only.) List - of internal attribues to expose as external +expose_internals List of internal attribues to expose as external attributes (with "internal:" namespace prefix). Default: don't (None). Options: - ``--expose-internal-attribute``. + ``--expose-internal-attribute`` (hidden, for + development use only). -------------------- ------------------------------------------------ compact_lists (HTML Writer.) Remove extra vertical whitespace between items of bullet lists and enumerated @@ -368,13 +369,13 @@ debug Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. -------------------- ------------------------------------------------ -dump_internals (Hidden option, for development use only.) At - the end of processing, print out all internal +dump_internals At the end of processing, print out all internal attributes of the document (``document.__dict__``). Default: don't (None). Options: - ``--dump-internals``. + ``--dump-internals`` (hidden, for development + use only). -------------------- ------------------------------------------------ embed_stylesheet (HTML Writer.) Embed the stylesheet in the output HTML file. The stylesheet file must be @@ -430,12 +431,11 @@ newlines (XML Writer.) Generate XML with newlines before Default: don't (None). Options: ``--newlines``. -------------------- ------------------------------------------------ -no_random (PEP/HTML Writer; hidden option.) Workaround - for platforms which core-dump on "``import - random``". +no_random (PEP/HTML Writer.) Workaround for platforms + which core-dump on "``import random``". Default: random enabled (None). Options: - ``--no-random``. + ``--no-random`` (hidden). -------------------- ------------------------------------------------ output_encoding Default: UTF-8. Options: ``--output-encoding, -o``. @@ -552,16 +552,21 @@ warning_stream Path to a file for the output of system messages ---------------------------------------------------------------------- _directories (``buildhtml.py`` front end.) List of paths to source directories, set from positional - arguments. Default: current working directory - (None). No command-line options. + arguments. + + Default: current working directory (None). No + command-line options. -------------------- ------------------------------------------------ _destination Path to output destination, set from positional - arguments. Default: stdout (None). No - command-line options. + arguments. + + Default: stdout (None). No command-line + options. -------------------- ------------------------------------------------ _source Path to input source, set from positional - arguments. Default: stdin (None). No - command-line options. + arguments. + + Default: stdin (None). No command-line options. ==================== ================================================ .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html -- cgit v1.2.1 From e1118b87d660565cdafe0f321adf2bd2fcbe03e9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Oct 2002 23:49:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@834 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++-- docs/peps/pep-0258.txt | 11 ++++++----- 2 files changed, 10 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e6d202e9a..7f42eab5d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -367,7 +367,8 @@ General 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. Documentation @@ -1038,7 +1039,8 @@ If the processed document is written to multiple files (possibly in a directory tree), it will need to be split up. References will have to be adjusted. -(HTML only? For now, yes.) +(HTML only? Initially, yes. Eventually, anything should be +splittable.) Navigation diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index f385cebb6..7fa848911 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -176,11 +176,12 @@ reStructuredText markup. It is implemented in the Transforms ---------- -Transforms change the document tree from one form to another, add to -the tree, or prune it. Transforms are run by Reader and Writer -objects. Some transforms are Reader-specific, some are -Parser-specific, and others are Writer-specific. The choice and order -of transforms is specified in the Reader and Writer objects. +Transforms are applied to the document tree to change it from one form +to another, to add to the tree, or to prune it. Transforms are +applied by Reader and Writer objects. Some transforms are +Reader-specific, some are Parser-specific, and others are +Writer-specific. The choice and order of transforms is specified in +the Reader and Writer objects. Each transform is a class in a module in the ``docutils/transforms/`` package, a subclass of docutils.tranforms.Transform. -- cgit v1.2.1 From 99fbfbba88293ef1c07f4b96cc0cf9a75dc28849 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 00:35:43 +0000 Subject: Added "--dump-pseudo-xml", "--dump-settings", and "--dump-transforms" hidden options. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@842 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 7e1f597bd..3e499b93b 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -369,14 +369,35 @@ debug Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. -------------------- ------------------------------------------------ -dump_internals At the end of processing, print out all internal +dump_internals At the end of processing, write all internal attributes of the document - (``document.__dict__``). + (``document.__dict__``) to stderr. Default: don't (None). Options: ``--dump-internals`` (hidden, for development use only). -------------------- ------------------------------------------------ +dump_pseudo_xml At the end of processing, write the pseudo-XML + representation of the document to stderr. + + Default: don't (None). Options: + ``--dump-pseudo-xml`` (hidden, for development + use only). +-------------------- ------------------------------------------------ +dump_settings At the end of processing, write all Docutils + settings to stderr. + + Default: don't (None). Options: + ``--dump-settings`` (hidden, for development use + only). +-------------------- ------------------------------------------------ +dump_transforms At the end of processing, write a list of all + transforms applied to the document to stderr. + + Default: don't (None). Options: + ``--dump-transforms`` (hidden, for development + use only). +-------------------- ------------------------------------------------ embed_stylesheet (HTML Writer.) Embed the stylesheet in the output HTML file. The stylesheet file must be accessible during processing. The stylesheet is -- cgit v1.2.1 From f70da4a859aed7187bb6c4a183a8827ff4cbb58f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 00:51:28 +0000 Subject: Brought up to date. Many changes. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@854 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 465 +++++++++++++++++++++++++++---------------------- 1 file changed, 254 insertions(+), 211 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 7fa848911..e7df5dc04 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -20,7 +20,7 @@ This PEP documents design issues and implementation details for Docutils, a Python Docstring Processing System (DPS). The rationale and high-level concepts of a DPS are documented in PEP 256, "Docstring Processing System Framework" [#PEP-256]_. Also see PEP 256 for a -"Roadmap to the Doctring PEPs". +"Roadmap to the Docstring PEPs". Docutils is being designed modularly so that any of its components can be replaced easily. In addition, Docutils is not limited to the @@ -39,63 +39,65 @@ documentation. Docutils Project Model ====================== -:: - - +--------------------------+ - | Docutils: | - | docutils.core.Publisher, | - | docutils.core.publish() | - +--------------------------+ - / \ - / \ - 1,3,5,7 / \ 8,10 - +--------+ +--------+ - | READER | =========================> | WRITER | - +--------+ +--------+ - / || \ / \ - / || \ / \ - 2 / 4 || \ 6 9 / \ 11 - +-----+ +--------+ +-------------+ +------------+ +-----+ - | I/O | | PARSER |...| reader | | writer | | I/O | - +-----+ +--------+ | transforms | | transforms | +-----+ - | | | | - | - docinfo | | - system | - | - titles | | messages | - | - linking | | - final | - | - lookups | | checks | - | - reader- | | - writer- | - | specific | | specific | - | - parser- | | - etc. | - | specific | +------------+ - | - layout | - | (stylist) | - | - etc. | - +-------------+ - -The numbers indicate the path a document's data takes through the -code. Double-width lines between reader & parser and between reader & -writer indicate that data sent along these paths should be standard -(pure & unextended) Docutils doc trees. Single-width lines signify -that internal tree extensions or completely unrelated representations -are possible, but they must be supported at both ends. +Project components and data flow:: + + +---------------------------+ + | Docutils: | + | docutils.core.Publisher, | + | docutils.core.publish_*() | + +---------------------------+ + / | \ + / | \ + 1,3,5 / 6 | \ 7 + +--------+ +-------------+ +--------+ + | READER | ----> | TRANSFORMER | ====> | WRITER | + +--------+ +-------------+ +--------+ + / \\ | + / \\ | + 2 / 4 \\ 8 | + +-------+ +--------+ +--------+ + | INPUT | | PARSER | | OUTPUT | + +-------+ +--------+ +--------+ + +The numbers above each component indicate the path a document's data +takes. Double-width lines between Reader & Parser and between +Transformer & Writer indicate that data sent along these paths should +be standard (pure & unextended) Docutils doc trees. Single-width +lines signify that internal tree extensions or completely unrelated +representations are possible, but they must be supported at both ends. Publisher --------- The ``docutils.core`` module contains a "Publisher" facade class and -"publish" convenience function. Publisher encapsulates the high-level -logic of a Docutils system. The ``Publisher.publish()`` method first -calls its Reader, which reads data from its source I/O, parses and -transforms the data, and returns it. ``Publisher.publish()`` then -passes the resulting document tree to its Writer, which further -transforms the document before translating it to the final output -format and writing the formatted data to its destination I/O. +several convenience functions: "publish_cmdline()" (for command-line +front ends), "publish_file()" (for programmatic use with file-like +I/O), and "publish_string()" (for programmatic use with string I/O). +The Publisher class encapsulates the high-level logic of a Docutils +system. The Publisher class has overall responsibility for +processing, controlled by the ``Publisher.publish()`` method: + +1. Set up internal settings (may include config files & command-line + options) and I/O objects. + +2. Call the Reader object to read data from the source Input object + and parse the data with the Parser object. A document object is + returned. + +3. Set up and apply transforms via the Transformer object attached to + the document. + +4. Call the Writer object which translates the document to the final + output format and writes the formatted data to the destination + Output object. Depending on the Output object, the output may be + returned from the Writer, and then from the ``publish()`` method. Calling the "publish" function (or instantiating a "Publisher" object) with component names will result in default behavior. For custom behavior (customizing component settings), create custom component -objects first, and pass *them* to publish/Publisher. +objects first, and pass *them* to the Publisher or ``publish_*`` +convenience functions. Readers @@ -104,9 +106,6 @@ Readers Readers understand the input context (where the data is coming from), send the whole input or discrete "chunks" to the parser, and provide the context to bind the chunks together back into a cohesive whole. -Using transforms_, Readers also resolve references, footnote numbers, -interpreted text processing, and anything else that requires -context-sensitive computation. Each reader is a module or package exporting a "Reader" class with a "read" method. The base "Reader" class can be found in the @@ -118,40 +117,40 @@ still incomplete) will be able to determine the parser on its own. Responsibilities: -- Get input text from the source I/O. +* Get input text from the source I/O. -- Pass the input text to the parser, along with a fresh doctree root. - -- Run transforms over the doctree(s). +* Pass the input text to the parser, along with a fresh `document + tree`_ root. Examples: -- Standalone (Raw/Plain): Just read a text file and process it. +* Standalone (Raw/Plain): Just read a text file and process it. The reader needs to be told which parser to use. The "Standalone Reader" has been implemented in module ``docutils.readers.standalone``. -- Python Source: See `Python Source Reader`_ below. This Reader is +* Python Source: See `Python Source Reader`_ below. This Reader is currently in development in the Docutils sandbox. -- Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. +* Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. -- PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs. +* PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs. The "PEP Reader" has been implemented in module ``docutils.readers.pep``; see PEP 287 and PEP 12. -- Wiki: Global reference lookups of "wiki links" incorporated into +* Wiki: Global reference lookups of "wiki links" incorporated into transforms. (CamelCase only or unrestricted?) Lazy indentation? -- Web Page: As standalone, but recognize meta fields as meta tags. +* Web Page: As standalone, but recognize meta fields as meta tags. Support for templates of some sort? (After ``<body>``, before ``</body>``?) -- FAQ: Structured "question & answer(s)" constructs. +* FAQ: Structured "question & answer(s)" constructs. -- Compound document: Merge chapters into a book. Master TOC file? +* Compound document: Merge chapters into a book. Master manifest + file? Parsers @@ -172,56 +171,78 @@ Example: The only parser implemented so far is for the reStructuredText markup. It is implemented in the ``docutils/parsers/rst/`` package. +The development and integration of other parsers is possible and +encouraged. -Transforms ----------- -Transforms are applied to the document tree to change it from one form -to another, to add to the tree, or to prune it. Transforms are -applied by Reader and Writer objects. Some transforms are -Reader-specific, some are Parser-specific, and others are -Writer-specific. The choice and order of transforms is specified in -the Reader and Writer objects. +.. _transforms: + +Transformer +----------- + +The Transformer class, in ``docutils/transforms/__init__.py``, stores +transforms and applies them to documents. A transformer object is +attached to every new document tree. The Publisher_ calls +``Transformer.apply_transforms()`` to apply all stored transforms to +the document tree. Transforms change the document tree from one form +to another, add to the tree, or prune it. Transforms resolve +references and footnote numbers, processing interpreted text, and do +other context-sensitive processing. + +Some transforms are specific to components (Readers, Parser, Writers, +Input, Output). Standard component-specific transforms are specified +in the ``default_transforms`` attribute of component classes. After +the Reader has finished processing, the Publisher_ calls the +Transformer object's "populate_from_components" method with a list of +components. Each transform is a class in a module in the ``docutils/transforms/`` -package, a subclass of docutils.tranforms.Transform. +package, a subclass of ``docutils.tranforms.Transform``. Transform +classes each have a ``default_priority`` attribute which is used by +the Transformer to apply transforms in order. The default priority +can be overridden when adding transforms to the Transformer object. -Responsibilities: +Transformer responsibilities: + +* Apply transforms to the document tree, in priority order. + +* Store a mapping of component type name ('reader', 'writer', etc.) to + component objects. These are used by certain transforms (such as + "components.Filter") to determine suitability. + +Transform responsibilities: -- Modify a doctree in-place, either purely transforming one structure +* Modify a doctree in-place, either purely transforming one structure into another, or adding new structures based on the doctree and/or external data. -Examples (in the ``docutils/transforms/`` package): +Examples of transforms (in the ``docutils/transforms/`` package): -- frontmatter.DocInfo: Conversion of document metadata (bibliographic +* frontmatter.DocInfo: Conversion of document metadata (bibliographic information). -- references.Hyperlinks: Resolution of hyperlinks. +* references.AnonymousHyperlinks: Resolution of anonymous references + to corresponding targets. -- parts.Contents: Generates a table of contents for a document. +* parts.Contents: Generates a table of contents for a document. -- document.Merger: Combining multiple populated doctrees into one (not - yet implemented or fully understood). +* document.Merger: Combining multiple populated doctrees into one. + (Not yet implemented or fully understood.) -- document.Splitter: Splits a document into a tree-structure of +* document.Splitter: Splits a document into a tree-structure of subdocuments, perhaps by section. It will have to transform references appropriately. (Neither implemented not remotely understood.) -- universal.Pending: Handles transforms that must be executed at - specific stages of processing. - -- components.Filter: Includes or excludes elements which depend on a - specific Docutils component (triggered by the universal.Pending - transform). +* components.Filter: Includes or excludes elements which depend on a + specific Docutils component. Writers ------- Writers produce the final output (HTML, XML, TeX, etc.). Writers -translate the internal document tree structure into the final data +translate the internal `document tree`_ structure into the final data format, possibly running Writer-specific transforms_ first. By the time the document gets to the Writer, it should be in final @@ -236,34 +257,34 @@ Each writer is a module or package exporting a "Writer" class with a Responsibilities: -- Translate doctree(s) into specific output formats. +* Translate doctree(s) into specific output formats. - Transform references into format-native forms. -- Write the translated output to the destination I/O. +* Write the translated output to the destination I/O. Examples: -- XML: Various forms, such as: +* XML: Various forms, such as: - - DocBook (being implemented in the Docutils sandbox). + - Docutils XML (an expression of the internal document tree, + implemented as ``docutils.writers.docutils_xml``). - - Raw doctree XML (accessible via "``doctree.asdom().toxml()``"; no - Writer component implemented yet). + - DocBook (being implemented in the Docutils sandbox). -- HTML (XHTML implemented as ``docutils.writers.html4css1``). +* HTML (XHTML implemented as ``docutils.writers.html4css1``). -- PDF (a ReportLabs interface is being developed in the Docutils +* PDF (a ReportLabs interface is being developed in the Docutils sandbox). -- TeX +* TeX (a LaTeX Writer is being implemented in the sandbox). -- Docutils-native pseudo-XML (implemented as +* Docutils-native pseudo-XML (implemented as ``docutils.writers.pseudoxml``, used for testing). -- Plain text +* Plain text -- reStructuredText? +* reStructuredText? Input/Output @@ -271,69 +292,78 @@ Input/Output I/O classes provide a uniform API for low-level input and output. Subclasses will exist for a variety of input/output mechanisms. +However, they can be considered an implementation detail. Most +applications should be satisfied using one of the convenience +functions associated with the Publisher_. I/O classes are currently in the preliminary stages; there's a lot of work yet to be done. Issues: -- Looking at the list of writers, it seems that only HTML would - require anything other than monolithic output. Perhaps "Writer" - variants, one for each output distribution type? +* How to represent multi-file input (files & directories) in the API? -- How to represent a multi-file document (files & directories) in the - API? +* How to represent multi-file output? Perhaps "Writer" variants, one + for each output distribution type? Or Output objects with + associated transforms? Responsibilities: -- Read data from the input source and/or write data to the output - destination. +* Read data from the input source (Input objects) or write data to the + output destination (Output objects). Examples of input sources: -- A single file on disk or a stream (implemented as +* A single file on disk or a stream (implemented as ``docutils.io.FileInput``). -- Multiple files on disk (``MultiFileInput``?). +* Multiple files on disk (``MultiFileInput``?). -- Python source files: modules and packages. +* Python source files: modules and packages. -- Python strings, as received from a client application +* Python strings, as received from a client application (implemented as ``docutils.io.StringInput``). Examples of output destinations: -- A single file on disk or a stream (implemented as +* A single file on disk or a stream (implemented as ``docutils.io.FileOutput``). -- A tree of directories and files on disk. +* A tree of directories and files on disk. -- A Python string, returned to a client application (implemented as +* A Python string, returned to a client application (implemented as ``docutils.io.StringOutput``). -- A single tree-shaped data structure in memory. +* No output; useful for programmatic applications where only a portion + of the normal output is to be used (implemented as + ``docutils.io.NullOutput``). -- Some other set of data structures in memory. +* A single tree-shaped data structure in memory. + +* Some other set of data structures in memory. Docutils Package Structure ========================== -- Package "docutils". +* Package "docutils". - - Class "Component" is a base class for Docutils components. + - Module "__init__.py" contains: class "Component", a base class for + Docutils components; class "SettingsSpec", a base class for + specifying runtime settings (used by docutils.frontend); and class + "TransformSpec", a base class for specifying transforms. - Module "docutils.core" contains facade class "Publisher" and - convenience function "publish()". See `Publisher`_ above. + convenience functions. See `Publisher`_ above. - - Module "docutils.frontend" provides command-line and option - processing for Docutils front-end tools, and runtime settings - support for programmatic use. + - Module "docutils.frontend" provides runtime settings support, for + programmatic use and front-end tools (including configuration file + support, and command-line argument and option processing). - Module "docutils.io" provides a uniform API for low-level input and output. See `Input/Output`_ above. - Module "docutils.nodes" contains the Docutils document tree - element class library plus Visitor pattern base classes. See - `Document Tree`_ below. + element class library plus tree-traversal Visitor pattern base + classes. See `Document Tree`_ below. - Module "docutils.optik" provides option parsing and command-line help; from Greg Ward's http://optik.sf.net/ project, included for @@ -343,8 +373,9 @@ Docutils Package Structure routines. - Module "docutils.statemachine" contains a finite state machine - specialized for regular-expression-based text filters. The - reStructuredText parser implementation is based on this module. + specialized for regular-expression-based text filters and parsers. + The reStructuredText parser implementation is based on this + module. - Module "docutils.urischemes" contains a mapping of known URI schemes ("http", "ftp", "mail", etc.). @@ -378,7 +409,7 @@ Docutils Package Structure Proposals). - Readers to be added for: Python source code (structure & - docstrings), PEPs, email, FAQ, and perhaps Wiki and others. + docstrings), email, FAQ, and perhaps Wiki and others. See `Readers`_ above. @@ -388,20 +419,26 @@ Docutils Package Structure by name. Class "Writer" is the base class of specific writers. (``docutils/writers/__init__.py``) - - Module "docutils.writers.pseudoxml" is a simple internal - document tree writer; it writes indented pseudo-XML. - - Module "docutils.writers.html4css1" is a simple HyperText Markup Language document tree writer for HTML 4.01 and CSS1. + - Module "docutils.writers.docutils_xml" writes the internal + document tree in XML form. + + - Module "docutils.writers.pseudoxml" is a simple internal + document tree writer; it writes indented pseudo-XML. + - Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms, - such as DocBook and the raw internal doctree), PDF, TeX, - plaintext, reStructuredText, and perhaps others. + such as DocBook), PDF, TeX, plaintext, reStructuredText, and + perhaps others. See `Writers`_ above. - Package "docutils.transforms": tree transform classes. + - Class "Transformer" stores transforms and applies them to + document trees. (``docutils/transforms/__init__.py``) + - Class "Transform" is the base class of specific transforms. (``docutils/transforms/__init__.py``) @@ -425,7 +462,8 @@ Docutils Package Structure Front-End Tools =============== -See `Docutils Front-End Tools`_. +The ``tools/`` directory contains several front ends for common +Docutils processing. See `Docutils Front-End Tools`_ for details. .. _Docutils Front-End Tools: http://docutils.sf.net/docs/tools.html @@ -435,31 +473,34 @@ Document Tree A single intermediate data structure is used internally by Docutils, in the interfaces between components; it is defined in the -docutils.nodes module. It is not required that this data structure be -used *internally* by any of the components, just *between* components. +``docutils.nodes`` module. It is not required that this data +structure be used *internally* by any of the components, just +*between* components as outlined in the diagram in the `Docutils +Project Model`_ above. Custom node types are allowed, provided that either (a) a transform converts them to standard Docutils nodes before they reach the Writer proper, or (b) the custom node is explicitly supported by certain Writers, and is wrapped in a filtered "pending" node. An example of -condition A is the `Python Source Reader`_ (see below), where a +condition (a) is the `Python Source Reader`_ (see below), where a "stylist" transform converts custom nodes. The HTML ``<meta>`` tag is -an example of condition B; it is supported by the HTML Writer but not -by others. The reStructuredText "meta" directive creates a "pending" -node, which contains knowledge that the embedded "meta" node can only -be handled by HTML-compatible writers. The "pending" node is resolved -by the "transforms.components.Filter" transform, which checks that the -calling writer supports HTML; if it doesn't, the "meta" node is -removed from the document. +an example of condition (b); it is supported by the HTML Writer but +not by others. The reStructuredText "meta" directive creates a +"pending" node, which contains knowledge that the embedded "meta" node +can only be handled by HTML-compatible writers. The "pending" node is +resolved by the ``docutils.transforms.components.Filter`` transform, +which checks that the calling writer supports HTML; if it doesn't, the +"pending" node (and enclosed "meta" node) is removed from the +document. The document tree data structure is similar to a DOM tree, but with specific node names (classes) instead of DOM's generic nodes. The schema is documented in an XML DTD (eXtensible Markup Language Document Type Definition), which comes in two parts: -- the Docutils Generic DTD, docutils.dtd_, and +* the Docutils Generic DTD, docutils.dtd_, and -- the OASIS Exchange Table Model, soextbl.dtd_. +* the OASIS Exchange Table Model, soextbl.dtd_. The DTD defines a rich set of elements, suitable for many input and output formats. The DTD retains all information necessary to @@ -476,23 +517,23 @@ When the parser encounters an error in markup, it inserts a system message (DTD element "system_message"). There are five levels of system messages: -- Level-0, "DEBUG": an internal reporting issue. There is no effect +* Level-0, "DEBUG": an internal reporting issue. There is no effect on the processing. Level-0 system messages are handled separately from the others. -- Level-1, "INFO": a minor issue that can be ignored. There is little +* Level-1, "INFO": a minor issue that can be ignored. There is little or no effect on the processing. Typically level-1 system messages are not reported. -- Level-2, "WARNING": an issue that should be addressed. If ignored, +* Level-2, "WARNING": an issue that should be addressed. If ignored, there may be minor problems with the output. Typically level-2 system messages are reported but do not halt processing -- Level-3, "ERROR": a major issue that should be addressed. If +* Level-3, "ERROR": a major issue that should be addressed. If ignored, the output will contain unpredictable errors. Typically level-3 system messages are reported but do not halt processing -- Level-4, "SEVERE": a critical error that must be addressed. +* Level-4, "SEVERE": a critical error that must be addressed. Typically level-4 system messages are turned into exceptions which halt processing. If ignored, the output will contain severe errors. @@ -520,11 +561,11 @@ Processing Model This model will evolve over time, incorporating experience and discoveries. -1. The PySource Reader uses an I/O class to read in some Python - packages and modules, into a tree of strings. +1. The PySource Reader uses an Input class to read in Python packages + and modules, into a tree of strings. 2. The Python modules are parsed, converting the tree of strings into - a tree of abstract syntax trees. + a tree of abstract syntax trees with docstring nodes. 3. The abstract syntax trees are converted into an internal representation of the packages/modules. Docstrings are extracted, @@ -535,7 +576,7 @@ discoveries. Docutils doctrees. 5. PySource assembles all the individual docstrings' doctrees into a - Python-specific custom Docutils tree parallelling the + Python-specific custom Docutils tree paralleling the package/module/class structure; this is a custom Reader-specific internal representation (see the `Docutils Python Source DTD`_). Namespaces must be merged: Python identifiers, hyperlink targets. @@ -544,37 +585,38 @@ discoveries. identifiers are resolved according to the Python namespace lookup rules. See `Identifier Cross-References`_ below. -7. A "Stylist" transform is applied to the custom doctree, custom - nodes are rendered using standard nodes as primitives, and a - standard document tree is emitted. See `Stylist Transforms`_ - below. +7. A "Stylist" transform is applied to the custom doctree (by the + Transformer_), custom nodes are rendered using standard nodes as + primitives, and a standard document tree is emitted. See `Stylist + Transforms`_ below. -8. Other transforms are applied to the standard doctree. +8. Other transforms are applied to the standard doctree by the + Transformer_. 9. The standard doctree is sent to a Writer, which translates the document into a concrete format (HTML, PDF, etc.). -10. The Writer uses an I/O class to write the resulting data to its +10. The Writer uses an Output class to write the resulting data to its destination (disk file, directories and files, etc.). AST Mining ---------- -Abstract Syntax Tree mining code will be written that scans a parsed -Python module, and returns an ordered tree containing the names, -docstrings (including attribute and additional docstrings; see below), -and additional info (in parentheses below) of all of the following -objects: - -- packages -- modules -- module attributes (+ initial values) -- classes (+ inheritance) -- class attributes (+ initial values) -- instance attributes (+ initial values) -- methods (+ parameters & defaults) -- functions (+ parameters & defaults) +Abstract Syntax Tree mining code will be written (or adapted) that +scans a parsed Python module, and returns an ordered tree containing +the names, docstrings (including attribute and additional docstrings; +see below), and additional info (in parentheses below) of all of the +following objects: + +* packages +* modules +* module attributes (+ initial values) +* classes (+ inheritance) +* class attributes (+ initial values) +* instance attributes (+ initial values) +* methods (+ parameters & defaults) +* functions (+ parameters & defaults) (Extract comments too? For example, comments at the start of a module would be a good place for bibliographic field lists.) @@ -582,7 +624,7 @@ 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 +See the python-dev/docstring-develop thread "AST mining", started on 2001-08-14. @@ -595,12 +637,11 @@ Docstring Extraction Rules documented, only identifiers listed in "``__all__``" are examined for docstrings. - b) In the absense of "``__all__``", all identifiers are examined, + b) In the absence of "``__all__``", all identifiers are examined, except those whose names are private (names begin with "_" but don't begin and end with "__"). - c) 1a and 1b can be overridden by a parameter or command-line - option. + c) 1a and 1b can be overridden by runtime settings. 2. Where: @@ -619,7 +660,8 @@ Docstring Extraction Rules docstrings in (a) and (b) will be recognized, extracted, and concatenated. See `Additional Docstrings`_ below. - d) @@@ 2.2-style "properties" with attribute docstrings? + d) @@@ 2.2-style "properties" with attribute docstrings? Wait for + syntax? 3. How: @@ -632,7 +674,7 @@ Docstring Extraction Rules examine an imported module, such as comments and the order of definitions. - - Docstrings are to be recognized in places where the bytecode + - Docstrings are to be recognized in places where the byte-code compiler ignores string literal expressions (2b and 2c above), meaning importing the module will lose these docstrings. @@ -645,7 +687,7 @@ Docstring Extraction Rules limitations must be lived with. Since attribute docstrings and additional docstrings are ignored by -the Python bytecode compiler, no namespace pollution or runtime bloat +the Python byte-code compiler, no namespace pollution or runtime bloat will result from their use. They are not assigned to ``__doc__`` or to any other attribute. The initial parsing of a module may take a slight performance hit. @@ -657,7 +699,7 @@ Attribute Docstrings (This is a simplified version of PEP 224 [#PEP-224]_.) A string literal immediately following an assignment statement is -interpreted by the docstring extration machinery as the docstring of +interpreted by the docstring extraction machinery as the docstring of the target of the assignment statement, under the following conditions: @@ -669,7 +711,7 @@ conditions: b) At the top level of a class definition: a class attribute. c) At the top level of the "``__init__``" method definition of a - class: an instance attribute. + class: an instance attribute. (@@@ ``__new__`` methods?) Since each of the above contexts are at the top level (i.e., in the outermost suite of a definition), it may be necessary to place @@ -688,7 +730,7 @@ conditions: b) For context 1c above, the target must be of the form "``self.attrib``", where "``self``" matches the "``__init__``" method's first parameter (the instance parameter) and "attrib" - is a simple indentifier as in 3a. + is a simple identifier as in 3a. Blank lines may be used after attribute docstrings to emphasize the connection between the assignment and the docstring. @@ -715,25 +757,25 @@ Additional Docstrings Many programmers would like to make extensive use of docstrings for API documentation. However, docstrings do take up space in the -running program, so some of these programmers are reluctant to "bloat -up" their code. Also, not all API documentation is applicable to -interactive environments, where ``__doc__`` would be displayed. - -The docstring processing system's extraction tools will concatenate -all string literal expressions which appear at the beginning of a -definition or after a simple assignment. Only the first strings in -definitions will be available as ``__doc__``, and can be used for -brief usage text suitable for interactive sessions; subsequent string -literals and all attribute docstrings are ignored by the Python -bytecode compiler and may contain more extensive API information. +running program, so some programmers are reluctant to "bloat up" their +code. Also, not all API documentation is applicable to interactive +environments, where ``__doc__`` would be displayed. + +Docutils' docstring extraction tools will concatenate all string +literal expressions which appear at the beginning of a definition or +after a simple assignment. Only the first strings in definitions will +be available as ``__doc__``, and can be used for brief usage text +suitable for interactive sessions; subsequent string literals and all +attribute docstrings are ignored by the Python byte-code compiler and +may contain more extensive API information. Example:: def function(arg): """This is __doc__, function's docstring.""" """ - This is an additional docstring, ignored by the bytecode - compiler, but extracted by the Docutils. + This is an additional docstring, ignored by the byte-code + compiler, but extracted by Docutils. """ pass @@ -756,13 +798,13 @@ Example:: 1. Should we search for docstrings after a ``__future__`` statement? Very ugly. - 2. Redefine ``__future__`` statements to allow multiple preceeding + 2. Redefine ``__future__`` statements to allow multiple preceding string literals? 3. Or should we not even worry about this? There probably shouldn't be ``__future__`` statements in production code, after - all. Will modules with ``__future__`` statements simply have to - put up with the single-docstring limitation? + all. Perhaps modules with ``__future__`` statements will simply + have to put up with the single-docstring limitation. Choice of Docstring Format @@ -779,7 +821,8 @@ format being used, a case-insensitive string matching the input parser's module or package name (i.e., the same name as required to "import" the module or package), or a registered alias. If no ``__docformat__`` is specified, the default format is "plaintext" for -now; this may be changed to the standard format once determined. +now; this may be changed to the standard format if one is ever +established. The ``__docformat__`` string may contain an optional second field, separated from the format name (first field) by a single space: a @@ -821,17 +864,17 @@ when necessary. For example (using reStructuredText markup):: """ Extend `Storer.__init__()` to keep track of instances. - Keep count in `self.instances`, data in `self.data`. + Keep count in `Keeper.instances`, data in `self.data`. """ Storer.__init__(self) - self.instances += 1 + Keeper.instances += 1 self.data = [] """Store data in a list, most recent last.""" - def storedata(self, data): + def store_data(self, data): """ - Extend `Storer.storedata()`; append new `data` to a + Extend `Storer.store_data()`; append new `data` to a list (in `self.data`). """ self.data = data @@ -843,12 +886,12 @@ references to the definitions of the identifiers themselves. Stylist Transforms ------------------ -Stylist transforms are specialized transforms specific to a Reader. -The PySource Reader doesn't have to make any decisions as to style; it -just produces a logically constructed document tree, parsed and -linked, including custom node types. Stylist transforms understand -the custom nodes created by the Reader and convert them into standard -Docutils nodes. +Stylist transforms are specialized transforms specific to the PySource +Reader. The PySource Reader doesn't have to make any decisions as to +style; it just produces a logically constructed document tree, parsed +and linked, including custom node types. Stylist transforms +understand the custom nodes created by the Reader and convert them +into standard Docutils nodes. Multiple Stylist transforms may be implemented and one can be chosen at runtime (through a "--style" or "--stylist" command-line option). -- cgit v1.2.1 From f8c63e4e07ebdcf7c41888c4f9f3ffe4e701a7a3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 00:54:03 +0000 Subject: Added to project. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@855 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 113 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/ref/transforms.txt (limited to 'docs') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt new file mode 100644 index 000000000..92e85179c --- /dev/null +++ b/docs/ref/transforms.txt @@ -0,0 +1,113 @@ +===================== + Docutils Transforms +===================== + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: + + +For background about transforms and the Transformer object, see `PEP +258`_. + +.. _PEP 258: pep-0258.html#transformer + + +Transforms Listed in Priority Order +=================================== + +============================== ====================== ======== +Transform: module.Class Added By Priority +============================== ====================== ======== +references.Substitutions standalone (r) 220 + + pep (r) + +frontmatter.DocTitle standalone (r) 320 + +frontmatter.DocInfo standalone (r) 340 + +peps.Headers pep (r) 360 + +peps.Contents pep (r) 380 + +references.ChainedTargets standalone (r) 420 + + pep (r) + +references.AnonymousHyperlinks standalone (r) 440 + + pep (r) + +references.IndirectHyperlinks standalone (r) 460 + + pep (r) + +peps.TargetNotes pep (r) 520 + +references.TargetNotes peps.TargetNotes (t) 0 + + "target-notes" (d) 540 + +references.Footnotes standalone (r) 620 + + pep (r) + +references.ExternalTargets standalone (r) 640 + + pep (r) + +references.InternalTargets standalone (r) 660 + + pep (r) + +parts.SectNum "sectnum" (d) 710 + +parts.Contents "contents" (d) 720 + + peps.Contents (t) + +peps.PEPZero pep.Headers (t) 760 + +components.Filter "meta" (d) 780 + +universal.Decorations all Readers 820 + +universal.FinalChecks all Writers 840 + +universal.Messages all Writers 860 + +universal.TestMessages DocutilsTestSupport 890 +============================== ====================== ======== + +Legend: + +* (r): Reader +* (d): Directive +* (t): Transform + + +Transform Priority Range Categories +=================================== + +==== ==== ================================================ + Priority Category +---------- ------------------------------------------------ +From To +==== ==== ================================================ + 0 immediate execution (added by another transform) +---------- ------------------------------------------------ + 1 99 unused + 100 199 very early (non-standard) + 200 299 very early + 300 399 early + 400 699 main + 700 799 late + 800 899 very late + 900 999 very late (non-standard) +==== ==== ================================================ -- cgit v1.2.1 From a714d9a65946eaec2c775e27e24159ce65ce10a1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 01:01:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@856 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 98 ++------------------------------------- docs/ref/rst/restructuredtext.txt | 6 +-- 2 files changed, 6 insertions(+), 98 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7f42eab5d..e70026510 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -79,101 +79,6 @@ General * Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -* @@@ Transforms need a priority system. The "first reader" ... - "last writer" system is no longer adequate for pending transforms. - For example, the ``references.TargetNotes`` transform needs to run - after ``references.Hyperlinks.resolve_indirect()`` but before - ``references.Footnotes``. - - Ideas: - - - Add a ``Transformer`` class that registers and executes - transforms. - - - Class contains a queue, with entries ``(priority, transform, - pending=None)``. - - - Perhaps ``Transformer.add_transform(transform, priority=None)``, - where ``priority`` can be used to override the transform class' - ``default_priority`` class attribute (used if ``None``). - - - Perhaps a ``Transformer.add_transforms(transform_list)`` method - for quick population. ``docutils.Component`` could be the host - for the ``default_transforms`` class attribute and an - ``add_transforms()`` method. - - - The ``Transformer`` class could host all universal transforms in - its ``default_transforms`` attribute. - - - How to handle ``pending`` elements? Perhaps a - ``Transformer.add_pending(pending, priority=None)`` method? - Just call it from ``nodes.document.note_pending()``. Need to - re-sort the queue whenever a new transform is added. - - - Who creates a ``Transformer`` object? Attach it to the - ``document`` object? Needs to be accessible when instantiating - other components? Or when "runtime initializing" them? - - a) ``core.Publisher`` creates a ``Transformer`` object, - initializes it from components (reader, parser, writer, - source, destination), and attaches it to ``document`` (via - ``settings``]?). - - b) ``document`` is given a ``Transformer`` object - (``document.transformer``) in ``utils.new_document``. - ``Publisher`` populates ``document.transformer`` from - components after the ``self.reader.read`` call returns (be - sure to use ``self.reader.parser``, not ``self.parser``). - ``document.transformer.apply_all`` is called before - ``self.writer.write``. - - - Should components initialize the ``Transformer`` object (add - ``self.add_transforms()`` calls to components' ``__init__``), or - should the ``Transformer`` initialize itself, accessing the - transform lists of the components? - - - Pass a ``Transformer`` object at component instantiation time? - - - Transform classes can have ``priority`` class attributes. - Each transform could have a unique priority. Use a look-up table? - No, that would require too many imports to construct. - - - Priorities can be numeric. Integers (0..100? 0..999? - 100..999? 0..9999?)? Floats (would be easier to squeeze in new - ones)? - - - Priorities can be strings. Numeric (000..999? 100..999? - 0000..9999?)? Alphanumeric (a..z? 1, 1a, 1b, ...?)? - - - Document transform priorities. - - Updated project dataflow model under consideration for PEP 258:: - - +---------------------------+ - | Docutils: | - | docutils.core.Publisher, | - | docutils.core.publish_*() | - +---------------------------+ - / | \ - / | \ - 1,3,5 / 6 | \ 7 - +--------+ +-------------+ +--------+ - | READER | ----> | TRANSFORMER | ====> | WRITER | - +--------+ +-------------+ +--------+ - / \\ | - / \\ | - 2 / 4 \\ 8 | - +-------+ +--------+ +--------+ - | INPUT | | PARSER | | OUTPUT | - +-------+ +--------+ +--------+ - -* @@@ Break up ``references.Hyperlinks`` into multiple smaller - transforms. - -* Make it easier to say, "Here's a reStructuredText string; give me - HTML." Maybe ``core.publish_string()``; rename ``core.publish`` to - ``core.publish_file()``? - * Standalone Reader: Implement an option to turn off the DocTitle transform? @@ -487,6 +392,9 @@ Miscellaneous ideas: 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 ----------------------- diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 642aace28..00445956c 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1254,9 +1254,9 @@ Simple Tables Simple tables provide a compact and easy to type but limited row-oriented table representation for simple data sets. Cell contents are typically single paragraphs, although arbitrary body elements may -be represented in most cells. Simple tables allow multi-line rows and -column spans, but not row spans. See `Grid Tables`_ above for a -complete table representation. +be represented in most cells. Simple tables allow multi-line rows (in +all but the first column) and column spans, but not row spans. See +`Grid Tables`_ above for a complete table representation. Simple tables are described with horizontal borders made up of "=" and "-" characters. The equals sign ("=") is used for top and bottom -- cgit v1.2.1 From 35a1beda765cd44715a9ea7c4064d71b1abbcf1e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 24 Oct 2002 23:33:52 +0000 Subject: minor updates & fixes git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@859 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 ++- docs/howto/rst-directives.txt | 10 ++---- docs/peps/pep-0256.txt | 4 +-- docs/peps/pep-0258.txt | 8 ++--- docs/peps/pep-0287.txt | 2 +- docs/ref/transforms.txt | 76 ++++++++++++++++++------------------------- 6 files changed, 43 insertions(+), 62 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e70026510..f198f9560 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -296,9 +296,8 @@ Implementation Docs - Transforms -* Document the ``pending`` elements, how they're generated and when - they're triggered ("first reader", "last writer", etc.; priority - system due to be reworked, as noted above). +* 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. diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index 5e30e4334..377ca31ad 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -313,8 +313,8 @@ code:: else: messages = [] title = None - pending = nodes.pending(parts.Contents, 'first writer', - {'title': title}, block_text) + pending = nodes.pending(parts.Contents, {'title': title}, + block_text) pending.details.update(options) state_machine.document.note_pending(pending) return [pending] + messages @@ -345,8 +345,4 @@ Aspects of note include: options, effectively communicating the options forward. The actual table of contents processing is performed by a transform, ``docutils.transforms.parts.Contents``, after the rest of the - document has been parsed. [#]_ - -.. [#] Please note that the priority system for transforms, indicated - above by ``'first writer'`` in the call to the ``nodes.pending`` - class, is due for an overhaul. + document has been parsed. diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index 8dc00f72e..198ebd9d8 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -34,8 +34,8 @@ The concepts of a DPS framework are presented independently of implementation details. -Roadmap to the Doctring PEPs -============================ +Road Map to the Doctring PEPs +============================= There are many aspects to docstring processing. The "Docstring PEPs" have broken up the issues in order to deal with each of them in diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index e7df5dc04..1a0968ecf 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -20,7 +20,7 @@ This PEP documents design issues and implementation details for Docutils, a Python Docstring Processing System (DPS). The rationale and high-level concepts of a DPS are documented in PEP 256, "Docstring Processing System Framework" [#PEP-256]_. Also see PEP 256 for a -"Roadmap to the Docstring PEPs". +"Road Map to the Docstring PEPs". Docutils is being designed modularly so that any of its components can be replaced easily. In addition, Docutils is not limited to the @@ -192,9 +192,9 @@ other context-sensitive processing. Some transforms are specific to components (Readers, Parser, Writers, Input, Output). Standard component-specific transforms are specified in the ``default_transforms`` attribute of component classes. After -the Reader has finished processing, the Publisher_ calls the -Transformer object's "populate_from_components" method with a list of -components. +the Reader has finished processing, the Publisher_ calls +``Transformer.populate_from_components()`` with a list of components +and all default transforms are stored. Each transform is a class in a module in the ``docutils/transforms/`` package, a subclass of ``docutils.tranforms.Transform``. Transform diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index 4b4ed4e44..af790a53e 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -25,7 +25,7 @@ what-you-see-is-what-you-get plaintext markup syntax. Only the low-level syntax of docstrings is addressed here. This PEP is not concerned with docstring semantics or processing at all (see -PEP 256 for a "Roadmap to the Doctring PEPs"). Nor is it an attempt +PEP 256 for a "Road Map to the Doctring PEPs"). Nor is it an attempt to deprecate pure plaintext docstrings, which are always going to be legitimate. The reStructuredText markup is an alternative for those who want more expressive docstrings. diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 92e85179c..a5564f042 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -21,84 +21,70 @@ For background about transforms and the Transformer object, see `PEP Transforms Listed in Priority Order =================================== -============================== ====================== ======== -Transform: module.Class Added By Priority -============================== ====================== ======== -references.Substitutions standalone (r) 220 +============================== ============================ ======== +Transform: module.Class Added By Priority +============================== ============================ ======== +references.Substitutions standalone (r), pep (r) 220 - pep (r) +frontmatter.DocTitle standalone (r) 320 -frontmatter.DocTitle standalone (r) 320 +frontmatter.DocInfo standalone (r) 340 -frontmatter.DocInfo standalone (r) 340 +peps.Headers pep (r) 360 -peps.Headers pep (r) 360 +peps.Contents pep (r) 380 -peps.Contents pep (r) 380 +references.ChainedTargets standalone (r), pep (r) 420 -references.ChainedTargets standalone (r) 420 +references.AnonymousHyperlinks standalone (r), pep (r) 440 - pep (r) +references.IndirectHyperlinks standalone (r), pep (r) 460 -references.AnonymousHyperlinks standalone (r) 440 +peps.TargetNotes pep (r) 520 - pep (r) +references.TargetNotes peps.TargetNotes (t/p) 0 -references.IndirectHyperlinks standalone (r) 460 +references.TargetNotes "target-notes" (d/p) 540 - pep (r) +references.Footnotes standalone (r), pep (r) 620 -peps.TargetNotes pep (r) 520 +references.ExternalTargets standalone (r), pep (r) 640 -references.TargetNotes peps.TargetNotes (t) 0 +references.InternalTargets standalone (r), pep (r) 660 - "target-notes" (d) 540 +parts.SectNum "sectnum" (d/p) 710 -references.Footnotes standalone (r) 620 +parts.Contents "contents" (d/p), 720 + peps.Contents (t/p) - pep (r) +peps.PEPZero pep.Headers (t/p) 760 -references.ExternalTargets standalone (r) 640 +components.Filter "meta" (d/p) 780 - pep (r) +universal.Decorations Transformer 820 -references.InternalTargets standalone (r) 660 +universal.FinalChecks Transformer 840 - pep (r) +universal.Messages Transformer 860 -parts.SectNum "sectnum" (d) 710 +universal.TestMessages DocutilsTestSupport 890 +============================== ============================ ======== -parts.Contents "contents" (d) 720 - - peps.Contents (t) - -peps.PEPZero pep.Headers (t) 760 - -components.Filter "meta" (d) 780 - -universal.Decorations all Readers 820 - -universal.FinalChecks all Writers 840 - -universal.Messages all Writers 860 - -universal.TestMessages DocutilsTestSupport 890 -============================== ====================== ======== - -Legend: +Key: * (r): Reader * (d): Directive * (t): Transform +* (/p): Via a "pending" node Transform Priority Range Categories =================================== ==== ==== ================================================ - Priority Category + Priority ---------- ------------------------------------------------ -From To +From To Category ==== ==== ================================================ 0 immediate execution (added by another transform) ---------- ------------------------------------------------ -- cgit v1.2.1 From d01273dd782b4d075ed6e29b6860819dad338490 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 31 Oct 2002 02:36:58 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@868 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 3e499b93b..870f90a6a 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -542,7 +542,7 @@ stylesheet (HTML Writer.) CSS stylesheet URL, used Default: "default.css". Options: ``--stylesheet``. -------------------- ------------------------------------------------ -stylesheet-path (HTML Writer.) Path to CSS stylesheet [#pwd]_. +stylesheet_path (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option (``--stylesheet``). Path is adjusted relative to the output HTML file. -- cgit v1.2.1 From 15e81d9c0111d33107133b79089a21561e398ed9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 31 Oct 2002 02:43:26 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@871 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 22 ++++++++++++++++++---- docs/peps/pep-0258.txt | 5 +++-- 2 files changed, 21 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f198f9560..4a554f715 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,6 +45,19 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. +* @@@ The "include" directive screws up with multiple adjacent + includes of sections. Also, sections must be self-contained (i.e., + a section can't start in an included file and end in the parent + file, because of nested parsing). (Thanks to Brett g Porter for a + bug report that led to this one.) + + Possible solution: Instead of nested parsing, how about replacing + the list of strings for the state machine with an iterator which can + handle multiple files? New files could be inserted, and callbacks + called (observers notified) when the file changes. See + docutils-develop 2002-10-30, subject 'problem with the "include" + directive'. + General ------- @@ -65,10 +78,11 @@ General pollution. Ask opinions on whether or not Docutils should recognize & use them. -* In reader.get_reader_class (& parser & writer 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.) +* 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 diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 1a0968ecf..2ad422d75 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -199,8 +199,9 @@ and all default transforms are stored. Each transform is a class in a module in the ``docutils/transforms/`` package, a subclass of ``docutils.tranforms.Transform``. Transform classes each have a ``default_priority`` attribute which is used by -the Transformer to apply transforms in order. The default priority -can be overridden when adding transforms to the Transformer object. +the Transformer to apply transforms in order (low to high). The +default priority can be overridden when adding transforms to the +Transformer object. Transformer responsibilities: -- cgit v1.2.1 From 6f29cffd10c80e604b5298fbecf046c2c9657cc6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 3 Nov 2002 04:28:21 +0000 Subject: Replaced stilted section example with abstract output. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@882 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index c40c67cdd..5426e9c93 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -269,24 +269,30 @@ underline style are deemed to be at the same level:: Chapter 2 Title =============== -results in: - -.. sorry, I change the heading style here, but it's only an example :) - -Chapter 1 Title -~~~~~~~~~~~~~~~ - -Section 1.1 Title -''''''''''''''''' - -Subsection 1.1.1 Title -"""""""""""""""""""""" - -Section 1.2 Title -''''''''''''''''' - -Chapter 2 Title -~~~~~~~~~~~~~~~ +This results in the following structure, illustrated by simplified +pseudo-XML:: + + <section> + <title> + Chapter 1 Title + <section> + <title> + Section 1.1 Title + <section> + <title> + Subsection 1.1.1 Title + <section> + <title> + Section 1.2 Title + <section> + <title> + Chapter 2 Title + +(Pseudo-XML uses indentation for nesting and has no end-tags. It's +not possible to show actual processed output, as in the other +examples, because sections cannot exist inside block quotes. For a +concrete example, compare the section structure of this document's +source text and processed output.) Note that section headers are available as link targets, just using their name. To link to the Lists_ heading, I write "``Lists_``". If -- cgit v1.2.1 From bfda82c68d90e66574bc4c7907920848e2858aef Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 6 Nov 2002 02:29:25 +0000 Subject: ASCII-only in Python code. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@893 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 40 ++++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 9aeda9f6a..f9a33d334 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -31,14 +31,6 @@ have to be added to the project: one for Docutils itself (the `Docutils Language Module`_) and one for the reStructuredText parser (the `reStructuredText Language Module`_). -Language modules are named using a case-insensitive language -identifier as defined in `RFC 1766`_. A typical language identifier -consists of a 2-letter language code from `ISO 639`_ (3-letter codes -can be used if no 2-letter code exists; RFC 1766 is currently being -revised to allow 3-letter codes). If no language identifier is -specified, the default is "en" for English. Examples of module names -include ``en.py``, ``fr.py``, and ``ja.py`` - .. [#] If anything in Docutils is insufficiently parameterized, it should be considered a bug. Please report bugs to the Docutils project bug tracker on SourceForge at @@ -47,10 +39,42 @@ include ``en.py``, ``fr.py``, and ``ja.py`` .. _Docutils: http://docutils.sourceforge.net/ .. _Introduction to i18n: http://www.debian.org/doc/manuals/intro-i18n/ + + +Language Module Names +===================== + +Language modules are named using a case-insensitive language +identifier as defined in `RFC 1766`_. A typical language identifier +consists of a 2-letter language code from `ISO 639`_ (3-letter codes +can be used if no 2-letter code exists; RFC 1766 is currently being +revised to allow 3-letter codes). If no language identifier is +specified, the default is "en" for English. Examples of module names +include ``en.py``, ``fr.py``, and ``ja.py`` + .. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html +Python Code +=========== + +All Python code in Docutils will be ASCII-only. In language modules, +Unicode-escapes will have to be used for non-ASCII characters. +Although it may be possible for some developers to store non-ASCII +characters directly in strings, it will cause problems for other +developers whose locales are set up differently. + +`PEP 263`_ introduces source code encodings to Python modules, +implemented beginning in Python 2.3. Until PEP 263 is fully +implemented as a well-established convention, proven robust in daily +use, and the tools (editors, CVS, email, etc.) recognize this +convention, Docutils shall remain conservative. + +As mentioned in the note above, developers are invited to explore +"gettext" and other i18n technologies. + + Docutils Language Module ======================== -- cgit v1.2.1 From b2f5d8df179415896167ddbf22d25cdd12769758 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 6 Nov 2002 02:30:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@894 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4a554f715..d0c6f691d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -111,7 +111,7 @@ General We need to name the objects: - - "name" attribute for the "figure" directive? :: + - "name" option for the "figure" directive? :: .. figure:: image.png :name: image's name @@ -128,7 +128,7 @@ General False True ===== ===== - This would also allow other attributes to be set, like border + This would also allow other options to be set, like border styles. The same technique could be used for other objects. - The object could also be done this way:: @@ -669,21 +669,21 @@ Directives * Allow directives to be added at run-time? -* Use the language module for directive attribute names? +* Use the language module for directive option names? -* Implement attributes on existing directives: +* Implement options on existing directives: - _`images.image`: "border"? - _`parts.sectnum`: "start", "local"? - A "local" attribute could enable numbering for sections from a + 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" attribute will specify the sequence set to use at the + 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:: @@ -714,6 +714,9 @@ Directives suppress contents display for sections in a branch from that point down. Or a new directive, like "prune-contents"? + - _`misc.include`: "encoding" option? Take default from runtime + settings. Use Input component to read it in? + * 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 @@ -763,7 +766,7 @@ Directives - _`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 (optional attribute "qa" done). + Add support to parts.contents. New elements would be required. Perhaps:: -- cgit v1.2.1 From 5aed03bda74ab6f155bd07ddba18d32d89f0deab Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 6 Nov 2002 02:47:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@895 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index d0c6f691d..646991646 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1108,6 +1108,9 @@ least important): * 4 spaces per indentation level. No tabs. Indent continuation lines according to the Emacs python-mode standard. +* 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.). @@ -1131,6 +1134,7 @@ least important): .. _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 -- cgit v1.2.1 From ac321a3311501b2c173075dd284c1cb36f4ed33b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 6 Nov 2002 02:47:56 +0000 Subject: link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@896 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index f9a33d334..3e9cc0f89 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -74,6 +74,8 @@ convention, Docutils shall remain conservative. As mentioned in the note above, developers are invited to explore "gettext" and other i18n technologies. +.. _PEP 263: http://www.python.org/peps/pep-0263.html + Docutils Language Module ======================== -- cgit v1.2.1 From f290510ad2f164c0ef773ca098eae21274bcbd9f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 7 Nov 2002 01:53:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@901 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 +++++++++++++++++ docs/user/tools.txt | 16 ++++++++-------- 2 files changed, 25 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 646991646..c35b210f5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -58,6 +58,17 @@ Bugs docutils-develop 2002-10-30, subject 'problem with the "include" directive'. +* From Engelbert Gruber:: + + tools/html.py -l de README.txt donotcare.html + ... + File ".../docutils/parsers/rst/languages/__init__.py", line + 19, in get_language + module = __import__(language_code, globals(), locals()) + ImportError: No module named de + + Shouldn't cause a traceback; just return ``None``. + General ------- @@ -289,6 +300,10 @@ General * Multiple file I/O suggestion from Michael Hudson: use a file-like object or something you can iterate over to get file-like objects. +* Language modules: in accented languages it may be useful to have + both accented and unaccented entries in the ``bibliographic_fields`` + mapping for versatility. + Documentation ------------- @@ -1004,6 +1019,8 @@ HTML Writer * Add more support for <link> elements, especially for navigation bars. +* Make the admonitions more distinctive and varied. + Front-End Tools --------------- diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 870f90a6a..b5bbfdf99 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -329,13 +329,6 @@ for some attributes. ==================== ================================================ Setting/Config Entry Description ==================== ================================================ -expose_internals List of internal attribues to expose as external - attributes (with "internal:" namespace prefix). - - Default: don't (None). Options: - ``--expose-internal-attribute`` (hidden, for - development use only). --------------------- ------------------------------------------------ compact_lists (HTML Writer.) Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all @@ -402,11 +395,18 @@ embed_stylesheet (HTML Writer.) Embed the stylesheet in the output HTML file. The stylesheet file must be accessible during processing. The stylesheet is embedded inside a comment, so it must not - contain the text "--" (two hyphens). + contain the text "``--``" (two hyphens). Default: link, don't embed (None). Options: ``--embed-stylesheet, --link-stylesheet``. -------------------- ------------------------------------------------ +expose_internals List of internal attribues to expose as external + attributes (with "internal:" namespace prefix). + + Default: don't (None). Options: + ``--expose-internal-attribute`` (hidden, for + development use only). +-------------------- ------------------------------------------------ footnote_backlinks Enable or disable backlinks from footnotes and citations to their references. -- cgit v1.2.1 From 47e460c659b1e295d43604762eff2e9147d7df6c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 8 Nov 2002 01:38:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@917 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ docs/peps/pep-0258.txt | 3 ++- 2 files changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c35b210f5..8848d1208 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -304,6 +304,13 @@ General 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 an "--input-language" option & setting? Specify a different + language module for input (bibliographic fields, directives) than + for output ("--language"). + Documentation ------------- diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 2ad422d75..e9df3c9a5 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -455,7 +455,8 @@ Docutils Package Structure - Function "get_language(language_code)", returns matching language module. (``docutils/languages/__init__.py``) - - Module "docutils.languages.en" (English). + - Modules: en.py (English), de.py (German), fr.py (French), sk.py + (Slovak), sv.py (Swedish). - Other languages to be added. -- cgit v1.2.1 From 0b5556688eb293cdd373a5cf0cd3ee5af5842b8a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 8 Nov 2002 22:06:30 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@923 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 8 ++++---- docs/dev/todo.txt | 41 ++++++++++++++++++++++++----------------- 2 files changed, 28 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 05327c71b..c5c859c50 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1356,8 +1356,8 @@ Currently reStructuredText has two hyperlink syntax variations: * Anonymous hyperlinks (in current reStructuredText):: - This is a named reference__ of one word ("reference"). Here is - a `phrase reference`__. Phrase references may even cross `line + This is an anonymous reference__. Here is an anonymous + `phrase reference`__. Phrase references may even cross `line boundaries`__. __ http://www.example.org/reference/ @@ -1380,13 +1380,13 @@ syntaxes for hyperlinks: * First, ``"reference text":URL``:: - This is a named "reference":http://www.example.org/reference/ + This is a "reference":http://www.example.org/reference/ of one word ("reference"). Here is a "phrase reference":http://www.example.org/phrase_reference/. * Second, ``"reference text", http://example.com/absolute_URL``:: - This is a named "reference", http://www.example.org/reference/ + This is a "reference", http://www.example.org/reference/ of one word ("reference"). Here is a "phrase reference", http://www.example.org/phrase_reference/. diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8848d1208..3b53930eb 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,19 +45,6 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -* @@@ The "include" directive screws up with multiple adjacent - includes of sections. Also, sections must be self-contained (i.e., - a section can't start in an included file and end in the parent - file, because of nested parsing). (Thanks to Brett g Porter for a - bug report that led to this one.) - - Possible solution: Instead of nested parsing, how about replacing - the list of strings for the state machine with an iterator which can - handle multiple files? New files could be inserted, and callbacks - called (observers notified) when the file changes. See - docutils-develop 2002-10-30, subject 'problem with the "include" - directive'. - * From Engelbert Gruber:: tools/html.py -l de README.txt donotcare.html @@ -309,7 +296,23 @@ General * Add an "--input-language" option & setting? Specify a different language module for input (bibliographic fields, directives) than - for output ("--language"). + 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.) + +* Add a "test_language.py" module to the test suite. Engelbert Gruber + has started one. See docutils-develop, 2002-11-05, article + "language set testing". + + Idea: the "test_language.py" module could test all languages when + run by "alltests.py", and it could accept a language name argument + if run as a script, like this:: + + test_language.py de Documentation @@ -613,10 +616,10 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. -* @@@ Decide whether or not to implement Simon Budig's "inline - external targets" syntax idea, and if so, how? +* @@@ Decide whether or not to implement Simon Budig's _`inline + external targets` syntax idea, and if so, how? - - As a regular directive affecting its indented text block:: + - As a regular directive affecting only its text block (indented):: .. inline-urls:: @@ -643,6 +646,10 @@ __ rst/alternatives.html#or-not-to-do - Or as a full-blown addition to the spec & parser. + The full discussion is here__. + + __ rst/alternatives.html#inline-external-targets + * Add support for pragma (syntax-altering) directives. * Remove leading numbers from section titles for implicit link names? -- cgit v1.2.1 From f8b508ad727e1ec8ed1b6c72f169adcfe8aeac07 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 9 Nov 2002 02:56:00 +0000 Subject: *** empty log message *** git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@924 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/problems.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index 25fda8136..cead7b5b8 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -281,6 +281,7 @@ definition (this distinguishes definition lists from block quotes). Literal Blocks ============== + The StructuredText_ specification has literal blocks indicated by 'example', 'examples', or '::' ending the preceding paragraph. STNG only recognizes '::'; 'example'/'examples' are not implemented. This -- cgit v1.2.1 From 180a8ae0dba23e223f1d0e70645e9eeb92d582c2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 9 Nov 2002 20:58:34 +0000 Subject: typo caught by GvR git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@926 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0256.txt | 4 ++-- docs/peps/pep-0287.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index 198ebd9d8..bad386391 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -34,8 +34,8 @@ The concepts of a DPS framework are presented independently of implementation details. -Road Map to the Doctring PEPs -============================= +Road Map to the Docstring PEPs +============================== There are many aspects to docstring processing. The "Docstring PEPs" have broken up the issues in order to deal with each of them in diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index af790a53e..c6e48901b 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -25,7 +25,7 @@ what-you-see-is-what-you-get plaintext markup syntax. Only the low-level syntax of docstrings is addressed here. This PEP is not concerned with docstring semantics or processing at all (see -PEP 256 for a "Road Map to the Doctring PEPs"). Nor is it an attempt +PEP 256 for a "Road Map to the Docstring PEPs"). Nor is it an attempt to deprecate pure plaintext docstrings, which are always going to be legitimate. The reStructuredText markup is an alternative for those who want more expressive docstrings. -- cgit v1.2.1 From 9db0294f3fb56bc3b4055eaf2cd79f0d25b527fa Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 13 Nov 2002 01:26:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@944 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 ++++++---------- docs/peps/pep-0258.txt | 2 +- 2 files changed, 7 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3b53930eb..e01d47cf9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -304,16 +304,6 @@ General option could be added to Docutils front ends to do this. (Idea from Engelbert Gruber.) -* Add a "test_language.py" module to the test suite. Engelbert Gruber - has started one. See docutils-develop, 2002-11-05, article - "language set testing". - - Idea: the "test_language.py" module could test all languages when - run by "alltests.py", and it could accept a language name argument - if run as a script, like this:: - - test_language.py de - Documentation ------------- @@ -692,6 +682,12 @@ __ rst/alternatives.html#or-not-to-do __ 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 + Directives `````````` diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index e9df3c9a5..d64110cba 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -450,7 +450,7 @@ Docutils Package Structure - Package "docutils.languages": Language modules contain language-dependent strings and mappings. They are named for their language identifier (as defined in `Choice of Docstring Format`_ - above), converting dashes to underscores. + below), converting dashes to underscores. - Function "get_language(language_code)", returns matching language module. (``docutils/languages/__init__.py``) -- cgit v1.2.1 From 77f2ee4872ec99a61ca1756c2dad1be556877a3a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 14 Nov 2002 02:31:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@949 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e01d47cf9..46356bb9a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,17 +45,6 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -* From Engelbert Gruber:: - - tools/html.py -l de README.txt donotcare.html - ... - File ".../docutils/parsers/rst/languages/__init__.py", line - 19, in get_language - module = __import__(language_code, globals(), locals()) - ImportError: No module named de - - Shouldn't cause a traceback; just return ``None``. - General ------- @@ -1031,6 +1020,8 @@ HTML Writer * Make the admonitions more distinctive and varied. +* Make the "class" attributes optional? Implies no stylesheet? + Front-End Tools --------------- -- cgit v1.2.1 From f39be6acf968ec1b51c73022e26535dc113cd37a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:28:33 +0000 Subject: Added "Testing the Language Modules" section. Expanded. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@956 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 55 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 3e9cc0f89..693513df0 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -12,10 +12,10 @@ .. contents:: -This document describes the internationalization (hereafter "i18n": -"i" + 18 letters + "n") facilities of the Docutils_ project. -`Introduction to i18n`_ by Tomohiro KUBOTA is a good general -reference. +This document describes the internationalization facilities of the +Docutils_ project. `Introduction to i18n`_ by Tomohiro KUBOTA is a +good general reference. "Internationalization" is often abbreviated +as "i18n": "i" + 18 letters + "n". .. Note:: @@ -81,7 +81,12 @@ Docutils Language Module ======================== Modules in ``docutils/languages`` contain language mappings for -markup-independent language-specific features of Docutils: +markup-independent language-specific features of Docutils. To make a +new language module, just copy the ``en.py`` file, rename it with the +code for your language (see `Language Module Names`_ above), and +translate the terms as described below. + +Each Docutils language module contains three module attributes: ``labels`` This is a mapping of node class names to language-dependent @@ -89,11 +94,15 @@ markup-independent language-specific features of Docutils: components when they encounter document tree elements whose class names are the mapping keys. + The entry values should be translated to the target language. + ``bibliographic_fields`` This is a mapping of language-dependent field names (converted to lower case) to node classes (in ``docutils.nodes``). It is used when parsing bibliographic fields. + The keys should be translated to the target language. + ``author_separators`` This is a list of strings used to parse the 'Authors' bibliographic field. They separate individual authors' names, and @@ -102,16 +111,50 @@ markup-independent language-specific features of Docutils: defines them as ``[';', ',']``; semi-colons can be used to separate names like "Arthur Pewtie, Esq.". + Most languages won't have to "translate" this list. + reStructuredText Language Module ================================ Modules in ``docutils/parsers/rst/languages`` contain language mappings for language-specific features of the reStructuredText -parser: +parser. To make a new language module, just copy the ``en.py`` file, +rename it with the code for your language (see `Language Module +Names`_ above), and translate the terms as described below. + +Each reStructuredText language module contains just one module +attribute: ``directives`` This is a mapping from language-dependent directive names to canonical directive names. The canonical directive names are registered in ``docutils/parsers/rst/directives/__init__.py``, in ``_directive_registry``. + + The keys should be translated to the target language. + + +Testing the Language Modules +============================ + +Whenever a new language module is added or an existing one modified, +the unit tests should be run. The test modules can be found in the +docutils/test directory from CVS_ or from the `latest CVS snapshot`_. + +The ``test_language.py`` module can be run as a script. With no +arguments, it will test all language modules. With one or more +language codes, it will test just those languages. For example:: + + $ python test_language.py en + .. + ---------------------------------------- + Ran 2 tests in 0.095s + + OK + +Use the "alltests.py" script to run all test modules, exhaustively +testing the parser and other parts of the Docutils system. + +.. _CVS: http://sourceforge.net/cvs/?group_id=38414 +.. _Docutils snapshot: http://docutils.sf.net/docutils-snapshot.tgz -- cgit v1.2.1 From af974421f6e86bab57638b1c0c8226f32437839b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:29:49 +0000 Subject: Updated "Inline External Targets" & closed the debate. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@957 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index c5c859c50..7fd7d6704 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1547,6 +1547,8 @@ A new type of "inline external hyperlink" has been proposed. for one-word references; the target URL is included within the reference text, forcing a phrase context. + We'll call this variant "embedded URIs". + Problem: how to refer to a title like "HTML Anchors: <a>" (which ends with an HTML/SGML/XML tag)? We could either require more syntax on the target (like ``"`reference text @@ -1560,6 +1562,24 @@ A new type of "inline external hyperlink" has been proposed. I think this is the least objectionable of the syntax alternatives. +Other syntax variations have been proposed (by Brett Cannon and Benja +Fallenstein):: + + `phrase reference`->http://www.example.com + + `phrase reference`@http://www.example.com + + `phrase reference`__ ->http://www.example.com + + `phrase reference` [-> http://www.example.com] + + `phrase reference`__ [-> http://www.example.com] + + `phrase reference` <http://www.example.com>_ + +None of these variations are clearly superior to #3 above. Some have +problems that exclude their use. + With any kind of inline external target syntax it comes down to the conflict between maintainability and plaintext readability. I don't see a major problem with reStructuredText's maintainability, and I @@ -1613,14 +1633,19 @@ reStructuredText for a while, and those *for* the proposal are either new to the list ["fantasai", background unknown] or longtime StructuredText users [Ken Manheimer].) -As is probably obvious, I'm ambivalent/against the proposed "inline -external targets". I value reStructuredText's readability very -highly, and although the proposed syntax offers convenience, I don't -know if the convenience is worth the cost in ugliness. Does the -proposed syntax compromise readability too much, or should the choice -be left up to the author? Perhaps if the syntax is *allowed* but its -use strongly *discouraged*, for aesthetic reasons? Or would that just -be hypocritical? Dilemma. +I was initially ambivalent/against the proposed "inline external +targets". I value reStructuredText's readability very highly, and +although the proposed syntax offers convenience, I don't know if the +convenience is worth the cost in ugliness. Does the proposed syntax +compromise readability too much, or should the choice be left up to +the author? Perhaps if the syntax is *allowed* but its use strongly +*discouraged*, for aesthetic/readability reasons? + +After a great deal of thought and much input from users, I've decided +that there are reasonable use cases for this construct. The +documentation should strongly caution against its use in most +situations, recommending independent block-level targets instead. +Syntax #3 above ("embedded URIs") will be used. Doctree Representation of Transitions -- cgit v1.2.1 From 4c472c98049e7fc5cc8ab42ad3d041ce85e12586 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:30:31 +0000 Subject: Added "Embedded URIs". Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@958 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 66 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 00445956c..b82b648df 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1625,18 +1625,25 @@ indirect. An inline form of internal hyperlink target is available; see `Inline Internal Targets`_. -2. _`External hyperlink targets` have an absolute or relative URI in - their link blocks. For example, take the following input:: +2. _`External hyperlink targets` have an absolute or relative URI or + email address in their link blocks. For example, take the + following input:: See the Python_ home page for info. + `Write to me`_ with your questions. + .. _Python: http://www.python.org + .. _Write to me: jdoe@example.com - After processing into HTML, the hyperlink might be expressed as:: + After processing into HTML, the hyperlinks might be expressed as:: See the <a href="http://www.python.org">Python</a> home page for info. + <a href="mailto:jdoe@example.com">Write to me</a> with your + questions. + An external hyperlink's URI may begin on the same line as the explicit markup start and target name, or it may begin in an indented text block immediately following, with no intervening @@ -1661,6 +1668,9 @@ indirect. .. _link: underscore\_ + It is possible (although not generally recommended) to include URIs + directly within hyperlink references. See `Embedded URIs`_ below. + 3. _`Indirect hyperlink targets` have a hyperlink reference in their link blocks. In the following example, target "one" indirectly references whatever target "two" references, and target "two" @@ -2367,6 +2377,56 @@ match references to targets, but otherwise behave similarly to named hyperlinks. +Embedded URIs +````````````` + +A hyperlink reference may directly embed a target URI inline, within +angle brackets ("<...>") as follows:: + + See the `Python home page <http://www.python.org>`_ for info. + +This is exactly equivalent to:: + + See the `Python home page`_ for info. + + .. _Python home page: http://www.python.org + +The bracketed URI must be preceded by whitespace and be the last text +before the end string. With a single trailing underscore, the +reference is named and the same target URI may be referred to again. + +With two trailing underscores, the reference and target are both +anonymous, and the target cannot be referred to again. These are +"one-off" hyperlinks. For example:: + + `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC + 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together + define the syntax of URIs. + +Equivalent to:: + + `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs. + + __ http://www.rfc-editor.org/rfc/rfc2396.txt + __ http://www.rfc-editor.org/rfc/rfc2732.txt + +If reference text happens to end with angle-bracketed text that is +*not* a URI, the open-angle-bracket needs to be backslash-escaped. +For example, here is a reference to a title describing a tag:: + + See `HTML Element: \<a>`_ below. + +.. Caution:: + + This construct offers easy authoring and maintenance of hyperlinks + at the expense of general readability. Inline URIs, especially + long ones, inevitably interrupt the natural flow of text. For + documents meant to be read in source form, the use of independent + block-level `hyperlink targets`_ is **strongly** recommended. The + embedded URI construct is most suited to documents intended *only* + to be read in processed form. + + Inline Internal Targets ------------------------ -- cgit v1.2.1 From bd499ef3acf8d89237b20bcd6bea9e268eeb0cf3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:35:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@960 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 37 +++---------------------------------- 1 file changed, 3 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 46356bb9a..b934b4d71 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -595,42 +595,11 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. -* @@@ Decide whether or not to implement Simon Budig's _`inline - external targets` syntax idea, and if so, how? - - - As a regular directive affecting only its text block (indented):: - - .. inline-urls:: - - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a - `phrase reference <http://www.example.org - /phrase_reference/>`__. - - - As a pragma directive affecting the entire document (from that - point on). Perhaps a variation on the regular directive:: - - .. inline-urls:: :global: - - Ordinary paragraphs ... - - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a - `phrase reference <http://www.example.org - /phrase_reference/>`__. - - Perhaps "``:pragma:``" instead of "``:global:``"? This pattern - could be useful for other pragma directives: local-scope unless - explicitly specified as global/pragma. - - - Or as a full-blown addition to the spec & parser. - - The full discussion is here__. - - __ rst/alternatives.html#inline-external-targets - * 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."). -- cgit v1.2.1 From 672c894d17866e40a58be7b5a2e57ff42b4cd48a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 02:39:33 +0000 Subject: fix target git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@961 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 693513df0..3c47f8a0f 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -157,4 +157,4 @@ Use the "alltests.py" script to run all test modules, exhaustively testing the parser and other parts of the Docutils system. .. _CVS: http://sourceforge.net/cvs/?group_id=38414 -.. _Docutils snapshot: http://docutils.sf.net/docutils-snapshot.tgz +.. _latest CVS snapshot: http://docutils.sf.net/docutils-snapshot.tgz -- cgit v1.2.1 From 52056baf6fd0350e129e9ef589e9742c2bef1fea Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Nov 2002 03:05:23 +0000 Subject: Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b82b648df..5f7ae8ebd 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2422,7 +2422,7 @@ For example, here is a reference to a title describing a tag:: at the expense of general readability. Inline URIs, especially long ones, inevitably interrupt the natural flow of text. For documents meant to be read in source form, the use of independent - block-level `hyperlink targets`_ is **strongly** recommended. The + block-level `hyperlink targets`_ is **strongly recommended**. The embedded URI construct is most suited to documents intended *only* to be read in processed form. -- cgit v1.2.1 From 3b5fa2b5c2df5a84234f336164a0518480b93a54 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Nov 2002 02:28:47 +0000 Subject: Added ``option_list`` & children (7 elements); fixed up. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@972 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 537 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 457 insertions(+), 80 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5332ab96e..8e27088ca 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -246,7 +246,7 @@ following subsections: - Parameter Entities: Lists the parameter entities which directly or indirectly include the element. -* Examples: reStructuredText examples are shown along with +* Examples: reStructuredText_ examples are shown along with fragments of the document trees resulting from parsing. _`Pseudo-XML` is used for the results of parsing and processing. Pseudo-XML is a representation of XML where nesting is indicated by @@ -291,7 +291,8 @@ line_block_ element: whitespace is significant, especially newlines. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``address``: docinfo_, authors_ @@ -330,7 +331,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -367,7 +368,8 @@ The ``author`` element holds the name of the author of the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``author``: docinfo_, authors_ @@ -401,7 +403,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -431,7 +433,8 @@ documents with multiple authors. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``authors``. @@ -466,7 +469,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -511,7 +514,8 @@ uniformly marked with bullets. Bullets are typically simple dingbats Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -539,15 +543,15 @@ Content Model .. parsed-literal:: - (list_item_+) + (list_item_ +) :Attributes: The ``bullet_list`` element contains the `common attributes`_ (id_, name_, dupname_, source_, and class_), plus bullet_. ``bullet`` is used to record the style of bullet from the input - data. In reStructuredText, it contains one of "-", "+", or "*". - It may be ignored in processing. + data. In documents processed from reStructuredText_, it contains + one of "-", "+", or "*". It may be ignored in processing. :Parameter Entities: The `%body.elements;`_ parameter entity directly includes @@ -558,7 +562,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: - Item 1, paragraph 1. @@ -616,7 +620,8 @@ used to indicate the type of a variable. Details ------- -:Category: `Body Subelements`_ (simple) +:Category: + `Body Subelements`_ (simple) :Parents: Only the definition_list_item_ element contains ``classifier``. @@ -647,7 +652,7 @@ Content Model Examples -------- -Here is a hypothetical data dictionary. reStructuredText source:: +Here is a hypothetical data dictionary. reStructuredText_ source:: name : string Customer name. @@ -698,7 +703,8 @@ is typically used for an email or web address. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: The following elements may contain ``contact``: docinfo_, authors_ @@ -734,7 +740,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -764,7 +770,8 @@ The ``copyright`` element contains the document's copyright statement. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``copyright``. @@ -799,7 +806,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -835,7 +842,8 @@ last modification of the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``date``. @@ -869,7 +877,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -902,7 +910,8 @@ footer_ element is implemented, populated with processing information Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``decoration``. @@ -936,7 +945,7 @@ empty ``decoration`` elements are ever created. Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -963,7 +972,8 @@ to define a term_ in a definition_list_. Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: Only definition_list_item_ elements contain ``definition``. @@ -1010,7 +1020,8 @@ describe or classify things, for dialogues, or to itemize subtopics Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1034,7 +1045,7 @@ Content Model .. parsed-literal:: - (definition_list_item_+) + (definition_list_item_ +) :Attributes: The ``definition_list`` element contains only the `common @@ -1049,7 +1060,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Term Definition. @@ -1090,7 +1101,8 @@ term_/definition_ pair (with optional classifier_). Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: Only the definition_list_ element contains @@ -1125,7 +1137,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Tyrannosaurus Rex : carnivore Big and scary; the "Tyrant King". @@ -1167,7 +1179,45 @@ See definition_list_ and classifier_ for further examples. ``description`` =============== -`To be completed`_. +The ``description`` element contains body elements, describing the +purpose or effect of a command-line option or group of options. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``description``. + +:Children: + ``description`` elements may contain `body elements`_. + +:Analogues: + ``description`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``description`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``docinfo`` @@ -1181,7 +1231,8 @@ front matter of a book, such as the title page and copyright page. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``docinfo``. @@ -1224,7 +1275,7 @@ Content Model Examples -------- -Docinfo is represented in reStructuredText by a field_list_ in a +Docinfo is represented in reStructuredText_ by a field_list_ in a bibliographic context: the first non-comment element of a document_, after any document title_/subtitle_. The field list is transformed into a ``docinfo`` element and its children by a transform. Source:: @@ -1292,7 +1343,8 @@ tree. It is the starting point for a document. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The ``document`` element has no parents. @@ -1337,7 +1389,7 @@ of a ``document``. Examples -------- -reStructuredText source:: +reStructuredText_ source:: A Title ======= @@ -1385,7 +1437,8 @@ uniformly marked with enumerator labels. Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1410,7 +1463,7 @@ Content Model .. parsed-literal:: - (list_item_+) + (list_item_ +) :Attributes: The ``enumerated_list`` element contains the `common attributes`_ @@ -1424,12 +1477,12 @@ Content Model MMMMCMXCIX [4999]). ``prefix`` stores the formatting characters used before the - enumerator. In documents originating from reStructuredText data, + enumerator. In documents originating from reStructuredText_ data, it will contain either "" (empty string) or "(" (left parenthesis). It may or may not affect processing. ``suffix`` stores the formatting characters used after the - enumerator. In documents originating from reStructuredText data, + enumerator. In documents originating from reStructuredText_ data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing. @@ -1447,7 +1500,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: 1. Item 1. @@ -1496,7 +1549,8 @@ elements. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: The following elements may contain ``field``: docinfo_, @@ -1509,7 +1563,8 @@ Details :Analogues: ``field`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1544,7 +1599,8 @@ a database field's data. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: Only the field_ element contains ``field_body``. @@ -1555,7 +1611,8 @@ Details :Analogues: ``field_body`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1581,7 +1638,7 @@ See the examples for the field_list_ and docinfo_ elements. The ``field_list`` element contains two-column table-like structures resembling database records (label & data pairs). Field lists are -often meant for further processing. In reStructuredText, field lists +often meant for further processing. In reStructuredText_, field lists are used to represent bibliographic fields (contents of the docinfo_ element) and directive options. @@ -1589,7 +1646,8 @@ element) and directive options. Details ------- -:Category: `Compound Body Elements`_ +:Category: + `Compound Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -1616,7 +1674,7 @@ Content Model .. parsed-literal:: - (field_+) + (field_ +) :Attributes: The ``field_list`` element contains only the `common attributes`_: @@ -1631,7 +1689,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: :Author: Me :Version: 1 @@ -1677,7 +1735,8 @@ to a database field's name. Details ------- -:Category: `Body Subelements`_ +:Category: + `Body Subelements`_ :Parents: Only the field_ element contains ``field_name``. @@ -1689,7 +1748,8 @@ Details :Analogues: ``field_name`` has no direct analogues in common DTDs. -:Processing: See field_list_. +:Processing: + See field_list_. Content Model @@ -1728,7 +1788,8 @@ processing information (datestamp, a link to Docutils_, etc.). Details ------- -:Category: `Decorative Elements`_ +:Category: + `Decorative Elements`_ :Parents: Only the decoration_ element contains ``footer``. @@ -1757,7 +1818,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -1803,7 +1864,8 @@ page. Docutils does not yet make use of the ``header`` element. Details ------- -:Category: `Decorative Elements`_ +:Category: + `Decorative Elements`_ :Parents: Only the decoration_ element contains ``header``. @@ -1887,7 +1949,8 @@ item. Details ------- -:Category: `Body Subelements`_ (compound) +:Category: + `Body Subelements`_ (compound) :Parents: The bullet_list_ and enumerated_list_ elements contain @@ -1919,7 +1982,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: 1. Outer list, item 1. @@ -1969,37 +2032,332 @@ See bullet_list_ or enumerated_list_ for further examples. ``option`` ========== -`To be completed`_. +The ``option`` element groups an option string together with zero or +more option argument placeholders. Note that reStructuredText_ +currently supports only one argument per option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_group_ element contains ``option``. + +:Children: + Each ``option`` element contains one option_string_ and zero or + more option_argument_ elements. + +:Analogues: + ``option`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_string_, option_argument_ \*) + +:Attributes: + The ``option`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_argument`` =================== -`To be completed`_. +The ``option_argument`` element contains placeholder text for option +arguments. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_argument``. + +:Children: + ``option_argument`` elements contain text data only. + +:Analogues: + ``option_argument`` has no direct analogues in common DTDs. + +:Processing: + The value of the "delimiter" attribute is prefixed to the + ``option_argument``, separating it from its option_string_ or a + preceding ``option_argument``. The ``option_argument`` text is + typically rendered in a monospaced typeface, possibly italicized + or otherwise altered to indicate its placeholder nature. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_argument`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus delimiter_. + + ``delimiter`` contains the text preceding the ``option_argument``: + either the text separating it from the option_string_ (typically + either "=" or " ") or the text between option arguments (typically + either "," or " "). + + +Examples +-------- + +See the examples for the option_list_ element. ``option_group`` ================ -`To be completed`_. +The ``option_group`` element groups together one or more option_ +elements, all synonyms. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``option_group``. + +:Children: + ``option_group`` elements contain one or more option_ elements. + + ``option_group`` is an empty element and has no children. + + Each ``option_group`` element contains one _ and + one _ element. + +:Analogues: + ``option_group`` has no direct analogues in common DTDs. + +:Processing: + Typically option_ elements within an ``option_group`` are joined + together in a comma-separated list. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_group`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_list`` =============== -`To be completed`_. +Each ``option_list`` element contains a two-column list of +command-line options and descriptions, documenting a program's +options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``option_list``. + +:Children: + ``option_list`` elements contain one or more option_list_item_ + elements. + +:Analogues: + ``option_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + An ``option_list`` is typically rendered as a two-column list, + where the first column contains option strings and arguments, and + the second column contains descriptions. + + +Content Model +------------- + +.. parsed-literal:: + + (option_list_item_ +) + +:Attributes: + The ``option_list`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``option_list``. The `%structure.model;`_ parameter entity + indirectly includes ``option_list``. + + +Examples +-------- + +reStructuredText_ source:: + + -a command-line option "a" + -1 file, --one=file, --two file + Multiple options with arguments. + +Pseudo-XML_ fragment from simple parsing:: + + <option_list> + <option_list_item> + <option_group> + <option> + <option_string> + -a + <description> + <paragraph> + command-line option "a" + <option_list_item> + <option_group> + <option> + <option_string> + -1 + <option_argument delimiter=" "> + file + <option> + <option_string> + --one + <option_argument delimiter="="> + file + <option> + <option_string> + --two + <option_argument delimiter=" "> + file + <description> + <paragraph> + Multiple options with arguments. ``option_list_item`` ==================== -`To be completed`_. +The ``option_list_item`` element is a container for a pair of +option_group_ and description_ elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_ element contains ``option_list_item``. + +:Children: + Each ``option_list_item`` element contains one option_group_ and + one description_ element. + +:Analogues: + ``option_list_item`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_list_item`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``option_string`` ================= -`To be completed`_. +The ``option_string`` element contains the text of a command-line +option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_string``. + +:Children: + ``option_string`` elements contain text data only. + +:Analogues: + ``option_string`` has no direct analogues in common DTDs. + +:Processing: + The ``option_string`` text is typically rendered in a monospaced + typeface. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_string`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +See the examples for the option_list_ element. ``organization`` @@ -2012,7 +2370,8 @@ organization, or the organization responsible for the document. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``organization``. @@ -2048,7 +2407,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2078,7 +2437,8 @@ single paragraph, a fundamental building block of documents. Details ------- -:Category: `Simple Body Elements`_ +:Category: + `Simple Body Elements`_ :Parents: All elements employing the `%body.elements;`_ or @@ -2114,7 +2474,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A paragraph. @@ -2158,7 +2518,8 @@ It can be used alone or in conjunction with version_. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``revision``. @@ -2195,7 +2556,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2237,7 +2598,8 @@ not after it. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The following elements may contain ``section``: document_, @@ -2276,7 +2638,7 @@ of a ``section``. Examples -------- -reStructuredText source:: +reStructuredText_ source:: Title 1 ======= @@ -2329,7 +2691,8 @@ such as "Draft", "Final", "Work In Progress", etc. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``status``. @@ -2363,7 +2726,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2410,7 +2773,8 @@ The ``subtitle`` element stores the subtitle of a document_. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: Only the document_ element contains ``subtitle``. @@ -2442,7 +2806,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: ======= Title @@ -2503,7 +2867,8 @@ definition_list_. Details ------- -:Category: `Body Subelements`_ (simple) +:Category: + `Body Subelements`_ (simple) :Parents: Only the definition_list_item_ element contains ``term``. @@ -2566,7 +2931,8 @@ topic_. Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: The following elements may contain ``title``: document_, section_, @@ -2600,7 +2966,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: A Title ======= @@ -2629,7 +2995,8 @@ a ``table`` or a ``list``, or inside another ``topic``. Details ------- -:Category: `Structural Elements`_ +:Category: + `Structural Elements`_ :Parents: The following elements may contain ``topic``: document_, section_ @@ -2667,7 +3034,7 @@ Examples -------- The `"topic" directive`_ is used to create a ``topic`` element. -reStructuredText source:: +reStructuredText_ source:: .. topic:: Title @@ -2704,7 +3071,8 @@ __ rst/alternatives.txt Details ------- -:Category: `Structural Subelements`_ +:Category: + `Structural Subelements`_ :Parents: The following elements may contain ``transition``: document_, @@ -2745,7 +3113,7 @@ The ``transition`` element has no content; it is a "point element". Examples -------- -reStructuredText source:: +reStructuredText_ source:: Paragraph 1. @@ -2773,7 +3141,8 @@ It can be used alone or in conjunction with revision_. Details ------- -:Category: `Bibliographic Elements`_ +:Category: + `Bibliographic Elements`_ :Parents: Only the docinfo_ element contains ``version``. @@ -2810,7 +3179,7 @@ Content Model Examples -------- -reStructuredText source:: +reStructuredText_ source:: Document Title ============== @@ -2937,6 +3306,14 @@ standardized document tree. ``class`` is one of the `common attributes`_, shared by all Docutils elements. +``delimiter`` +============= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``delimiter`` attribute is used in the option_argument_ element. + + ``dupname`` =========== -- cgit v1.2.1 From 4ea8903f17cf86452afef915296820e8c7d8225f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 21 Nov 2002 02:31:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@973 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ docs/ref/rst/directives.txt | 3 +++ 2 files changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b934b4d71..9b78c5df8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,6 +45,10 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. +* In docutils.transforms.peps.TargetNotes, an empty References section + is generated even if there are no references. Reported by David + Ascher. + General ------- @@ -293,6 +297,9 @@ General option could be added to Docutils front ends to do this. (Idea from Engelbert Gruber.) +* Should I/O objects be passed simple encoding name strings instead of + a full-blown settings object? + Documentation ------------- diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 495fec567..1e22f7bd9 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -522,6 +522,9 @@ directive. For example:: If an included document fragment contains section structure, the title adornments must match those of the master document. +The text encoding of the master input source is used for included +files. + The following options are recognized: ``literal`` : flag (empty) -- cgit v1.2.1 From fe4f32cd84affa9cb4cef45cb96d50e899fa17fb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 22 Nov 2002 04:33:02 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@978 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 9b78c5df8..3a194edad 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -720,7 +720,7 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - _`misc.exec`: Execute Python code & insert the results. Perhaps - dangerous? + 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 -- cgit v1.2.1 From 61e1c94b8ec784fa597445dc16a0b9e49da23134 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 28 Nov 2002 03:30:19 +0000 Subject: Added "--no-doctype" and "--no-xml-declaration" options. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@979 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index b5bbfdf99..11748a4e5 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -362,6 +362,11 @@ debug Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. -------------------- ------------------------------------------------ +doctype_declaration (XML Writer.) Generate XML with a DOCTYPE + declaration. + + Default: do (1). Options: ``--no-doctype``. +-------------------- ------------------------------------------------ dump_internals At the end of processing, write all internal attributes of the document (``document.__dict__``) to stderr. @@ -567,6 +572,17 @@ warning_stream Path to a file for the output of system messages Default: stderr (None). Options: ``--warnings``. +-------------------- ------------------------------------------------ +xml_declaration (XML Writer.) Generate XML with an XML + declaration. + + .. Caution:: The XML declaration carries text + encoding information, without which standard + tools may be unable to read the generated + XML. + + Default: do (1). Options: + ``--no-xml-declaration``. -------------------- ------------------------------------------------ **For Internal Use Only** (setting these in a config file has no effect) -- cgit v1.2.1 From 28e18904bc9b3fb12188da9da59574f86c5e5aa3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 28 Nov 2002 03:37:06 +0000 Subject: Clarified algorithm for stripping indentation from docstrings. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@982 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0257.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index 9ce589f88..7cc26480e 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -139,11 +139,12 @@ the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first -line (see example below). Docstring processing tools will strip an -amount of indentation from the second and further lines of the -docstring equal to the indentation of the first non-blank line after -the first line of the docstring. Relative indentation of later lines -in the docstring is retained. +line (see example below). Docstring processing tools will strip a +uniform amount of indentation from the second and further lines of the +docstring, equal to the minimum indentation of all non-blank lines +after the first line of the docstring. Relative indentation of later +lines in the docstring is retained. Any indentation on the first line +of the docstring (i.e., before the first newline) is removed. Insert a blank line before and after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's -- cgit v1.2.1 From 673c882e62ff706d8706218bfe74c203c46c87f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 28 Nov 2002 03:45:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@983 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 12 +++++++++++- docs/dev/todo.txt | 4 +++- 2 files changed, 14 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index 02d754358..79a074cec 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -29,7 +29,8 @@ The formal public identifier for this DTD is:: <!ENTITY % additional.section.elements " | package_section | module_section | class_section - | method_section | function_section | module_attribute_section + | method_section | function_section + | module_attribute_section | function_attribute_section | class_attribute_section | instance_attribute_section "> <!ENTITY % additional.inline.elements @@ -84,6 +85,10 @@ http://docutils.sourceforge.net/spec/docutils.dtd. (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;)> @@ -94,6 +99,11 @@ http://docutils.sourceforge.net/spec/docutils.dtd. %structure.model;)> <!ATTLIST instance_attribute_section %basic.atts;> +<!-- + Section Subelements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + <!ELEMENT fullname (package | module | class | method | function | attribute)+> <!ATTLIST fullname %basic.atts;> diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3a194edad..51978fcb9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -298,7 +298,9 @@ General Engelbert Gruber.) * Should I/O objects be passed simple encoding name strings instead of - a full-blown settings object? + a full-blown settings object? Yes. + + @@@ Remove "settings" parameters before next release. Documentation -- cgit v1.2.1 From f26cec7ea84333534bcc2e9e6be3aa71f1b1771c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 30 Nov 2002 01:59:35 +0000 Subject: Added "Handling Docstring Indentation" section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@984 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0257.txt | 82 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 73 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt index 7cc26480e..23094c56a 100644 --- a/docs/peps/pep-0257.txt +++ b/docs/peps/pep-0257.txt @@ -136,15 +136,9 @@ docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on -the same line as the opening quotes or on the next line. - -The entire docstring is indented the same as the quotes at its first -line (see example below). Docstring processing tools will strip a -uniform amount of indentation from the second and further lines of the -docstring, equal to the minimum indentation of all non-blank lines -after the first line of the docstring. Relative indentation of later -lines in the docstring is retained. Any indentation on the first line -of the docstring (i.e., before the first newline) is removed. +the same line as the opening quotes or on the next line. The entire +docstring is indented the same as the quotes at its first line (see +example below). Insert a blank line before and after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's @@ -218,6 +212,76 @@ the closing quotes on a line by themselves. This way, Emacs' ``fill-paragraph`` command can be used on it. +Handling Docstring Indentation +------------------------------ + +Docstring processing tools will strip a uniform amount of indentation +from the second and further lines of the docstring, equal to the +minimum indentation of all non-blank lines after the first line. Any +indentation in the first line of the docstring (i.e., up to the first +newline) is insignificant and removed. Relative indentation of later +lines in the docstring is retained. Blank lines should be removed +from the beginning and end of the docstring. + +Since code is much more precise than words, here is an implementation +of the algorithm:: + + def trim(docstring): + if not docstring: + return '' + # Convert tabs to spaces (following the normal Python rules) + # and split into a list of lines: + lines = docstring.expandtabs().splitlines() + # Determine minimum indentation (first line doesn't count): + indent = sys.maxint + for line in lines[1:]: + stripped = line.lstrip() + if stripped: + indent = min(indent, len(line) - len(stripped)) + # Remove indentation (first line is special): + trimmed = [lines[0].strip()] + if indent < sys.maxint: + for line in lines[1:]: + trimmed.append(line[indent:].rstrip()) + # Strip off trailing and leading blank lines: + while trimmed and not trimmed[-1]: + trimmed.pop() + while trimmed and not trimmed[0]: + trimmed.pop(0) + # Return a single string: + return '\n'.join(trimmed) + +The docstring in this example contains two newline characters and is +therefore 3 lines long. The first and last lines are blank:: + + def foo(): + """ + This is the second line of the docstring. + """ + +To illustrate:: + + >>> print repr(foo.__doc__) + '\n This is the second line of the docstring.\n ' + >>> foo.__doc__.splitlines() + ['', ' This is the second line of the docstring.', ' '] + >>> trim(foo.__doc__) + 'This is the second line of the docstring.' + +Once trimmed, these docstrings are equivalent:: + + def foo(): + """A multi-line + docstring. + """ + + def bar(): + """ + A multi-line + docstring. + """ + + References and Footnotes ======================== -- cgit v1.2.1 From 7e3ce390de2658e948d5c9c83df50bbc7ab12862 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Dec 2002 02:37:37 +0000 Subject: completed 13 elements; 30 to go git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@993 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 967 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 893 insertions(+), 74 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 8e27088ca..f55aed5f3 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -356,7 +356,64 @@ context. ``attention`` ============= -`To be completed`_. +The ``attention`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): caution_, danger_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``attention``. + +:Children: + ``attention`` elements contain one or more `body elements`_. + +:Analogues: + ``attention`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Attention!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``attention`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``attention``. The `%structure.model;`_ parameter entity + indirectly includes ``attention``. + + +Examples +-------- + +reStructuredText source:: + + .. Attention:: All your base are belong to us. + +Pseudo-XML_ fragment from simple parsing:: + + <attention> + <paragraph> + All your base are belong to us. ``author`` @@ -500,7 +557,70 @@ context. ``block_quote`` =============== -`To be completed`_. +The ``block_quote`` element is used for quotations set off from the +main text (standalone). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``block_quote``. + +:Children: + ``block_quote`` elements may contain `body elements`_. + +:Analogues: + ``block_quote`` is analogous to the "blockquote" element in both + HTML and DocBook. + +:Processing: + ``block_quote`` elements serve to set their contents off from the + main text, typically with indentation and/or other decoration. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``block_quote`` element contains only the `common + attributes`_: id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``block_quote``. The `%structure.model;`_ parameter entity + indirectly includes ``block_quote``. + + +Examples +-------- + +reStructuredText source:: + + As a great paleontologist once said, + + This theory, that is mine, is mine. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + As a great paleontologist once said, + <block_quote> + <paragraph> + This theory, that is mine, is mine. + <paragraph> + -- Anne Elk (Miss) ``bullet_list`` @@ -594,7 +714,63 @@ See list_item_ for another example. ``caution`` =========== -`To be completed`_. +The ``caution`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, danger_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``caution``. + +:Children: + ``caution`` elements contain one or more `body elements`_. + +:Analogues: + ``caution`` is analogous to the DocBook "caution" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Caution" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``caution`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``caution``. The `%structure.model;`_ parameter entity + indirectly includes ``caution``. + + +Examples +-------- + +reStructuredText source:: + + .. Caution:: Don't take any wooden nickels. + +Pseudo-XML_ fragment from simple parsing:: + + <caution> + <paragraph> + Don't take any wooden nickels. ``citation`` @@ -829,7 +1005,64 @@ context. ``danger`` ========== -`To be completed`_. +The ``danger`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, error_, +hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``danger``. + +:Children: + ``danger`` elements contain one or more `body elements`_. + +:Analogues: + ``danger`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "!DANGER!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``danger`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``danger``. The `%structure.model;`_ parameter entity + indirectly includes ``danger``. + + +Examples +-------- + +reStructuredText source:: + + .. DANGER:: Mad scientist at work! + +Pseudo-XML_ fragment from simple parsing:: + + <danger> + <paragraph> + Mad scientist at work! ``date`` @@ -1328,7 +1561,78 @@ see the individual examples for the various `bibliographic elements`_. ``doctest_block`` ================= -`To be completed`_. +The ``doctest_block`` element is a Python-specific variant of +literal_block_. It is a block of text where line breaks and +whitespace are significant and must be preserved. ``doctest_block`` +elements are used for interactive Python interpreter sessions, which +are distinguished by their input prompt: ``>>>``. They are meant to +illustrate usage by example, and provide an elegant and powerful +testing environment via the `doctest module`_ in the Python standard +library. + +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``doctest_block``. + +:Children: + ``doctest_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``doctest_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + As with literal_block_, ``doctest_block`` elements are typically + rendered in a monospaced typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``doctest_block`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``doctest_block``. The `%structure.model;`_ parameter entity + indirectly includes ``doctest_block``. + + +Examples +-------- + +reStructuredText source:: + + This is an ordinary paragraph. + + >>> print 'this is a Doctest block' + this is a Doctest block + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + This is an ordinary paragraph. + <doctest_block xml:space="preserve"> + >>> print 'this is a Doctest block' + this is a Doctest block ``document`` @@ -1536,7 +1840,64 @@ See list_item_ for another example. ``error`` ========= -`To be completed`_. +The ``error`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``error``. + +:Children: + ``error`` elements contain one or more `body elements`_. + +:Analogues: + ``error`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Error" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``error`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``error``. The `%structure.model;`_ parameter entity indirectly + includes ``error``. + + +Examples +-------- + +reStructuredText source:: + + .. Error:: Does not compute. + +Pseudo-XML_ fragment from simple parsing:: + + <error> + <paragraph> + Does not compute. ``field`` @@ -1811,72 +2172,291 @@ Content Model (`%body.elements;`_)+ :Attributes: - The ``footer`` element contains only the `common attributes`_: + The ``footer`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +`To be completed`_. + + +``header`` +========== + +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. Docutils does not yet make use of the ``header`` element. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``header``. + +:Children: + ``header`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``header`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + + +Examples +-------- + +None. + + +``hint`` +======== + +The ``hint`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``hint``. + +:Children: + ``hint`` elements contain one or more `body elements`_. + +:Analogues: + ``hint`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Hint" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``hint`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``hint``. The `%structure.model;`_ parameter entity indirectly + includes ``hint``. + + +Examples +-------- + +reStructuredText source:: + + .. Hint:: It's bigger than a bread box. + +Pseudo-XML_ fragment from simple parsing:: + + <hint> + <paragraph> + It's bigger than a bread box. + + +``image`` +========= + +`To be completed`_. + + +``important`` +============= + +The ``important`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``important``. + +:Children: + ``important`` elements contain one or more `body elements`_. + +:Analogues: + ``important`` is analogous to the DocBook "important" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Important" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``important`` element contains only the `common attributes`_: id_, name_, dupname_, source_, and class_. +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``important``. The `%structure.model;`_ parameter entity + indirectly includes ``important``. + Examples -------- -reStructuredText_ source:: +reStructuredText source:: - A paragraph. + .. Important:: -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: + * Wash behind your ears. + * Clean up your room. + * Back up your data. + * Call your mother. - <document> - <decoration> - <footer> +Pseudo-XML_ fragment from simple parsing:: + + <important> + <bullet_list> + <list_item> <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. + Wash behind your ears. + <list_item> + <paragraph> + Clean up your room. + <list_item> + <paragraph> + Back up your data. + <list_item> + <paragraph> + Call your mother. -``footnote`` -============ +``interpreted`` +=============== `To be completed`_. -``footnote_reference`` -====================== +``label`` +========= `To be completed`_. -``generated`` -============= +``legend`` +========== `To be completed`_. -``header`` -========== +``line_block`` +============== -The ``header`` element is a container element whose contents are meant -to appear at the top of a web page, or at the top of every printed -page. Docutils does not yet make use of the ``header`` element. +The ``line_block`` element contains a block of text where line breaks +and whitespace are significant and must be preserved. ``line_block`` +elements are commonly used for verse and addresses. See `line_block`_ +for an alternative useful for program listings and interactive +computer sessions. Details ------- :Category: - `Decorative Elements`_ + `Simple Body Elements`_ :Parents: - Only the decoration_ element contains ``header``. + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``line_block``. :Children: - ``header`` elements may contain `body elements`_. + ``line_block`` elements may contain text data plus `inline + elements`_. :Analogues: - There are no direct analogies to ``header`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. + ``line_block`` is analogous to the DocBook "literallayout" element + and to the HTML "pre" element (with modifications to typeface + styles). + +:Processing: + Unline ``literal_block``, ``line_block`` elements are typically + rendered in an ordinary text typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. Content Model @@ -1884,59 +2464,60 @@ Content Model .. parsed-literal:: - (`%body.elements;`_)+ + `%text.model;`_ :Attributes: - The ``header`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. + The ``line_block`` element contains the `common attributes`_ (id_, + name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``line_block``. The `%structure.model;`_ parameter entity + indirectly includes ``line_block``. Examples -------- -None. - - -``hint`` -======== - -`To be completed`_. - - -``image`` -========= - -`To be completed`_. - +reStructuredText uses a directive to indicate a ``line_block``. +Example source:: -``important`` -============= - -`To be completed`_. - - -``interpreted`` -=============== + Take it away, Eric the Orchestra Leader! -`To be completed`_. + .. line-block:: + A one, two, a one two three four -``label`` -========= + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? -`To be completed`_. + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + Singing... -``legend`` -========== +Pseudo-XML_ fragment from simple parsing:: -`To be completed`_. + <paragraph> + Take it away, Eric the Orchestra Leader! + <line_block xml:space="preserve"> + A one, two, a one two three four + Half a bee, philosophically, + must, <emphasis>ipso facto</emphasis>, half not be. + But half the bee has got to be, + <emphasis>vis a vis</emphasis>its entity. D'you see? -``line_block`` -============== + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? -`To be completed`_. + Singing... ``list_item`` @@ -2020,14 +2601,140 @@ See bullet_list_ or enumerated_list_ for further examples. ``literal_block`` ================= -`To be completed`_. +The ``literal_block`` element contains a block of text where line +breaks and whitespace are significant and must be preserved. +``literal_block`` elements are commonly used for program listings and +interactive computer sessions. See `line_block`_ for an alternative +useful for verse and addresses. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``literal_block``. + +:Children: + ``literal_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``literal_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + ``literal_block`` elements are typically rendered in a monospaced + typeface. It is crucial that all whitespace and line breaks are + preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``literal_block`` element contains the `common attributes`_ + (id_, name_, dupname_, source_, and class_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``literal_block``. The `%structure.model;`_ parameter entity + indirectly includes ``literal_block``. + + +Examples +-------- + +reStructuredText source:: + + Here is a literal block:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Here is a literal block: + <literal_block xml:space="preserve"> + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None ``note`` ======== -`To be completed`_. +The ``note`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``note``. + +:Children: + ``note`` elements contain one or more `body elements`_. + +:Analogues: + ``note`` is analogous to the DocBook "note" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Note" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ +:Attributes: + The ``note`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``note``. The `%structure.model;`_ parameter entity indirectly + includes ``note``. + + +Examples +-------- + +reStructuredText source:: + + .. Note:: Admonitions can be handy to break up a + long boring technical document. + +Pseudo-XML_ fragment from simple parsing:: + + <note> + <paragraph> + Admonitions can be handy to break up a + long boring technical document. ``option`` ========== @@ -2918,7 +3625,63 @@ classifier_ elements. ``tip`` ======= -`To be completed`_. +The ``tip`` element is an admonition, a distinctive and self-contained +notice. Also see the other admonition elements Docutils offers (in +alphabetical order): attention_, caution_, danger_, error_, hint_, +important_, note_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``tip``. + +:Children: + ``tip`` elements contain one or more `body elements`_. + +:Analogues: + ``tip`` is analogous to the DocBook "tip" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Tip" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``tip`` element contains only the `common attributes`_: id_, + name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes ``tip``. + The `%structure.model;`_ parameter entity indirectly includes + ``tip``. + + +Examples +-------- + +reStructuredText source:: + + .. Tip:: 15% if the service is good. + +Pseudo-XML_ fragment from simple parsing:: + + <tip> + <paragraph> + 15% if the service is good. ``title`` @@ -3202,7 +3965,63 @@ context. ``warning`` =========== -`To be completed`_. +The ``warning`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, note_, tip_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``warning``. + +:Children: + ``warning`` elements contain one or more `body elements`_. + +:Analogues: + ``warning`` is analogous to the DocBook "warning" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Warning" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``warning`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``warning``. The `%structure.model;`_ parameter entity indirectly + includes ``warning``. + + +Examples +-------- + +reStructuredText source:: + + .. WARNING:: Reader discretion is strongly advised. + +Pseudo-XML_ fragment from simple parsing:: + + <warning> + <paragraph> + Reader discretion is strongly advised. --------------------- -- cgit v1.2.1 From a4237939cd9815ee1f487ffab293398b843a6e25 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Dec 2002 02:40:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@994 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 +++++ docs/peps/pep-0258.txt | 21 ++++++++++++++++++++- docs/ref/rst/directives.txt | 10 ++++++---- 3 files changed, 31 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 51978fcb9..d92c51ca3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -993,6 +993,9 @@ HTML Writer directives and substitutions for dynamic stuff. Or a specialized writer to generate .ht & links.h files for ht2html? +* Add a setting (or another writer) which produces just the contents + of the <body> element. Part of the ht2html implementation? + * Add more support for <link> elements, especially for navigation bars. @@ -1000,6 +1003,8 @@ HTML Writer * Make the "class" attributes optional? Implies no stylesheet? +* Add a setting to customize the header tag levels, i.e. <h1>. + Front-End Tools --------------- diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index d64110cba..000b63acb 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -713,7 +713,12 @@ conditions: b) At the top level of a class definition: a class attribute. c) At the top level of the "``__init__``" method definition of a - class: an instance attribute. (@@@ ``__new__`` methods?) + class: an instance attribute. Instance attributes assigned in + other methods are assumed to be implementation details. (@@@ + ``__new__`` methods?) + + d) A function attribute assignment at the top level of a module or + class definition. Since each of the above contexts are at the top level (i.e., in the outermost suite of a definition), it may be necessary to place @@ -734,6 +739,11 @@ conditions: method's first parameter (the instance parameter) and "attrib" is a simple identifier as in 3a. + c) For context 1d above, the target must be of the form + "``name.attrib``", where "``name``" matches an already-defined + function or method name and "attrib" is a simple identifier as + in 3a. + Blank lines may be used after attribute docstrings to emphasize the connection between the assignment and the docstring. @@ -748,9 +758,18 @@ Examples:: """This is AClass.c's docstring.""" def __init__(self): + """Method __init__'s docstring.""" + self.i = 'instance attribute' """This is self.i's docstring.""" + def f(x): + """Function f's docstring.""" + return x**2 + + f.a = 1 + """Function attribute f.a's docstring.""" + Additional Docstrings ''''''''''''''''''''' diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 1e22f7bd9..3a0449f40 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -513,11 +513,13 @@ directive. For example:: .. include:: inclusion.txt - This second will be parsed in a block quote context. - Therefore it may only contain body elements. It may not - contain section headers. + Back in the main document. - .. include:: inclusion.txt + This second example will be parsed in a block quote context. + Therefore it may only contain body elements. It may not + contain section headers. + + .. include:: inclusion.txt If an included document fragment contains section structure, the title adornments must match those of the master document. -- cgit v1.2.1 From 3b2fad8136d9ba7c4db32426eb96f62640b14323 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 7 Dec 2002 03:11:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1005 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++++ docs/ref/transforms.txt | 8 +++++--- 2 files changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index d92c51ca3..cdd2c332a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -401,6 +401,10 @@ Miscellaneous ideas: 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: pep-0258.html#additional-docstrings * Multi-file output should be divisible at arbitrary level. diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index a5564f042..7874bca3a 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -44,6 +44,8 @@ peps.TargetNotes pep (r) 520 references.TargetNotes peps.TargetNotes (t/p) 0 +misc.CallBack peps.TargetNotes (t/p) 1 + references.TargetNotes "target-notes" (d/p) 540 references.Footnotes standalone (r), pep (r) 620 @@ -68,6 +70,8 @@ universal.FinalChecks Transformer 840 universal.Messages Transformer 860 universal.TestMessages DocutilsTestSupport 890 + +misc.CallBack n/a 990 ============================== ============================ ======== Key: @@ -86,9 +90,7 @@ Transform Priority Range Categories ---------- ------------------------------------------------ From To Category ==== ==== ================================================ - 0 immediate execution (added by another transform) ----------- ------------------------------------------------ - 1 99 unused + 0 99 immediate execution (added by another transform) 100 199 very early (non-standard) 200 299 very early 300 399 early -- cgit v1.2.1 From 623794723f5a6b489d395cc4c41e9eea22818575 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 12 Dec 2002 02:48:30 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1015 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index cdd2c332a..8e957823a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,10 +45,6 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -* In docutils.transforms.peps.TargetNotes, an empty References section - is generated even if there are no references. Reported by David - Ascher. - General ------- -- cgit v1.2.1 From eb82300e688f6e452b1db58d5abadd76be56025d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 17 Dec 2002 02:25:19 +0000 Subject: Added support for backslash-escape after inline markup. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1023 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 5f7ae8ebd..d2838ac72 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2140,9 +2140,9 @@ In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary character-level markup is not supported; -it is not possible to mark up individual characters within a word. -Inline markup cannot be nested. +with whitespace. Arbitrary character-level markup is not supported +[#]_; it is not possible to mark up individual characters within a +word. Inline markup cannot be nested. There are nine inline markup constructs. Five of the constructs use identical start-strings and end-strings to indicate the markup: @@ -2243,6 +2243,18 @@ each character. The inline markup recognition order is as follows: - `Standalone hyperlinks`_ are the last to be recognized. +.. [#] Backslash escapes can be used to allow arbitrary text to + immediately follow inline markup:: + + Python ``list``\s use square bracket syntax. + + The backslash will disappear from the processed document. The word + "list" will appear as inline literal text, and the letter "s" will + immediately follow it as normal text, with no space in-between. + + There is not yet any way for arbitrary text to immediately precede + inline markup. + Emphasis -------- -- cgit v1.2.1 From ae5fd4a5e4f398a38b52b712b4a19ad8416139e3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 17 Dec 2002 02:27:26 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1024 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8e957823a..b80257866 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -464,10 +464,11 @@ __ rst/alternatives.html#or-not-to-do - Convert quotes to curly quote entities. (Essentially impossible for HTML? Unnecessary for TeX. An output issue?) - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to  . + - ``"\ "`` to  . Problem with line-wrapping though: it could + end up escaping the newline. - Escaped newlines to <BR>. - - Escaped period or quote as a disappearing catalyst to allow - character-level inline markup? + - Escaped period or quote or dash as a disappearing catalyst to + allow character-level inline markup? - Others? How to represent character entities in the text though? Probably as @@ -476,6 +477,17 @@ __ rst/alternatives.html#or-not-to-do Which component is responsible for this, the parser, the reader, or the writer? +* From David Abrahams, 15 Dec 2002 (docutils-users list): + + Would it break anything if you added the backslash to the list + of "certain punctuation characters"? That way, I could write + ``list``\s and get exactly the effect I want. + + Interesting idea. May work. I'll have to think it through. There + may be adverse side-effects due to the way backslash-escapes are + handled internally (they're converted to \x00 null bytes, which I've + always thought was a bit of a kludge, but it's worked thus far). + * 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 @@ -1005,6 +1017,9 @@ HTML Writer * Add a setting to customize the header tag levels, i.e. <h1>. +* Base list compaction on the spacing of source list? Would require + parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.) + Front-End Tools --------------- -- cgit v1.2.1 From a01ac19f851156f283ed761f0fa1320a9894374b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Dec 2002 01:08:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1033 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b80257866..5af0e9474 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -477,17 +477,6 @@ __ rst/alternatives.html#or-not-to-do Which component is responsible for this, the parser, the reader, or the writer? -* From David Abrahams, 15 Dec 2002 (docutils-users list): - - Would it break anything if you added the backslash to the list - of "certain punctuation characters"? That way, I could write - ``list``\s and get exactly the effect I want. - - Interesting idea. May work. I'll have to think it through. There - may be adverse side-effects due to the way backslash-escapes are - handled internally (they're converted to \x00 null bytes, which I've - always thought was a bit of a kludge, but it's worked thus far). - * 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 @@ -667,10 +656,17 @@ __ rst/alternatives.html#or-not-to-do .. _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? + 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? @@ -729,7 +725,7 @@ Directives - _`html.imagemap` (Useful outside of HTML? If not, replace with image only in non-HTML writers?) - - _`parts.endnotes`: See `Footnote & Citation Gathering`_. + - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_. - _`parts.citations`: See `Footnote & Citation Gathering`_. -- cgit v1.2.1 From 813520af216474ec5c97efb2b1809e38aa72b5d1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 29 Dec 2002 18:38:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1046 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.txt | 2 +- docs/dev/todo.txt | 33 ++++++++++++++++++++++++++++++--- 2 files changed, 31 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index 93fba9420..1b5e629f7 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -28,7 +28,7 @@ goes something like this: 1. Extract the docstring/namespace [#]_ tree from the module(s) and/or package(s). - .. [#] See `Docstring Extractor`_ above. + .. [#] See `Docstring Extractor`_ below. 2. Run the parser on each docstring in turn, producing a forest of doctrees (per nodes.py). diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5af0e9474..d806ce9b1 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -344,8 +344,8 @@ Specification See Doc-SIG from 2001-06-19/20. -PySource Reader ---------------- +Python Source Reader +-------------------- General: @@ -353,6 +353,8 @@ General: * Analyze Doug Hellmann's HappyDoc project. +* Investigate how POD handles literate programming. + * Take the best ideas and integrate them into Docutils 0.3. Miscellaneous ideas: @@ -378,6 +380,15 @@ Miscellaneous ideas: # 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. @@ -477,6 +488,16 @@ __ rst/alternatives.html#or-not-to-do Which component is responsible for this, the parser, the reader, or the writer? +* Idea from David Abrahams re character-level inline markup: + + I can think of one way to beautify cases like this: introduce a + kind of quotation which removes all spaces in what it surrounds + as a postprocessing step. :: + + ''*re* ``Structured`` *Text*'' + + This would be analogous to re.VERBOSE, if memory serves. + * 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 @@ -488,7 +509,8 @@ __ rst/alternatives.html#or-not-to-do * Alan Jaffray suggested (and I agree) that it would be sensible to: - - have a directive to specify a default role for interpreted text + - 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 - issue a warning when processing documents with no default role which contain interpreted text with no explicitly specified role @@ -497,6 +519,11 @@ __ rst/alternatives.html#or-not-to-do "title", as in, "title of a book". It'd be a text-only reference, no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. +* Add a directive establishing a mapping of interpreted text role + aliases? A set of default roles (index, acronym, etc.) could exist, + and the directive could assign abbreviations (i, a, etc.) or other + alternatives. + * @@ Fix the parser's indentation handling to conform with the stricter definition in the spec. (Explicit markup blocks should be strict or forgiving?) -- cgit v1.2.1 From b9469568d6a1f35e7016c6ac61b65ccb39e818c2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 3 Jan 2003 00:52:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1054 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index d806ce9b1..bb59286f6 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -414,6 +414,17 @@ Miscellaneous ideas: .. _additional docstrings: 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: @@ -507,6 +518,13 @@ __ rst/alternatives.html#or-not-to-do exposition in the spec, to make clear what is going on for people with head colds. +* @@@ Add interpreted text support code. + + Ideally and eventually, the "interpreted" element will disappear + from the Docutils doctree. In its place will be a customizable set + of inline elements including "acronym" and "index_entry", directly + created by the parser. + * Alan Jaffray suggested (and I agree) that it would be sensible to: - have a directive and/or command-line option to specify a default @@ -1015,6 +1033,15 @@ system_messages and add them to the document, perhaps to the end of the "Docutils System Messages" section. +Filtering System Messages +````````````````````````` + +Currently the Writer is responsible for filtering out system messages +that are below the current threshold. Should the filtering be in a +separate transform? It would then happen regardless of the writer +used. Perhaps some writers don't want system messages filtered? + + Others `````` -- cgit v1.2.1 From 223a5013b74c0a1eef9d183346c0115c22815e2b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 4 Jan 2003 15:02:22 +0000 Subject: added warning git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1063 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index f55f6bcea..a7b27a9ef 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -493,6 +493,11 @@ following caveats: <!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> +<!-- +WARNING: The "interpreted" element is a placeholder for testing +purposes only. Once proper parser support is in place, it will be +removed. +--> <!ELEMENT interpreted %text.model;> <!ATTLIST interpreted %basic.atts; -- cgit v1.2.1 From 0e726b1398ec735dfa2a109f4a3c152dcc7a2b9d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:15:32 +0000 Subject: Removed "interpreted" element; added "title_reference", "abbreviation", "acronym". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1081 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f55aed5f3..2045552bf 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -198,9 +198,10 @@ Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model". -Category members: citation_reference_, emphasis_, footnote_reference_, -generated_, image_, interpreted_, literal_, problematic_, reference_, -strong_, substitution_reference_, target_, raw_ +Category members: abbreviation_, acronym_, citation_reference_, +emphasis_, footnote_reference_, generated_, image_, literal_, +problematic_, reference_, strong_, substitution_reference_, target_, +title_reference_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -279,6 +280,18 @@ completed`". Please help complete this document by contributing to its writing. +``abbreviation`` +================ + +`To be completed`_. + + +``acronym`` +=========== + +`To be completed`_. + + ``address`` =========== @@ -2405,12 +2418,6 @@ Pseudo-XML_ fragment from simple parsing:: Call your mother. -``interpreted`` -=============== - -`To be completed`_. - - ``label`` ========= @@ -3745,6 +3752,12 @@ Pseudo-XML_ fragment from simple parsing:: A paragraph. +``title_reference`` +=================== + +`To be completed`_. + + ``topic`` ========= -- cgit v1.2.1 From 062a5e1abc7f92c84fff24ad40e24bf35eb167de Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:16:04 +0000 Subject: Removed "interpreted" element; added "title_reference", "abbreviation", "acronym". Removed "refuri" attribute from "footnote_reference" and "citation_reference". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1082 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index a7b27a9ef..e5bc5a46e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -129,7 +129,9 @@ resolve to either an internal or external reference. <!ENTITY % inline.elements " emphasis | strong | interpreted | literal | reference | footnote_reference | citation_reference - | substitution_reference | problematic | generated + | substitution_reference | title_reference + | abbreviation | acronym | + | problematic | generated | target | image | raw %additional.inline.elements; "> @@ -493,17 +495,6 @@ following caveats: <!ELEMENT strong %text.model;> <!ATTLIST strong %basic.atts;> -<!-- -WARNING: The "interpreted" element is a placeholder for testing -purposes only. Once proper parser support is in place, it will be -removed. ---> -<!ELEMENT interpreted %text.model;> -<!ATTLIST interpreted - %basic.atts; - role NMTOKEN #IMPLIED - position (prefix | suffix) #IMPLIED> - <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> @@ -516,19 +507,30 @@ removed. <!ELEMENT footnote_reference (#PCDATA)> <!ATTLIST footnote_reference %basic.atts; - %reference.atts; + %refid.att; + %refname.att; %auto.att;> <!ELEMENT citation_reference (#PCDATA)> <!ATTLIST citation_reference %basic.atts; - %reference.atts;> + %refid.att; + %refname.att;> <!ELEMENT substitution_reference %text.model;> <!ATTLIST substitution_reference %basic.atts; %refname.att;> +<!ELEMENT title_reference %text.model;> +<!ATTLIST title_reference %basic.atts;> + +<!ELEMENT abbreviation %text.model;> +<!ATTLIST abbreviation %basic.atts;> + +<!ELEMENT acronym %text.model;> +<!ATTLIST acronym %basic.atts;> + <!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; -- cgit v1.2.1 From cc6a449e7af1e41d7bf57febd81a8cb1860db2ff Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:17:15 +0000 Subject: Added ideas for interpreted text syntax extensions. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1083 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 55 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 7fd7d6704..b36ec2e14 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -180,6 +180,60 @@ email mode, where we may be able to rely on less complex structure (few nested lists, for example). +Multiple Roles in Interpreted Text +---------------------------------- + +In reStructuredText, inline markup cannot be nested. This also +applies to interpreted text. In order to simultaneously combine +multiple roles for a single piece of text, a syntax extension would be +necessary. Ideas: + +1. Initial idea:: + + `interpreted text`:role1,role2: + +2. Suggested by Jason Diamond:: + + `interpreted text`:role1:role2: + +If a document is so complex as to require nested inline markup, +perhaps another markup system should be considered. By design, +reStructuredText does not have the flexibility of XML. + + +Parameterized Interpreted Text +------------------------------ + +In some cases it may be expedient to pass parameters to interpreted +text roles, analogous to function calls. Ideas: + +1. Suggested by Jason Diamond:: + + `interpreted text`:role1(foo=bar): + + Positional parameters could also be supported:: + + `CSS`:acronym(Cascading Style Sheets): is used for HTML, and + `CSS`:acronym(Content Scrambling System): is used for DVDs. + + Problem: current interpreted text syntax does not recognize roles + containing whitespace. + +This pushes inline markup too far; readability becomes a serious +issue. Substitutions may provide a better alternative by pulling the +details out of the text flow:: + + |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. + + .. |CSS| acronym:: Cascading Style Sheets + .. |CSS-DVD| acronym:: Content Scrambling System + :text: CSS + +This is going beyond the scope of reStructuredText though. Documents +requiring this functionality may be better off using XML or another +markup system. + + Field Lists =========== @@ -1748,6 +1802,7 @@ Solution 3 was chosen for incorporation into the document tree model. .. _HTML: http://www.w3.org/MarkUp/ + .. Local Variables: -- cgit v1.2.1 From 864c13ae2445706b95d038fa0b856293bf30a4e5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:18:05 +0000 Subject: Updated "Interpreted Text" section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1084 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 52 ++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 28 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d2838ac72..e99e31767 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2287,42 +2287,39 @@ Strongly emphasized text is typically displayed in boldface. Interpreted Text ---------------- -DTD element: interpreted. +DTD element: depends on the explicit or implicit role and processing. Start-string = end-string = "`". -Text enclosed by single backquote characters is interpreted:: +Interpreted text is text that is meant to be related, indexed, linked, +summarized, or otherwise processed, but the text itself is typically +left alone. Interpreted text is enclosed by single backquote +characters:: This is `interpreted text`. -Interpreted text is text that is meant to be related, indexed, linked, -summarized, or otherwise processed, but the text itself is left -alone. The text is "tagged" directly, in-place. The semantics of -interpreted text are domain-dependent. It can be used as implicit or -explicit descriptive markup (such as for program identifiers, as in -the `Python Source Reader`_), for cross-reference interpretation (such -as index entries), or for other applications where context can be -inferred. - -The role of the interpreted text determines how the text is -interpreted. It is normally inferred implicitly. The role of the -interpreted text may also be indicated explicitly, using a role -marker, either as a prefix or as a suffix to the interpreted text, -depending on which reads better:: +The "role" of the interpreted text determines how the text is +interpreted. The role may be inferred implicitly (as above; the +"default role" is used) or indicated explicitly, using a role marker. +A role marker consists of a colon, the role name, and another colon. +A role name is a single word consisting of alphanumerics plus internal +hyphens, underscores, and periods; no whitespace or other characters +are allowed. A role marker is either a prefix or a suffix to the +interpreted text, whichever reads better; it's up to the author:: :role:`interpreted text` `interpreted text`:role: -Roles are simply extensions of the available inline constructs; to -emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink -references`_, we can add "index entry", "acronym", "class", "red", -"blinking" or anything else we want. - -A role marker consists of a colon, the role name, and another colon. -A role name is a single word consisting of alphanumerics plus internal -hyphens, underscores, and periods; no whitespace or other characters -are allowed. +Interpreted text allows extensions to the available inline descriptive +markup constructs. To emphasis_, `strong emphasis`_, `inline +literals`_, and `hyperlink references`_, we can add "title reference", +"index entry", "acronym", "class", "red", "blinking" or anything else +we want. Only pre-determined roles are recognized; unknown roles will +generate errors. A core set of standard roles is implemented in the +reference parser; see `reStructuredText Interpreted Text Roles`_ for +individual descriptions. In addition, applications may support +specialized roles. Inline Literals @@ -2536,7 +2533,7 @@ Examples:: Standalone Hyperlinks --------------------- -DTD element: link. +DTD element: reference. Start-string = end-string = "" (empty string). @@ -2630,8 +2627,7 @@ Markup errors are handled according to the specification in `PEP .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _reStructuredText Directives: directives.html -.. _Python Source Reader: - http://docutils.sourceforge.net/spec/pysource.txt +.. _reStructuredText Interpreted Text Roles: interpreted.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -- cgit v1.2.1 From 798975af17442e34055e6cc48b807afea4a9213d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:19:01 +0000 Subject: Descriptions of interpreted text roles. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1085 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/ref/rst/roles.txt (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt new file mode 100644 index 000000000..64045b36d --- /dev/null +++ b/docs/ref/rst/roles.txt @@ -0,0 +1,84 @@ +========================================= + reStructuredText Interpreted Text Roles +========================================= +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +This document describes the interpreted text roles implemented in the +reference reStructuredText parser. + +Interpreted text uses backquotes (`) around the text. An explicit +role marker may optionally appear before or after the text, delimited +with colons. For example:: + + This is `interpreted text` using the default role. + + This is :title:`interpreted text` using an explicit role. + +A default role may be defined by applications of reStructuredText; it +is used if no explicit ``:role:`` prefix or suffix is given. The +"default default role" is `:title-reference:`_. + +See the `Interpreted Text`__ section in the `reStructuredText Markup +Specification`_ for syntax details. + +.. _Interpreted Text: ./reStructuredText.html#interpreted-text +.. _reStructuredText Markup Specification: ./reStructuredText.html + + +.. contents:: + + +``:pep-reference:`` +=================== + +:Aliases: ``:PEP:`` +:DTD Element: reference + +The ``:pep-reference:`` role is used to create an HTTP reference to a +PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually +used. For example:: + + See :PEP:`287` for more information about reStructuredText. + +This is equivalent to:: + + See `PEP 287`__ for more information about reStructuredText. + + __ http://www.python.org/peps/pep-0287.html + + +``:rfc-reference:`` +=================== + +:Aliases: ``:RFC:`` +:DTD Element: reference + +The ``:rfc-reference:`` role is used to create an HTTP reference to an +RFC (Internet Request for Comments). The ``:RFC:`` alias is usually +used. For example:: + + See :RFC:`2822` for information about email headers. + +This is equivalent to:: + + See `RFC 2822`__ for information about email headers. + + __ http://www.faqs.org/rfcs/rfc2822.html + + +``:title-reference:`` +===================== + +:Aliases: ``:title:``, ``:t:``. +:DTD Element: title_reference + +The ``:title-reference:`` role is used to describe the titles of +books, periodicals, and other materials. + +``:title-reference:`` is the default role in the standard +reStructuredText parser. This means that no explicit role is +required. Applications of reStructuredText may designate a different +default role, in which case the explicit role must be used. -- cgit v1.2.1 From 13681f75fbe4e198808988aa4dc962524e89fbcf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:25:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1090 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.txt | 41 ---------------- docs/dev/todo.txt | 125 +++++++++++++++++++++++++++++++++++++++---------- docs/peps/pep-0258.txt | 2 +- docs/user/tools.txt | 6 ++- 4 files changed, 106 insertions(+), 68 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index 1b5e629f7..e1df7fb52 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -105,47 +105,6 @@ DTD elements: package, module, class, method, function, module_attribute, class_attribute, instance_attribute, variable, parameter, type, exception_class, warning_class. -In Python docstrings, interpreted text is used to classify and mark up -program identifiers, such as the names of variables, functions, -classes, and modules. If the identifier alone is given, its role is -inferred implicitly according to the Python namespace lookup rules. -For functions and methods (even when dynamically assigned), -parentheses ('()') may be included:: - - This function uses `another()` to do its work. - -For class, instance and module attributes, dotted identifiers are used -when necessary:: - - class Keeper(Storer): - - """ - Extend `Storer`. Class attribute `instances` keeps track of - the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of instances. - - Keep count in `self.instances` and data in `self.data`. - """ - Storer.__init__(self) - self.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def storedata(self, data): - """ - Extend `Storer.storedata()`; append new `data` to a list - (in `self.data`). - """ - self.data = data - To classify identifiers explicitly, the role is given along with the identifier in either prefix or suffix form:: diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bb59286f6..bdfc5847e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -90,7 +90,8 @@ General .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. -* Add object numbering and object references (tables & figures). +* 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 @@ -155,6 +156,8 @@ General 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. @@ -518,30 +521,6 @@ __ rst/alternatives.html#or-not-to-do exposition in the spec, to make clear what is going on for people with head colds. -* @@@ Add interpreted text support code. - - Ideally and eventually, the "interpreted" element will disappear - from the Docutils doctree. In its place will be a customizable set - of inline elements including "acronym" and "index_entry", directly - created by the parser. - -* 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 - - issue a warning when processing documents with no default role - which contain interpreted text with no explicitly specified role - -* Perhaps the default implicit role for interpreted text could be - "title", as in, "title of a book". It'd be a text-only reference, - no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. - -* Add a directive establishing a mapping of interpreted text role - aliases? A set of default roles (index, acronym, etc.) could exist, - and the directive could assign abbreviations (i, a, etc.) or other - alternatives. - * @@ Fix the parser's indentation handling to conform with the stricter definition in the spec. (Explicit markup blocks should be strict or forgiving?) @@ -720,6 +699,9 @@ when used in a document. - _`images.image`: "border"? + - _`images.figure`: "title" and "number", to indicate a formal + figure? + - _`parts.sectnum`: "start", "local"? A "local" option could enable numbering for sections from a @@ -967,6 +949,95 @@ when used in a document. 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 be known by the Parser. +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 +spec/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. + +* @@@ Add interpreted text support code. + + Ideally and eventually, the "interpreted" element will disappear + from the Docutils doctree. In its place will be a customizable set + of inline elements including "acronym" and "index_entry", directly + created by the parser. + +* Add a test for language mappings. + +* 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) + +* Perhaps the default implicit role for interpreted text could be + "title", as in, "title of a book". It'd be a text-only reference, + no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. (Done) + +* Add a directive establishing a mapping of interpreted text role + aliases? A set of default roles (index, acronym, etc.) could exist, + and the directive could assign abbreviations (i, a, etc.) or other + alternatives. + +* Explicitly add inline markup roles (emphasis, strong, literal) to + the built-in list of interpreted text roles? Useful for + completeness, and potentially useful if `multiple roles`_ ever + become possible. + + .. _multiple roles: + rst/alternatives.html#multiple-roles-in-interpreted-text + +* 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. + + What to do with an undefined acronym or abbreviation? + + - "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. + + Unimplemented Transforms ------------------------ @@ -1118,6 +1189,10 @@ Front-End Tools * 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. Alternatively, create a single dynamic_ or + unqualified_ front end that can be installed. + Project Policies ================ diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 000b63acb..c984cd0ad 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -186,7 +186,7 @@ attached to every new document tree. The Publisher_ calls ``Transformer.apply_transforms()`` to apply all stored transforms to the document tree. Transforms change the document tree from one form to another, add to the tree, or prune it. Transforms resolve -references and footnote numbers, processing interpreted text, and do +references and footnote numbers, process interpreted text, and do other context-sensitive processing. Some transforms are specific to components (Readers, Parser, Writers, diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 11748a4e5..882e5a26b 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -352,10 +352,14 @@ config Path to a configuration file to read (if it Default: None. Options: ``--config``. -------------------- ------------------------------------------------ datestamp Include a time/datestamp in the document footer. - Contains a format string for ``time.strftime``. + Contains a format string for Python's + ``time.strftime``. See the `time module + documentation`__. Default: None. Options: ``--date, -d, --time, -t, --no-datestamp``. + + __ http://www.python.org/doc/current/lib/module-time.html -------------------- ------------------------------------------------ debug Report debug-level system messages. -- cgit v1.2.1 From c73dcd6968b586e767c9dab66a226f52f1260680 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:39:46 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1091 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 64045b36d..d3e1a7494 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -21,7 +21,7 @@ A default role may be defined by applications of reStructuredText; it is used if no explicit ``:role:`` prefix or suffix is given. The "default default role" is `:title-reference:`_. -See the `Interpreted Text`__ section in the `reStructuredText Markup +See the `Interpreted Text`_ section in the `reStructuredText Markup Specification`_ for syntax details. .. _Interpreted Text: ./reStructuredText.html#interpreted-text -- cgit v1.2.1 From 432dee48981911f7c4803fea7aac37aaa6218f1d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 10 Jan 2003 02:44:30 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 29 ++++++++++++++++------------- docs/ref/docutils.dtd | 6 +++--- 2 files changed, 19 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 2045552bf..3ee68f9d5 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4447,9 +4447,11 @@ Entity definition: .. parsed-literal:: - emphasis_ | strong_ | interpreted_ | literal_ + emphasis_ | strong_ | literal_ | reference_ | footnote_reference_ | citation_reference_ - | substitution_reference_ | problematic_ | generated_ + | substitution_reference_ | title_reference_ + | abbreviation_ | acronym_ + | problematic_ | generated_ | target_ | image_ | raw_ %additional.inline.elements; @@ -4458,11 +4460,12 @@ wrapper DTDs to extend ``%inline.elements;``. Via `%text.model;`_, the ``%inline.elements;`` parameter entity is indirectly employed in the content models of the following elements: -address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, generated_, interpreted_, line_block_, -literal_block_, organization_, paragraph_, problematic_, raw_, -reference_, revision_, status_, strong_, substitution_definition_, -substitution_reference_, subtitle_, target_, term_, title_, version_ +abbreviation_, acronym_, address_, author_, caption_, classifier_, +contact_, copyright_, date_, doctest_block_, emphasis_, generated_, +line_block_, literal_block_, organization_, paragraph_, problematic_, +raw_, reference_, revision_, status_, strong_, +substitution_definition_, substitution_reference_, subtitle_, target_, +term_, title_, version_ ``%reference.atts;`` @@ -4613,12 +4616,12 @@ Entity definition: (#PCDATA | `%inline.elements;`_)* The ``%text.model;`` parameter entity is directly employed in the -content models of the following elements: address_, author_, caption_, -classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, -generated_, interpreted_, line_block_, literal_block_, organization_, -paragraph_, problematic_, raw_, reference_, revision_, status_, -strong_, substitution_definition_, substitution_reference_, subtitle_, -target_, term_, title_, version_ +content models of the following elements: abbreviation_, acronym_, +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, generated_, line_block_, literal_block_, +organization_, paragraph_, problematic_, raw_, reference_, revision_, +status_, strong_, substitution_definition_, substitution_reference_, +subtitle_, target_, term_, title_, version_ diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index e5bc5a46e..03a003b62 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -127,11 +127,11 @@ resolve to either an internal or external reference. <!ENTITY % additional.inline.elements ""> <!ENTITY % inline.elements - " emphasis | strong | interpreted | literal + " emphasis | strong | literal | reference | footnote_reference | citation_reference | substitution_reference | title_reference - | abbreviation | acronym | - | problematic | generated + | abbreviation | acronym + | problematic | generated | target | image | raw %additional.inline.elements; "> -- cgit v1.2.1 From 16979155f8d713326c1a9d5887372c7366196d7c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 Jan 2003 00:59:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1095 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 15 ++++++++++++++- docs/ref/rst/roles.txt | 29 ++++++++++++++++++++++++++--- 2 files changed, 40 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bdfc5847e..be338cfef 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -977,7 +977,7 @@ 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. -* @@@ Add interpreted text support code. +* Add interpreted text support code. (Done) Ideally and eventually, the "interpreted" element will disappear from the Docutils doctree. In its place will be a customizable set @@ -1505,6 +1505,19 @@ Release Checklist + web: index.txt +* Run the test suite: ``cd test ; alltests.py``. + +* Create the release tarball. (@@@ Expand this.) + +* Expand and install the release tarball in isolation (no PYTHONPATH, + clear out old installation, etc.). + +* Run the test suite from the expanded archive directory: ``cd test ; + alltests.py``. + +* Run ``cd tools ; buildhtml.py ..`` to confirm that there are no + major problems with the docs. + .. Local Variables: diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d3e1a7494..7b5e80b0a 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -76,9 +76,32 @@ This is equivalent to:: :DTD Element: title_reference The ``:title-reference:`` role is used to describe the titles of -books, periodicals, and other materials. +books, periodicals, and other materials. It is the equivalent of the +HTML "cite" element. Since title references are typically rendered +with italics, they are often marked up using ``*emphasis*``, which is +misleading and vague. The "title_reference" element provides accurate +and unambiguous descriptive markup. -``:title-reference:`` is the default role in the standard -reStructuredText parser. This means that no explicit role is +Let's assume ``:title-reference:`` is the default interpreted text +role (see below) for this example:: + + `Design Patterns` [GoF95]_ is an excellent read. + +The following document fragment (pseudo-XML_) will result from +processing:: + + <paragraph> + <title_reference> + Design Patterns + + <citation_reference refname="gof95"> + GoF95 + is an excellent read. + +``:title-reference:`` is the default interpreted text role in the +standard reStructuredText parser. This means that no explicit role is required. Applications of reStructuredText may designate a different default role, in which case the explicit role must be used. + + +.. _pseudo-XML: ../doctree.html#pseudo-xml -- cgit v1.2.1 From b203fb8fd7596191d692918697927f91fe3afe16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 11 Jan 2003 22:39:52 +0000 Subject: clarified git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1130 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 11 +++++++---- docs/user/tools.txt | 3 ++- 2 files changed, 9 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 7b5e80b0a..9a720eff0 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -77,10 +77,13 @@ This is equivalent to:: The ``:title-reference:`` role is used to describe the titles of books, periodicals, and other materials. It is the equivalent of the -HTML "cite" element. Since title references are typically rendered -with italics, they are often marked up using ``*emphasis*``, which is -misleading and vague. The "title_reference" element provides accurate -and unambiguous descriptive markup. +HTML "cite" element, and it is expected that HTML writers will +typically render "title_reference" elements using "cite". + +Since title references are typically rendered with italics, they are +often marked up using ``*emphasis*``, which is misleading and vague. +The "title_reference" element provides accurate and unambiguous +descriptive markup. Let's assume ``:title-reference:`` is the default interpreted text role (see below) for this example:: diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 882e5a26b..63f597ddd 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -546,7 +546,8 @@ source_url An explicit URL for a "View document source" Options: ``--source-uri, --no-source-link``. -------------------- ------------------------------------------------ stylesheet (HTML Writer.) CSS stylesheet URL, used - verbatim. + verbatim. Overridden by "stylesheet_path" URL + option (``--stylesheet-path``). Default: "default.css". Options: ``--stylesheet``. -- cgit v1.2.1 From ef4490e4ef04122123ffad9fe83accc867e0a5ed Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 21 Jan 2003 18:32:31 +0000 Subject: clarified section title adornment styles & doc title git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1152 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 +++++--- docs/user/rst/quickstart.txt | 39 ++++++++++++++++++++++++++++++++------- 2 files changed, 37 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e99e31767..eb58100ce 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -447,15 +447,17 @@ Sections DTD elements: section, title. Sections are identified through their titles, which are marked up with -adornment: "underlines" below the title text, and, in some cases, +adornment: "underlines" below the title text, or underlines and matching "overlines" above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character [#]_. When an overline is used, the length and character used must match the -underline. There may be any number of levels of section titles, -although some output formats may have limits (HTML has 6 levels). +underline. Underline-only adornment styles are distinct from +overline-and-underline styles that use the same character. There may +be any number of levels of section titles, although some output +formats may have limits (HTML has 6 levels). .. [#] The following are all valid section title adornment characters:: diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index 5426e9c93..a810cd878 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -246,13 +246,15 @@ Sections __ quickref.html#section-structure To break longer text up into sections, you use **section headers**. -These are a single line of text (one or more words) with an underline -(and optionally an overline) in dashes "``-----``", equals -"``======``", tildes "``~~~~~~``" or any of the non-alphanumeric -characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable -with. The underline/overline must be at least as long as the title -text. Be consistent though, since all sections marked with the same -underline style are deemed to be at the same level:: +These are a single line of text (one or more words) with adornment: an +underline alone, or an overline and an overline together, in dashes +"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the +non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you +feel comfortable with. An underline-only adornment is distinct from +an overline-and-underline adornment using the same character. The +underline/overline must be at least as long as the title text. Be +consistent, since all sections marked with the same adornment style +are deemed to be at the same level:: Chapter 1 Title =============== @@ -299,6 +301,29 @@ their name. To link to the Lists_ heading, I write "``Lists_``". If the heading has a space in it like `text styles`_, we need to quote the heading "```text styles`_``". +To indicate the document title, use a unique adornment style at the +beginning of the document. To indicate the document subtitle, use +another unique adornment style immediately after the document title. +For example:: + + ================ + Document Title + ================ + ---------- + Subtitle + ---------- + + Section Title + ============= + + ... + +Note that "Document Title" and "Section Title" both use equals signs, +but are distict and unrelated styles. The text of +overline-and-underlined titles (but not underlined-only) may be inset +for aesthetics. + + Images ------ -- cgit v1.2.1 From 76a8bdd027af6103076ae78b50ab5e9f64320153 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 21 Jan 2003 18:32:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1153 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 53 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index be338cfef..7e96ea7be 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -298,7 +298,7 @@ General * Should I/O objects be passed simple encoding name strings instead of a full-blown settings object? Yes. - + @@@ Remove "settings" parameters before next release. @@ -683,6 +683,22 @@ __ rst/alternatives.html#or-not-to-do * 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? + Directives `````````` @@ -702,7 +718,7 @@ when used in a document. - _`images.figure`: "title" and "number", to indicate a formal figure? - - _`parts.sectnum`: "start", "local"? + - _`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 @@ -737,6 +753,12 @@ when used in a document. "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? 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"? @@ -1037,6 +1059,22 @@ elements. - "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 ------------------------ @@ -1075,13 +1113,18 @@ 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. References will -have to be adjusted. +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 "split here" attribute into the root element of each +split-out document, containing the path/filename. The Output object +will recognize this attribute and split out the files accordingly. +Must allow for common headers & footers, prev/next, breadcrumbs, etc. + Navigation `````````` -- cgit v1.2.1 From b6d57c3187a39759e8ed4621b9bcd9548266eda0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 3 Feb 2003 19:30:02 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7e96ea7be..c62ba5a61 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -301,6 +301,9 @@ General @@@ Remove "settings" parameters before next release. +* Change the "class" attribute of elements (set with + Element.set_class) to a list? + Documentation ------------- @@ -1184,6 +1187,9 @@ HTML Writer * 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. + Front-End Tools --------------- -- cgit v1.2.1 From 1fe7b9635381043c5ad87bf651e155a8cc983e21 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 19 Feb 2003 17:23:12 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1189 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3a0449f40..9cd173714 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -218,7 +218,7 @@ The directive's sole argument is interpreted as the topic title; the next line must be blank. All subsequent lines make up the topic body, interpreted as body elements. For example:: - topic:: Topic Title + .. topic:: Topic Title Subsequent indented lines comprise the body of the topic, and are -- cgit v1.2.1 From 9d4fcb00e8f6023b8ab16b20679198ffbd1acf45 Mon Sep 17 00:00:00 2001 From: pobrien <pobrien@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 14:19:55 +0000 Subject: Added sidebar directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 7 +++++-- docs/ref/rst/directives.txt | 28 ++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 03a003b62..8edc5f040 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -140,8 +140,8 @@ resolve to either an internal or external reference. ================================================================== --> <!ENTITY % structure.model - " ( ( (%body.elements; | topic)+, - (transition, (%body.elements; | topic)+ )*, + " ( ( (%body.elements; | topic | sidebar)+, + (transition, (%body.elements; | topic | sidebar)+ )*, (%section.elements;)* ) | (%section.elements;)+ ) "> @@ -265,6 +265,9 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT section (title, %structure.model;)> <!ATTLIST section %basic.atts;> +<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> +<!ATTLIST sidebar %basic.atts;> + <!ELEMENT topic (title?, (%body.elements;)+)> <!ATTLIST topic %basic.atts;> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9cd173714..bdbd53e83 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -199,6 +199,34 @@ legend. To specify a legend without a caption, use an empty comment Body Elements --------------- +Sidebar +======= + +:Directive Type: "sidebar" +:DTD Element: sidebar +:Directive Arguments: One, required (sidebar title). +:Directive Options: Possible; optional subtitle. +:Directive Content: Interpreted as the sidebar body. + +A sidebar is like a block quote with a title, or a self-contained +section with no subsections. Use the "sidebar" directive to indicate a +self-contained idea that is separate from the flow of the document. +Sidebars may occur anywhere a section or transition may occur. Body +elements (including sidebars) may not contain nested sidebars. + +The directive's sole argument is interpreted as the sidebar title, +which may be followed by an optional subtitle; the next line must be +blank. All subsequent lines make up the sidebar body, interpreted as +body elements. For example:: + + .. sidebar:: Sidebar Title + :subtitle: Optional Sidebar Subtitle + + Subsequent indented lines comprise + the body of the sidebar, and are + interpreted as body elements. + + Topic ===== -- cgit v1.2.1 From 585c1818730f3d4cc3551839459ffc730fd6f914 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 14:34:36 +0000 Subject: tweak git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1195 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index eb58100ce..6f260e180 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -467,7 +467,7 @@ formats may have limits (HTML has 6 levels). Some characters are more suitable than others. The following are recommended:: - = - ` : ' " ~ ^ _ * + # < > + = - ` : . ' " ~ ^ _ * + # Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. -- cgit v1.2.1 From 813c817e2696f9eba43e10cd147ba4a04244a1d1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 22:35:49 +0000 Subject: sidebar improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1196 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 112 ++++++++++++++++++++++++++++++++++++++------ docs/ref/docutils.dtd | 6 +-- docs/ref/rst/directives.txt | 65 ++++++++++++++----------- 3 files changed, 138 insertions(+), 45 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 3ee68f9d5..b97c71b7d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -102,7 +102,7 @@ directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements. -Category members: document_, section_, topic_ +Category members: document_, section_, topic_, sidebar_ Structural Subelements @@ -3321,7 +3321,7 @@ Details :Children: ``section`` elements begin with a title_, and may contain `body - elements`_ and transition_ and topic_ elements. + elements`_ as well as transition_, topic_, and sidebar_ elements. :Analogues: ``section`` is analogous to DocBook recursive "section" elements, @@ -3395,6 +3395,89 @@ Complete pseudo-XML_ result after parsing:: Paragraph 4. +``sidebar`` +========= + +Sidebars are like miniature, parallel documents that occur inside +other documents, providing related or reference material. A +``sidebar`` is typically offset by a border and "floats" to the side +of the page; the document's main text may flow around it. Sidebars +can also be likened to super-footnotes; their content is outside of +the flow of the document's main text. + +The ``sidebar`` element is a nonrecursive section_-like construct +which may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``sidebar`` elements +cannot nest inside body elements, so you can't have a ``sidebar`` +inside a ``table`` or a ``list``, or inside another ``sidebar`` (or +topic_). + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``sidebar``: document_, + section_ + +:Children: + ``sidebar`` elements begin with a title_ and an optional subtitle_ + and contain `body elements`_. + +:Analogues: + ``sidebar`` is analogous to the DocBook "sidebar" element. + +:Processing: + A ``sidebar`` element should be set off from the rest of the + document somehow, typically with a border. Sidebars typically + "float" to the side of the page and the document's main text flows + around them. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, subtitle_?, + (`%body.elements;`_)+) + +:Attributes: + The ``sidebar`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``sidebar``. + + +Examples +-------- + +The `"sidebar" directive`_ is used to create a ``sidebar`` element. +reStructuredText_ source:: + + .. sidebar:: Title + :subtitle: If Desired + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <sidebar> + <title> + Title + <subtitle> + If Desired + <paragraph> + Body. + +.. _"sidebar" directive: rst/directives.html#sidebar + + ``status`` ========== @@ -3491,7 +3574,7 @@ Details `Structural Subelements`_ :Parents: - Only the document_ element contains ``subtitle``. + The document_ and sidebar_ elements may contain ``subtitle``. :Children: ``subtitle`` elements may contain text data plus `inline @@ -3694,8 +3777,8 @@ Pseudo-XML_ fragment from simple parsing:: ``title`` ========= -The ``title`` element stores the title of a document_, section_, or -topic_. +The ``title`` element stores the title of a document_, section_, +topic_, or sidebar_. Details @@ -3706,7 +3789,7 @@ Details :Parents: The following elements may contain ``title``: document_, section_, - topic_ + topic_, sidebar_ :Children: ``title`` elements may contain text data plus `inline elements`_. @@ -3765,7 +3848,7 @@ The ``topic`` element is a nonrecursive section_-like construct which may occur at the top level of a section_ wherever a body element (list, table, etc.) is allowed. In other words, ``topic`` elements cannot nest inside body elements, so you can't have a ``topic`` inside -a ``table`` or a ``list``, or inside another ``topic``. +a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_). Details @@ -4412,7 +4495,8 @@ The ``%body.elements;`` parameter entity is directly employed in the content models of the following elements: attention_, block_quote_, caution_, citation_, danger_, definition_, description_, entry_, error_, field_body_, footer_, footnote_, header_, hint_, important_, -legend_, list_item_, note_, system_message_, tip_, topic_, warning_ +legend_, list_item_, note_, sidebar_, system_message_, tip_, topic_, +warning_ Via `%structure.model;`_, the ``%body.elements;`` parameter entity is indirectly employed in the content models of the document_ and @@ -4584,17 +4668,17 @@ Entity definition: .. parsed-literal:: - ( ( (`%body.elements;`_ | topic_)+, - (transition_, (`%body.elements;`_ | topic_)+ )*, + ( ( (`%body.elements;`_ | topic_ | sidebar_)+, + (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, (`%section.elements;`_)* ) | (`%section.elements;`_)+ ) Each document_ or section_ contains either: -- multiple body elements and/or topics, optionally interspersed with - transitions (but transitions cannot occur at the beginning or end, - nor may there be two transitions in a row), followed by zero or more - sections; or +- multiple body elements, topics, and/or sidebars, optionally + interspersed with transitions (but transitions cannot occur at the + beginning or end, nor may there be two transitions in a row), + followed by zero or more sections; or - one or more sections (whose contents are recursively the same as this model). diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 8edc5f040..5c8857ae9 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -265,12 +265,12 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT section (title, %structure.model;)> <!ATTLIST section %basic.atts;> -<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> -<!ATTLIST sidebar %basic.atts;> - <!ELEMENT topic (title?, (%body.elements;)+)> <!ATTLIST topic %basic.atts;> +<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> +<!ATTLIST sidebar %basic.atts;> + <!ELEMENT transition EMPTY> <!ATTLIST transition %basic.atts;> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index bdbd53e83..ba93d7da0 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -199,34 +199,6 @@ legend. To specify a legend without a caption, use an empty comment Body Elements --------------- -Sidebar -======= - -:Directive Type: "sidebar" -:DTD Element: sidebar -:Directive Arguments: One, required (sidebar title). -:Directive Options: Possible; optional subtitle. -:Directive Content: Interpreted as the sidebar body. - -A sidebar is like a block quote with a title, or a self-contained -section with no subsections. Use the "sidebar" directive to indicate a -self-contained idea that is separate from the flow of the document. -Sidebars may occur anywhere a section or transition may occur. Body -elements (including sidebars) may not contain nested sidebars. - -The directive's sole argument is interpreted as the sidebar title, -which may be followed by an optional subtitle; the next line must be -blank. All subsequent lines make up the sidebar body, interpreted as -body elements. For example:: - - .. sidebar:: Sidebar Title - :subtitle: Optional Sidebar Subtitle - - Subsequent indented lines comprise - the body of the sidebar, and are - interpreted as body elements. - - Topic ===== @@ -253,6 +225,43 @@ interpreted as body elements. For example:: interpreted as body elements. +Sidebar +======= + +:Directive Type: "sidebar" +:DTD Element: sidebar +:Directive Arguments: One, required (sidebar title). +:Directive Options: Possible; optional subtitle. +:Directive Content: Interpreted as the sidebar body. + +Sidebars are like miniature, parallel documents that occur inside +other documents, providing related or reference material. A sidebar +is typically offset by a border and "floats" to the side of the page; +the document's main text may flow around it. Sidebars can also be +likened to super-footnotes; their content is outside of the flow of +the document's main text. + +Sidebars may occur anywhere a section or transition may occur. Body +elements (including sidebars) may not contain nested sidebars. + +The directive's sole argument is interpreted as the sidebar title, +which may be followed by a subtitle option (see below); the next line +must be blank. All subsequent lines make up the sidebar body, +interpreted as body elements. For example:: + + .. sidebar:: Sidebar Title + :subtitle: Optional Sidebar Subtitle + + Subsequent indented lines comprise + the body of the sidebar, and are + interpreted as body elements. + +The following option is recognized: + +``subtitle`` : text + The sidebar's subtitle. + + Line Block ========== -- cgit v1.2.1 From d256fff9547aa9bb1fde01c5c495243df35157f2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 20 Feb 2003 22:44:31 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1197 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index b97c71b7d..baa45d04e 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -3396,7 +3396,7 @@ Complete pseudo-XML_ result after parsing:: ``sidebar`` -========= +=========== Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. A -- cgit v1.2.1 From cb00118e698eeebcb601543046d5023d33fa8046 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 24 Feb 2003 14:20:02 +0000 Subject: + moved latex writer into main line. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1202 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 63f597ddd..a6b5e9385 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -190,6 +190,31 @@ Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt files. If no arguments are given, all files of the form "``pep-*.txt``" are processed. +rst2latex.py +------------ + +:Reader: Standalone +:Parser: reStructuredText +:Writer: LaTeX2e + +The ``rst2laetx.py`` front end reads standalone reStructuredText source +files and produces LaTeX2e output. For example, to process a reStructuredText file +"``test.txt``" into LaTeX:: + + rst2latex.py test.txt test.tex + +The output file "``test.tex``" should then be processed with ``latex`` or +``pdflatex`` to get a typeset document. + +Some limitations and difference apply: + +- Gif,jpg or png images are not handled, when processed with ``latex``, use + ``pdflatex`` instead. +- Only Latin-1 is tested up to now. +- The generated file includes a file ``style.tex``, which allows the inclusion + of special packages or changes to settings made in the header. +- Not all constructs e.g. multirow/multicoumn entries in tables are possible. + docutils-xml.py --------------- @@ -237,6 +262,7 @@ document. Various forms output are possible: - Raw native XML (with or without a stylesheet reference) + Customization ============= -- cgit v1.2.1 From 3cf105681c70001de69a7bc12e5d77dee6329e61 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 22 Mar 2003 06:02:17 +0000 Subject: support & docs for character-level inline markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1226 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 59 ++++++++++++++++++++++++++------------- docs/user/rst/quickref.html | 11 ++++---- 2 files changed, 46 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 6f260e180..819d05d3f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -343,12 +343,16 @@ mechanism to override the default meaning of the characters used for the markup. In reStructuredText we use the backslash, commonly used as an escaping character in other domains. -A backslash followed by any character escapes that character. The -escaped character represents the character itself, and is prevented -from playing a role in any markup interpretation. The backslash is -removed from the output. A literal backslash is represented by two -backslashes in a row (the first backslash "escapes" the second, -preventing it being interpreted in an "escaping" role). +A backslash followed by any character (except whitespace characters) +escapes that character. The escaped character represents the +character itself, and is prevented from playing a role in any markup +interpretation. The backslash is removed from the output. A literal +backslash is represented by two backslashes in a row (the first +backslash "escapes" the second, preventing it being interpreted in an +"escaping" role). + +Backslash-escaped whitespace characters are removed from the document. +This allows for character-level `inline markup`_. There are two contexts in which backslashes have no special meaning: literal blocks and inline literals. In these contexts, a single @@ -2142,9 +2146,8 @@ In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary character-level markup is not supported -[#]_; it is not possible to mark up individual characters within a -word. Inline markup cannot be nested. +with whitespace. Arbitrary `character-level inline markup`_ is +supported although not encouraged. Inline markup cannot be nested. There are nine inline markup constructs. Five of the constructs use identical start-strings and end-strings to indicate the markup: @@ -2183,7 +2186,7 @@ end-string will not be recognized or processed. 4. Inline markup end-strings must end a text block or be immediately followed by whitespace or one of:: - ' " ) ] } > - / : . , ; ! ? + ' " ) ] } > - / : . , ; ! ? \ 5. If an inline markup start-string is immediately preceded by a single or double quote, "(", "[", "{", or "<", it must not be @@ -2245,17 +2248,35 @@ each character. The inline markup recognition order is as follows: - `Standalone hyperlinks`_ are the last to be recognized. -.. [#] Backslash escapes can be used to allow arbitrary text to - immediately follow inline markup:: - Python ``list``\s use square bracket syntax. +Character-Level Inline Markup +----------------------------- + +It is possible to mark up individual characters within a word with +backslash escapes (see `Escaping Mechanism`_ above). Backslash +escapes can be used to allow arbitrary text to immediately follow +inline markup:: + + Python ``list``\s use square bracket syntax. + +The backslash will disappear from the processed document. The word +"list" will appear as inline literal text, and the letter "s" will +immediately follow it as normal text, with no space in-between. + +Arbitrary text may immediately precede inline markup using +backslash-escaped whitespace:: + + Possible in *re*\ ``Structured``\ *Text*, though not encouraged. - The backslash will disappear from the processed document. The word - "list" will appear as inline literal text, and the letter "s" will - immediately follow it as normal text, with no space in-between. +The backslashes and spaces separating "re", "Structured", and "Text" +above will disappear from the processed document. + +.. CAUTION:: - There is not yet any way for arbitrary text to immediately precede - inline markup. + The use of backslash-escapes for character-level inline markup is + not encouraged. Such use is ugly and detrimental to the + unprocessed document's readability. Please use this feature + sparingly and only where absolutely necessary. Emphasis @@ -2427,7 +2448,7 @@ For example, here is a reference to a title describing a tag:: See `HTML Element: \<a>`_ below. -.. Caution:: +.. CAUTION:: This construct offers easy authoring and maintenance of hyperlinks at the expense of general readability. Inline URIs, especially diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index b1a1bb3ed..a3485679e 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -24,7 +24,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2002-10-08</em> + <br align="right"><em>Updated 2003-03-22</em> <p>The full details of the markup may be found on the @@ -188,16 +188,17 @@ <li>The end-string must be immediately preceded by non-whitespace. <li>The end-string must end a text block (end of document or followed by a blank line) or be immediately followed by whitespace - or any of <samp>' " . , : ; ! ? - ) ] }</samp> or <samp>></samp>. + or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> + or <samp>></samp>. <li>If a start-string is immediately preceded by one of  <samp>' " ( [ {</samp> or <samp><</samp>, it must not be immediately followed by the corresponding character from  <samp>' " ) ] }</samp> or <samp>></samp>. <li>An end-string must be separated by at least one character from the start-string. - <li>An <a href="#escaping">unescaped</a> backslash preceding a start-string or end-string will - disable markup recognition, except for the end-string of inline - literals. + <li>An <a href="#escaping">unescaped</a> backslash preceding a + start-string or end-string will disable markup recognition, except + for the end-string of inline literals. </ol> <p>Also remember that inline markup may not be nested (well, -- cgit v1.2.1 From 3d98a8e8eea73278c7c72eb907a4d20d99e24ee8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Mar 2003 00:21:21 +0000 Subject: fixed bibliographic field language lookups git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1234 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 3c47f8a0f..e27b69381 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -98,8 +98,9 @@ Each Docutils language module contains three module attributes: ``bibliographic_fields`` This is a mapping of language-dependent field names (converted to - lower case) to node classes (in ``docutils.nodes``). It is used - when parsing bibliographic fields. + lower case) to canonical field names (keys of + ``DocInfo.biblio_notes`` in ``docutils.transforms.frontmatter``). + It is used when transforming bibliographic fields. The keys should be translated to the target language. -- cgit v1.2.1 From 1c87d959eb6be73667ca61bbb48d69b075a846df Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Mar 2003 03:56:37 +0000 Subject: substitutions made case-sensitive but forgiving (case-insensitive fallback) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1236 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 76 +++++++++++++++++++++++++++++---------- docs/dev/todo.txt | 30 ---------------- docs/ref/rst/restructuredtext.txt | 21 ++++++----- 3 files changed, 69 insertions(+), 58 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index b36ec2e14..0208e3c0e 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -234,6 +234,44 @@ requiring this functionality may be better off using XML or another markup system. +Character Processing +-------------------- + +Several people have suggested adding some form of character processing +to reStructuredText: + +* Some sort of automated replacement of ASCII sequences: + + - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). + - Convert quotes to curly quote entities. (Essentially impossible + for HTML? Unnecessary for TeX.) + - Various forms of ``:-)`` to smiley icons. + - ``"\ "`` to  . Problem with line-wrapping though: it could + end up escaping the newline. + - Escaped newlines to <BR>. + - Escaped period or quote or dash as a disappearing catalyst to + allow character-level inline markup? + +* XML-style character entities, such as "©" for the copyright + symbol. + +Docutils has no need of a character entity subsystem. Supporting +Unicode and text encodings, character entities should be directly +represented in the text: a copyright symbol should be represented by +the copyright symbol character. If this is not possible in an +authoring environment, a pre-processing stage can be added, or a table +of substitution definitions can be devised. + +To allow for `character-level inline markup`_, a limited form of +character processing has been added to the spec and parser: escaped +whitespace characters are removed from the processed document. Any +further character processing will be of this functional type, rather +than of the character-encoding type. + +.. _character-level inline markup: + reStructuredText.html#character-level-inline-markup + + Field Lists =========== @@ -1394,15 +1432,15 @@ Currently reStructuredText has two hyperlink syntax variations: .. _phrase reference: http://www.example.org/phrase_reference/ .. _line boundaries: http://www.example.org/line_boundaries/ - + Advantages: + + Advantages: - The plaintext is readable. - Each target may be reused multiple times (e.g., just write ``"reference_"`` again). - No syncronized ordering of references and targets is necessary. - + + Disadvantages: - + - The reference text must be repeated as target names; could lead to mistakes. - The target URLs may be located far from the references, and hard @@ -1418,13 +1456,13 @@ Currently reStructuredText has two hyperlink syntax variations: __ http://www.example.org/phrase_reference/ __ http://www.example.org/line_boundaries/ - + Advantages: + + Advantages: - The plaintext is readable. - The reference text does not have to be repeated. - + + Disadvantages: - + - References and targets must be kept in sync. - Targets cannot be reused. - The target URLs may be located far from the references. @@ -1446,7 +1484,7 @@ syntaxes for hyperlinks: Both syntaxes share advantages and disadvantages: -+ Advantages: ++ Advantages: - The target is specified immediately adjacent to the reference. @@ -1472,18 +1510,18 @@ A new type of "inline external hyperlink" has been proposed. these examples, (single-underscore), named? If so, `anonymous references`__(http://www.example.org/anonymous/) using two underscores would probably be preferable. - + __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html The syntax, advantages, and disadvantages are similar to those of StructuredText. - + Advantages: - + + Advantages: + - The target is specified immediately adjacent to the reference. - + + Disadvantages: - + - Poor plaintext readability. - Targets cannot be reused (unless named, but the semantics are unclear). @@ -1492,7 +1530,7 @@ A new type of "inline external hyperlink" has been proposed. - The ``"`ref`_(URL)"`` syntax forces the last word of the reference text to be joined to the URL, making a potentially - very long word that can't be wrapped (URLs can be very long). + very long word that can't be wrapped (URLs can be very long). The reference and the URL should be separate. This is a symptom of the following point: @@ -1525,11 +1563,11 @@ A new type of "inline external hyperlink" has been proposed. The syntax builds on that of the existing "inline internal targets": ``an _`inline internal target`.`` - + Advantages: + + Advantages: - The target is specified immediately adjacent to the reference, improving maintainability: - + - References and targets are easily kept in sync. - The reference text does not have to be repeated. @@ -1541,7 +1579,7 @@ A new type of "inline external hyperlink" has been proposed. brackets [#]_. + Disadvantages: - + - Poor plaintext readability. - Lots of "line noise". - Targets cannot be reused (unless named; see below). @@ -1574,13 +1612,13 @@ A new type of "inline external hyperlink" has been proposed. characters are excluded [from URIs] because they are often used as the delimiters around URI in text documents and protocol fields. - + Using <> angle brackets around each URI is especially recommended as a delimiting style for URI that contain whitespace. - + From RFC 822 (email headers): - + Angle brackets ("<" and ">") are generally used to indicate the presence of a one machine-usable reference (e.g., delimiting mailboxes), possibly including source-routing to diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c62ba5a61..20bb5ed61 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -485,36 +485,6 @@ __ rst/alternatives.html#or-not-to-do This may not be just a parser issue though; it may need framework support. -* Add _`character processing`? For example: - - - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). - (Look for pre-existing conventions.) - - Convert quotes to curly quote entities. (Essentially impossible - for HTML? Unnecessary for TeX. An output issue?) - - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to  . Problem with line-wrapping though: it could - end up escaping the newline. - - Escaped newlines to <BR>. - - Escaped period or quote or dash as a disappearing catalyst to - allow character-level inline markup? - - Others? - - How to represent character entities in the text though? Probably as - Unicode. - - Which component is responsible for this, the parser, the reader, or - the writer? - -* Idea from David Abrahams re character-level inline markup: - - I can think of one way to beautify cases like this: introduce a - kind of quotation which removes all spaces in what it surrounds - as a postprocessing step. :: - - ''*re* ``Structured`` *Text*'' - - This would be analogous to re.VERBOSE, if memory serves. - * 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 diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 819d05d3f..90f19e4e1 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1893,12 +1893,14 @@ indirectly contain a circular substitution reference. `Substitution references`_ are replaced in-line by the processed contents of the corresponding definition (linked by matching -substitution text). Substitution definitions allow the power and -flexibility of block-level directives_ to be shared by inline text. -They are a way to include arbitrarily complex inline structures within -text, while keeping the details out of the flow of text. They are the -equivalent of SGML/XML's named entities or programming language -macros. +substitution text). Matches are case-sensitive but forgiving; if no +exact match is found, a case-insensitive comparison is attempted. + +Substitution definitions allow the power and flexibility of +block-level directives_ to be shared by inline text. They are a way +to include arbitrarily complex inline structures within text, while +keeping the details out of the flow of text. They are the equivalent +of SGML/XML's named entities or programming language macros. Without the substitution mechanism, every time someone wants an application-specific new inline structure, they would have to petition @@ -2270,7 +2272,7 @@ backslash-escaped whitespace:: The backslashes and spaces separating "re", "Structured", and "Text" above will disappear from the processed document. - + .. CAUTION:: The use of backslash-escapes for character-level inline markup is @@ -2540,8 +2542,9 @@ a "_" (named) or "__" (anonymous) suffix; the substitution text is used for the reference text in the named case. The processing system replaces substitution references with the -processed contents of the corresponding `substitution definitions`_. -Substitution definitions produce inline-compatible elements. +processed contents of the corresponding `substitution definitions`_ +(which see for the definition of "correspond"). Substitution +definitions produce inline-compatible elements. Examples:: -- cgit v1.2.1 From 98eab0e0fa0239ad300d565a7a2677143252689f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Mar 2003 04:00:49 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1237 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 20bb5ed61..70920c747 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -633,8 +633,7 @@ __ rst/alternatives.html#or-not-to-do Another idea: in an ordinary paragraph, if the first line ends with a backslash (escaping the newline), interpret the entire paragraph - as a verse block? This ties in to the `character processing`_ idea, - above. For example:: + as a verse block? For example:: Add just one backslash\ And this paragraph becomes -- cgit v1.2.1 From 09c2329ee31dc8f649be18dc23322b1d73c2f2f9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 27 Mar 2003 13:14:59 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1239 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index a6b5e9385..3a95fe675 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -190,6 +190,7 @@ Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt files. If no arguments are given, all files of the form "``pep-*.txt``" are processed. + rst2latex.py ------------ @@ -197,23 +198,25 @@ rst2latex.py :Parser: reStructuredText :Writer: LaTeX2e -The ``rst2laetx.py`` front end reads standalone reStructuredText source -files and produces LaTeX2e output. For example, to process a reStructuredText file -"``test.txt``" into LaTeX:: +The ``rst2latex.py`` front end reads standalone reStructuredText +source files and produces LaTeX2e output. For example, to process a +reStructuredText file "``test.txt``" into LaTeX:: rst2latex.py test.txt test.tex -The output file "``test.tex``" should then be processed with ``latex`` or -``pdflatex`` to get a typeset document. +The output file "``test.tex``" should then be processed with ``latex`` +or ``pdflatex`` to get a typeset document. Some limitations and difference apply: -- Gif,jpg or png images are not handled, when processed with ``latex``, use - ``pdflatex`` instead. +- Gif,jpg or png images are not handled, when processed with + ``latex``, use ``pdflatex`` instead. - Only Latin-1 is tested up to now. -- The generated file includes a file ``style.tex``, which allows the inclusion - of special packages or changes to settings made in the header. -- Not all constructs e.g. multirow/multicoumn entries in tables are possible. +- The generated file includes a file ``style.tex``, which allows the + inclusion of special packages or changes to settings made in the + header. +- Not all constructs are possible (e.g. multirow/multicoumn entries in + tables are not). docutils-xml.py -- cgit v1.2.1 From 6a44b80fbc36df0065293b936d526e31f7267dea Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 28 Mar 2003 20:41:20 +0000 Subject: updated from mailing list discussions git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1241 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 70920c747..40235fff6 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -304,6 +304,10 @@ General * 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? + Documentation ------------- @@ -331,6 +335,8 @@ Implementation Docs * Document the transforms (perhaps in docstrings?): how they're used, what they do, dependencies & order considerations. +* Document the HTML classes used by html4css1.py. + Specification ````````````` @@ -550,8 +556,20 @@ __ rst/alternatives.html#or-not-to-do 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. + "Structuring: a summary; and an attempt at EBNF", item 4. Also + docutils-users, 2003-02-17. * Make the parser modular. Allow syntax constructs to be added or disabled at run-time. Or is subclassing enough? @@ -671,6 +689,18 @@ __ rst/alternatives.html#or-not-to-do 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 + +* Line numbers in system messages are inconsistent in the parser. + Fix? + +* Generalize the "target-notes" directive into a command-line option + somehow? See docutils-develop 2003-02-13. + Directives `````````` @@ -687,6 +717,8 @@ when used in a document. - _`images.image`: "border"? + Units of measure? (See docutils-users, 2003-03-02.) + - _`images.figure`: "title" and "number", to indicate a formal figure? @@ -735,6 +767,9 @@ when used in a document. 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`: "encoding" option? Take default from runtime settings. Use Input component to read it in? @@ -784,6 +819,10 @@ when used in a document. problem similar to the first problem listed for misc.encoding_, although to a lesser degree. + - _`misc.class`: Specify a "class" attribute value to an element + (enclosing? preceding? following?). See docutils-develop + 2003-01-29. + - _`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?) @@ -915,6 +954,16 @@ when used in a document. 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" + + See docutils-users 2003-03-03. + + - _`admonitions.admonition`: Generic, titled admonition. + - _`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" -- cgit v1.2.1 From 3171a1a73139979536cdb785dfd3795e7f40ac30 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 Mar 2003 14:58:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1243 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 40235fff6..4353240e3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1191,7 +1191,9 @@ HTML Writer writer to generate .ht & links.h files for ht2html? * Add a setting (or another writer) which produces just the contents - of the <body> element. Part of the ht2html implementation? + of the <body> element. What about the rest; it should be accessible + somehow, especially the docinfo fields. Part of the ht2html + implementation? Generic component output? * Add more support for <link> elements, especially for navigation bars. -- cgit v1.2.1 From 26600cb16f6e77aa8584ffe0a8938a6fb5c7d3f3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Apr 2003 01:13:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1255 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4353240e3..c831b32e7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -715,7 +715,7 @@ when used in a document. * Implement options on existing directives: - - _`images.image`: "border"? + - _`images.image`: "border"? "link"? Units of measure? (See docutils-users, 2003-03-02.) @@ -1259,8 +1259,10 @@ Front-End Tools * 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. Alternatively, create a single dynamic_ or - unqualified_ front end that can be installed. + them as scripts. + +* Create a single dynamic_ or unqualified_ front end that can be + installed? Project Policies -- cgit v1.2.1 From 35e8cc0c270a59029dd1e5276894c4955eaf09c7 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Apr 2003 07:28:18 +0000 Subject: Add latex writer document. Table width is relative to an assumed reST linelength of 80 characters. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1264 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/user/latex.txt (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt new file mode 100644 index 000000000..2273a00be --- /dev/null +++ b/docs/user/latex.txt @@ -0,0 +1,125 @@ +======================= + Docutils LaTex Writer +======================= + +:Author: Engelbert Gruber +:Contact: grubert@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ + +.. contents:: + + +Introduction +============ + +Producing latex code from reST input could be done in at least two ways: + +a. Transform the internal markup into corresponding latex markup e.g. + a section title would be written as ```\section{this section ...}``. +b. Using latex as a typesetting system to produce desired paperwork + without caring about loosing document structure information. + +The former might be preferable, but limits to latexs capabilities, so +in reality it is a mix. + + +Options +======= + +Configuration can be done in two ways (again): + +1. Options to the docutils tool: e.g. language selection. +2. Options to latex via the stylesheet file. + +The generated latex documents should be kept processable by a standard +latex installation (if such a thing exists), therefore the document +contains default settings. To allow *overwriting defaults* the stylesheet +is included at last. + +Table of contents +----------------- + +To get pagenumbers in the table of contents the table of contents must +be generated by latex: ``--use-latex-toc=1``. Usually latex must be run twice to +get numbers correct. + +Missing options +--------------- + +* Selection of latex documentclass and papersize. +* Assumed reST linelength for table width setting. + +Problems +======== + +Open to be fixed or open to discussion. + +Tables +------ + +:Tablewidth: reST-documents line length is assumed to be 80 characters. The + tablewidth is set relative to this value. If someone produces + documents with line length of 132 this will fail. + + +* In tools.txt the option tables right column, there should be some more spacing + between the description and the next paragraph "Default:". + + Paragraph separation in tables is hairy. + see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab + + - The strut solution did not work. + - setting extrarowheight added ad top of row not between paragraphs in + a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline. + - baselineskip/stretch does not help. +* Should there be two hlines after table head and on table end ? +* Table: multicol cells are always {l}. +* Table heads and footer for longtable (firstpage lastpage ..). +* Longtable does not work with multirow +* Tabularx says "do not use any multicolmn which spans any X column. + maybe use ltxtable instead of tabularx (Longtable combined with tabularx). + but ltxtable disables longtable's multicolumn. +* Table cells with multirow and multicolumn +* Tables have borders, and the border is missing in empty cells. + + +Miscellaneous +------------- + +* Doctest blocks is incorrect (python prompt is escaped inside verbatim). +* Support embed-stylesheet. +* the ^-sign is problematic: using mathmode wedge is usually the wrong font. +* Sidebar handling. +* Maybe add end of line after term in definition list. see + http://roundup.sf.net/doc-0.5/features.pdf +* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH). +* center subsection{Abstract} gives a latex error here. + ``! LaTeX Error: Something's wrong--perhaps a missing \item.`` + Committed a HACK: centering by hfill. +* Document errors are also too silent. +* Use optionlist for docinfo, the table does only work for single page. +* Consider peter funk's hooks for TeXpert: + + * Define his own document preamble (including the choice to + choose his own documentclass. That would make the ``--documentclass`` + option superfluous). I suggest to call this option ``--preamble`` + * Use two additional hooks to put additional stuff just behind the + ``\begin{document}`` and just before the ``\end{document}`` macros. + Typical uses would be ``\tableofcontents``, ``\listoffigures`` and + ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such + for larger documents. + +* Hyphens: co-developers should be co--developers ? +* The indentional problematic error in test.txt is not referring anywhere. +* Footnotes are not all on the same page (as in tools/test.txt) and do not link back + and forth. +* No link to system errors. +* Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt + 2.14 directives directives +* Meta keywords into pdf ? +* Pagestyle headings does not work, when sections are starred. +* For additional docinfo items: the field_body is inserted as text, i.e. no + markup is done. +* Multiple author entries in docinfo (same thing as in html). + -- cgit v1.2.1 From 1efe26688716c2186ca2077430da7a11d031121e Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Apr 2003 07:34:29 +0000 Subject: Fix: Doctest blocks in real verbatim. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1265 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 2273a00be..92c40bb12 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -87,7 +87,6 @@ Tables Miscellaneous ------------- -* Doctest blocks is incorrect (python prompt is escaped inside verbatim). * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. * Sidebar handling. -- cgit v1.2.1 From 3d412915a9f0b8906f8fe91e740a0605cdcb0a28 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Apr 2003 11:10:06 +0000 Subject: Documentation for stylesheet usage. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 48 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 92c40bb12..209d5a269 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -37,17 +37,51 @@ latex installation (if such a thing exists), therefore the document contains default settings. To allow *overwriting defaults* the stylesheet is included at last. -Table of contents ------------------ - -To get pagenumbers in the table of contents the table of contents must -be generated by latex: ``--use-latex-toc=1``. Usually latex must be run twice to -get numbers correct. +Options on the Commandline +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +===================== ================================================ +Setting/Config Entry Description +===================== ================================================ +--use-latex-toc To get pagenumbers in the table of contents the + table of contents must be generated by latex. + Usually latex must be run twice to get numbers + correct. +--------------------- ------------------------------------------------ +--hyperlink-color Color of any hyperlinks embedded in text + (default: "blue", "0" to disable). +===================== ================================================ + + +Options in the Stylesheet +~~~~~~~~~~~~~~~~~~~~~~~~~ + +===================== ================================================ +Setting/Config Entry Description +===================== ================================================ +papersize Default: a4paper. Paper geometry can be changed + using ``\geometry{xxx}`` entries. + + Some possibilities: + * a4paper, b3paper, letterpaper, executivepaper, + legalpaper + * landscape, portrait, twoside. + and a ton of other option setting margins. +--------------------- ------------------------------------------------ +paragraph indent By default latex indents the forst line in a + paragraph. The following lines set indentation + to zero but add a vertical space between + paragraphs.:: + + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt} + +===================== ================================================ Missing options --------------- -* Selection of latex documentclass and papersize. +* Selection of latex documentclass and fontsize. * Assumed reST linelength for table width setting. Problems -- cgit v1.2.1 From 330b616b77c8b67291795d44962ea3bdb4aeb349 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Apr 2003 21:47:57 +0000 Subject: fixed markup errors git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1271 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 209d5a269..908431dce 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -38,7 +38,7 @@ contains default settings. To allow *overwriting defaults* the stylesheet is included at last. Options on the Commandline -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- ===================== ================================================ Setting/Config Entry Description @@ -54,7 +54,7 @@ Setting/Config Entry Description Options in the Stylesheet -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- ===================== ================================================ Setting/Config Entry Description @@ -63,9 +63,11 @@ papersize Default: a4paper. Paper geometry can be changed using ``\geometry{xxx}`` entries. Some possibilities: + * a4paper, b3paper, letterpaper, executivepaper, legalpaper * landscape, portrait, twoside. + and a ton of other option setting margins. --------------------- ------------------------------------------------ paragraph indent By default latex indents the forst line in a @@ -75,7 +77,6 @@ paragraph indent By default latex indents the forst line in a \setlength{\parindent}{0pt} \setlength{\parskip}{6pt plus 2pt minus 1pt} - ===================== ================================================ Missing options -- cgit v1.2.1 From 108c7f999935ac472c17e7766392cfa82e04bc55 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Apr 2003 12:45:09 +0000 Subject: Add latex lengths: admonitionwidth and docinfowidth. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1272 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 908431dce..2f08c1fe4 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -77,6 +77,17 @@ paragraph indent By default latex indents the forst line in a \setlength{\parindent}{0pt} \setlength{\parskip}{6pt plus 2pt minus 1pt} +--------------------- ------------------------------------------------ +admonitionwidth The width for admonitions. + Default: 0.9*textwidth, this can be changed + e.g.:: + + \setlength{\admonitionwidth}{0.7\textwidth} +--------------------- ------------------------------------------------ +docinfowidth The width for the docinfo table. + Default: 0.9*textwidth, changed to e.g.:: + + \setlength{\docinfowidth}{0.7\textwidth} ===================== ================================================ Missing options -- cgit v1.2.1 From 593e45fb2edecff6652ee51363f8466bd38a5363 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 16 Apr 2003 09:39:18 +0000 Subject: Actually use documentclass option. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1278 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 2f08c1fe4..70627b8f0 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -50,6 +50,10 @@ Setting/Config Entry Description --------------------- ------------------------------------------------ --hyperlink-color Color of any hyperlinks embedded in text (default: "blue", "0" to disable). +--------------------- ------------------------------------------------ +--documentclass Specify latex documentclass, *but* beaware that + books have chapters articles not. + (default: "article"). ===================== ================================================ -- cgit v1.2.1 From 85926fa8addd84c3d6411d73039a5bf1c6bc196d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 21:41:59 +0000 Subject: added "figwidth" option to "figure" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1280 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +++ docs/ref/docutils.dtd | 4 +++- docs/ref/rst/directives.txt | 25 +++++++++++++++++++++++-- 3 files changed, 29 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c831b32e7..5faf95214 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -722,6 +722,9 @@ when used in a document. - _`images.figure`: "title" and "number", to indicate a formal figure? + "figure-width" to constrain the width to actual width of the + image. Would require PIL. + - _`parts.sectnum`: "local"?, "start", "refnum" A "local" option could enable numbering for sections from a diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5c8857ae9..162cf212c 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -436,7 +436,9 @@ or " ") or the text between option arguments (typically either "," or <!ATTLIST pending %basic.atts;> <!ELEMENT figure (image, ((caption, legend?) | legend)) > -<!ATTLIST figure %basic.atts;> +<!ATTLIST figure + %basic.atts; + width %number; #IMPLIED> <!-- Also an inline element. --> <!ELEMENT image EMPTY> diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index ba93d7da0..4f07cdfe8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -116,7 +116,7 @@ intervening blank lines. If there are multiple lines in the link block, they are stripped of leading and trailing whitespace and joined together. -Optionally, the image link block may end with a flat field list, the +Optionally, the image link block may contain a flat field list, the _`image options`. For example:: .. image:: picture.jpeg @@ -162,7 +162,7 @@ Figure :Directive Type: "figure" :DTD Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). -:Directive Options: Possible; same as those of the `image`_ directive. +:Directive Options: Possible. :Directive Content: Interpreted as the figure caption and an optional legend. @@ -194,6 +194,27 @@ There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment ("..") in place of the caption. +The "figure" directive supports all of the options of the "image" +directive (see `image options`_ above). In addition, the following +option is recognized: + +``figwidth`` : integer or "image" + The width of the figure in pixels, to limit the horizontal space + used. A special value of "image" is allowed, in which case the + included image's actual width is used (requires PIL_ [#]_). If the + image file is not found or the required software is unavailable, + this option is ignored. + + Sets the "width" attribute of the "figure" DTD element. + + This option does not scale the included image; use the "width" + `image`_ option for that. + +.. [#] `Python Imaging Library`__. + +.. _PIL: +__ http://www.pythonware.com/products/pil/ + --------------- Body Elements -- cgit v1.2.1 From 4af77fded54fea37831284fd05b436b9c698cc6f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 22:28:19 +0000 Subject: changed "DTD element" to "doctree element" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1282 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 51 ++++++++++++++----------- docs/ref/rst/restructuredtext.txt | 79 ++++++++++++++++++++------------------- 2 files changed, 69 insertions(+), 61 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4f07cdfe8..a5b675ad8 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -6,6 +6,8 @@ :Revision: $Revision$ :Date: $Date$ +.. contents:: + This document describes the directives implemented in the reference reStructuredText parser. @@ -26,11 +28,16 @@ content (in that order), any of which may appear. See the Directives_ section in the `reStructuredText Markup Specification`_ for syntax details. +Descriptions below list "doctree elements" (document tree element +names; XML DTD generic identifiers) corresponding to individual +directives. For details on the hierarchy of elements, please see +`Docutils Document Tree Structure`_ and the `Generic Plaintext +Document Interface DTD`_ XML document type definition. + .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html - - -.. contents:: +.. _Docutils Document Tree Structure: ../doctree.html +.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd ------------- @@ -39,8 +46,8 @@ details. :Directive Types: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning" -:DTD Elements: attention, caution, danger, error, hint, important, - note, tip, warning +:Doctree Elements: attention, caution, danger, error, hint, important, + note, tip, warning :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as body elements. @@ -99,7 +106,7 @@ Image ===== :Directive Type: "image" -:DTD Element: image +:Doctree Element: image :Directive Arguments: One, required (image URI). :Directive Options: Possible. :Directive Content: None. @@ -160,7 +167,7 @@ Figure ====== :Directive Type: "figure" -:DTD Elements: figure, image, caption, legend +:Doctree Elements: figure, image, caption, legend :Directive Arguments: One, required (image URI). :Directive Options: Possible. :Directive Content: Interpreted as the figure caption and an optional @@ -205,7 +212,7 @@ option is recognized: image file is not found or the required software is unavailable, this option is ignored. - Sets the "width" attribute of the "figure" DTD element. + Sets the "width" attribute of the "figure" doctree element. This option does not scale the included image; use the "width" `image`_ option for that. @@ -224,7 +231,7 @@ Topic ===== :Directive Type: "topic" -:DTD Element: topic +:Doctree Element: topic :Directive Arguments: 1, required (topic title). :Directive Options: None. :Directive Content: Interpreted as the topic body. @@ -250,7 +257,7 @@ Sidebar ======= :Directive Type: "sidebar" -:DTD Element: sidebar +:Doctree Element: sidebar :Directive Arguments: One, required (sidebar title). :Directive Options: Possible; optional subtitle. :Directive Content: Interpreted as the sidebar body. @@ -287,7 +294,7 @@ Line Block ========== :Directive Type: "line-block" -:DTD Element: line_block +:Doctree Element: line_block :Directive Arguments: None. :Directive Options: None. :Directive Content: Becomes the body of the line block. @@ -318,7 +325,7 @@ Parsed Literal Block ==================== :Directive Type: "parsed-literal" -:DTD Element: literal_block +:Doctree Element: literal_block :Directive Arguments: None. :Directive Options: None. :Directive Content: Becomes the body of the literal block. @@ -351,7 +358,7 @@ Table of Contents ================= :Directive Type: "contents" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: One, optional: title. :Directive Options: Possible. :Directive Content: None. @@ -407,7 +414,7 @@ Automatic Section Numbering =========================== :Directive Type: "sectnum" or "section-autonumbering" (synonyms) -:DTD Elements: pending, generated +:Doctree Elements: pending, generated :Directive Arguments: None. :Directive Options: Possible. :Directive Content: None. @@ -441,7 +448,7 @@ Target Footnotes ================ :Directive Type: "target-notes" -:DTD Elements: pending, footnote, footnote_reference +:Doctree Elements: pending, footnote, footnote_reference :Directive Arguments: None. :Directive Options: None. :Directive Content: None. @@ -459,7 +466,7 @@ Footnotes **NOT IMPLEMENTED YET** :Directive Type: "footnotes" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: None? :Directive Options: Possible? :Directive Content: None. @@ -473,7 +480,7 @@ Citations **NOT IMPLEMENTED YET** :Directive Type: "citations" -:DTD Elements: pending, topic +:Doctree Elements: pending, topic :Directive Arguments: None? :Directive Options: Possible? :Directive Content: None. @@ -489,7 +496,7 @@ Meta ==== :Directive Type: "meta" -:DTD Element: meta (non-standard) +:Doctree Element: meta (non-standard) :Directive Arguments: None. :Directive Options: None. :Directive Content: Must contain a flat field list. @@ -557,7 +564,7 @@ Including an External Document Fragment ======================================= :Directive Type: "include" -:DTD Elements: depend on data being included +:Doctree Elements: depend on data being included :Directive Arguments: One, required (path to include file). :Directive Options: Possible. :Directive Content: None. @@ -596,7 +603,7 @@ Raw Data Pass-Through ===================== :Directive Type: "raw" -:DTD Element: pending +:Doctree Element: pending :Directive Arguments: One, required (output format type). :Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a @@ -642,7 +649,7 @@ Replacement Text ================ :Directive Type: "replace" -:DTD Element: pending +:Doctree Element: pending :Directive Arguments: None. :Directive Options: None. :Directive Content: A single paragraph; may contain inline markup. @@ -671,7 +678,7 @@ Restructuredtext-Test-Directive =============================== :Directive Type: "restructuredtext-test-directive" -:DTD Element: system_warning +:Doctree Element: system_warning :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as a literal block. diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 90f19e4e1..d714635a6 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -207,11 +207,11 @@ Here are examples of `body elements`_: Syntax Details ---------------- -Descriptions below list "DTD elements" (XML "generic identifiers") -corresponding to syntax constructs. For details on the hierarchy of -elements, please see `Docutils Document Tree Structure`_ and the -`Generic Plaintext Document Interface DTD`_ XML document type -definition. +Descriptions below list "doctree elements" (document tree element +names; XML DTD generic identifiers) corresponding to syntax +constructs. For details on the hierarchy of elements, please see +`Docutils Document Tree Structure`_ and the `Generic Plaintext +Document Interface DTD`_ XML document type definition. Whitespace @@ -425,7 +425,7 @@ Document Structure Document -------- -DTD element: document. +Doctree element: document. The top-level element of a parsed reStructuredText document is the "document" element. After initial parsing, the document element is a @@ -448,7 +448,7 @@ the "document title" can become the document subtitle. See the Sections -------- -DTD elements: section, title. +Doctree elements: section, title. Sections are identified through their titles, which are marked up with adornment: "underlines" below the title text, or underlines and @@ -542,7 +542,7 @@ sections. Transitions ----------- -DTD element: transition. +Doctree element: transition. Instead of subheads, extra space or a type ornament between paragraphs may be used to mark text divisions or to signal @@ -582,7 +582,7 @@ Body Elements Paragraphs ---------- -DTD element: paragraph. +Doctree element: paragraph. Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element. Blank lines separate paragraphs @@ -605,7 +605,7 @@ Syntax diagram:: Bullet Lists ------------ -DTD elements: bullet_list, list_item. +Doctree elements: bullet_list, list_item. A text block which begins with a "-", "*", or "+", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). @@ -654,7 +654,7 @@ Syntax diagram:: Enumerated Lists ---------------- -DTD elements: enumerated_list, list_item. +Doctree elements: enumerated_list, list_item. Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an @@ -734,8 +734,8 @@ Example syntax diagram:: Definition Lists ---------------- -DTD elements: definition_list, definition_list_item, term, classifier, -definition. +Doctree elements: definition_list, definition_list_item, term, +classifier, definition. Each definition list item contains a term, an optional classifier, and a definition. A term is a simple one-line word or phrase. An @@ -788,7 +788,7 @@ Syntax diagram:: Field Lists ----------- -DTD elements: field_list, field, field_name, field_body. +Doctree elements: field_list, field, field_name, field_body. Field lists are used as part of an extension syntax, such as options for directives_, or database-like records meant for further @@ -845,7 +845,7 @@ Syntax diagram (simplified):: Bibliographic Fields ```````````````````` -DTD elements: docinfo, author, authors, organization, contact, +Doctree elements: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic. When a field list is the first non-comment element in a document @@ -855,7 +855,7 @@ corresponds to the front matter of a book, such as the title page and copyright page. Certain registered field names (listed below) are recognized and -transformed to the corresponding DTD elements, most becoming child +transformed to the corresponding doctree elements, most becoming child elements of the "docinfo" element. No ordering is required of these fields, although they may be rearranged to fit the document structure, as noted. Unless otherwise indicated below, each of the bibliographic @@ -864,8 +864,8 @@ bodies may be checked for `RCS keywords`_ and cleaned up. Any unrecognized fields will remain as generic fields in the docinfo element. -The registered bibliographic field names and their corresponding DTD -elements are as follows: +The registered bibliographic field names and their corresponding +doctree elements are as follows: - Field name "Author": author element. - "Authors": authors. @@ -941,7 +941,7 @@ hold: Option Lists ------------ -DTD elements: option_list, option_list_item, option_group, option, +Doctree elements: option_list, option_list_item, option_group, option, option_string, option_argument, description. Option lists are two-column lists of command-line options and @@ -1025,7 +1025,7 @@ Syntax diagram (simplified):: Literal Blocks -------------- -DTD element: literal_block. +Doctree element: literal_block. A paragraph consisting of two colons ("::") signifies that all following **indented** text blocks comprise a literal block. No @@ -1098,7 +1098,7 @@ Syntax diagram:: Block Quotes ------------ -DTD element: block_quote. +Doctree element: block_quote. A text block that is indented relative to the preceding text, without markup indicating it to be a literal block, is a block quote. All @@ -1129,7 +1129,7 @@ Syntax diagram:: Doctest Blocks -------------- -DTD element: doctest_block. +Doctree element: doctest_block. Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and @@ -1159,7 +1159,7 @@ Indentation is not required for doctest blocks. Tables ------ -DTD elements: table, tgroup, colspec, thead, tbody, row, entry. +Doctree elements: table, tgroup, colspec, thead, tbody, row, entry. ReStructuredText provides two syntaxes for delineating table cells: `Grid Tables`_ and `Simple Tables`_. @@ -1377,7 +1377,7 @@ targets, directives, substitution definitions, and comments. Footnotes ````````` -DTD elements: footnote, label. +Doctree elements: footnote, label. Each footnote consists of an explicit markup start (".. "), a left square bracket, the footnote label, a right square bracket, and @@ -1562,7 +1562,7 @@ differently from footnotes. For example:: Hyperlink Targets ````````````````` -DTD element: target. +Doctree element: target. These are also called _`explicit hyperlink targets`, to differentiate them from `implicit hyperlink targets`_ defined below. @@ -1772,7 +1772,7 @@ require attention to the order of corresponding targets. Directives `````````` -DTD elements: depend on the directive. +Doctree elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of adding support for new constructs without adding new syntax. All @@ -1874,7 +1874,7 @@ Syntax diagram:: Substitution Definitions ```````````````````````` -DTD element: substitution_definition. +Doctree element: substitution_definition. Substitution definitions are indicated by an explicit markup start (".. ") followed by a vertical bar, the substitution text, another @@ -2070,7 +2070,7 @@ Replacement text Comments ```````` -DTD element: comment. +Doctree element: comment. Arbitrary indented text may follow the explicit markup start and will be processed as a comment element. No further processing is done on @@ -2284,7 +2284,7 @@ above will disappear from the processed document. Emphasis -------- -DTD element: emphasis. +Doctree element: emphasis. Start-string = end-string = "*". @@ -2298,7 +2298,7 @@ Emphasized text is typically displayed in italics. Strong Emphasis --------------- -DTD element: strong. +Doctree element: strong. Start-string = end-string = "**". @@ -2312,7 +2312,8 @@ Strongly emphasized text is typically displayed in boldface. Interpreted Text ---------------- -DTD element: depends on the explicit or implicit role and processing. +Doctree element: depends on the explicit or implicit role and +processing. Start-string = end-string = "`". @@ -2350,7 +2351,7 @@ specialized roles. Inline Literals --------------- -DTD element: literal. +Doctree element: literal. Start-string = end-string = "``". @@ -2379,7 +2380,7 @@ Inline literals are useful for short code snippets. For example:: Hyperlink References -------------------- -DTD element: reference. +Doctree element: reference. - Named hyperlink references: @@ -2464,7 +2465,7 @@ For example, here is a reference to a title describing a tag:: Inline Internal Targets ------------------------ -DTD element: target. +Doctree element: target. Start-string = "_`", end-string = "`". @@ -2486,7 +2487,7 @@ reference names. Footnote References ------------------- -DTD element: footnote_reference. +Doctree element: footnote_reference. Start-string = "[", end-string = "]_". @@ -2512,7 +2513,7 @@ For example:: Citation References ------------------- -DTD element: citation_reference. +Doctree element: citation_reference. Start-string = "[", end-string = "]_". @@ -2531,7 +2532,7 @@ See Citations_ for the citation itself. Substitution References ----------------------- -DTD element: substitution_reference, reference. +Doctree element: substitution_reference, reference. Start-string = "|", end-string = "|" (optionally followed by "_" or "__"). @@ -2559,7 +2560,7 @@ Examples:: Standalone Hyperlinks --------------------- -DTD element: reference. +Doctree element: reference. Start-string = end-string = "" (empty string). @@ -2623,7 +2624,7 @@ Punctuation at the end of a URI is not considered part of the URI. Error Handling ---------------- -DTD element: system_message, problematic. +Doctree element: system_message, problematic. Markup errors are handled according to the specification in `PEP 258`_. -- cgit v1.2.1 From 027e6b5d677f682cf20e3ba3dd38c4511d02e14b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 18 Apr 2003 22:33:29 +0000 Subject: corrected ref titles git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1283 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 +++--- docs/ref/rst/restructuredtext.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index a5b675ad8..e4f5b15cb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -30,9 +30,9 @@ details. Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to individual -directives. For details on the hierarchy of elements, please see -`Docutils Document Tree Structure`_ and the `Generic Plaintext -Document Interface DTD`_ XML document type definition. +directives. For details on the hierarchy of elements, please see `The +Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document +type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index d714635a6..3361762b7 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -209,9 +209,9 @@ Here are examples of `body elements`_: Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to syntax -constructs. For details on the hierarchy of elements, please see -`Docutils Document Tree Structure`_ and the `Generic Plaintext -Document Interface DTD`_ XML document type definition. +constructs. For details on the hierarchy of elements, please see `The +Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document +type definition. Whitespace -- cgit v1.2.1 From b9ac2d2023345f155a457fece4e1e68042c6206a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 23 Apr 2003 23:39:40 +0000 Subject: fixed reference names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1287 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 ++-- docs/ref/rst/restructuredtext.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index e4f5b15cb..8f142f110 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,8 +36,8 @@ type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html -.. _Docutils Document Tree Structure: ../doctree.html -.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../gpdi.dtd ------------- diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 3361762b7..09ae893f7 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2632,8 +2632,8 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Document Tree Structure: ../doctree.html -.. _Generic Plaintext Document Interface DTD: ../gpdi.dtd +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../gpdi.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From 44975befa49fd1a2283b53a2e429faf084b5a8bf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 23 Apr 2003 23:42:09 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1289 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5faf95214..875237352 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -715,6 +715,10 @@ when used in a document. * Implement options on existing directives: + - Add a "class" option to many/most directives, to set an arbitrary + "class" attribute on the enclosing element (see `misc.class`_)? + Perhaps "name" as well? + - _`images.image`: "border"? "link"? Units of measure? (See docutils-users, 2003-03-02.) @@ -722,9 +726,6 @@ when used in a document. - _`images.figure`: "title" and "number", to indicate a formal figure? - "figure-width" to constrain the width to actual width of the - image. Would require PIL. - - _`parts.sectnum`: "local"?, "start", "refnum" A "local" option could enable numbering for sections from a @@ -965,7 +966,8 @@ when used in a document. See docutils-users 2003-03-03. - - _`admonitions.admonition`: Generic, titled admonition. + - _`admonitions.admonition`: Generic, titled admonition. Use + author-supplied title as "class" attribute value? - _`colorize.python`: Colorize Python code. Fine for HTML output, but what about other formats? Revert to a literal block? Do we @@ -1060,6 +1062,26 @@ elements. .. _multiple roles: rst/alternatives.html#multiple-roles-in-interpreted-text +* Add document-local role bindings, associating directives with roles? + + ``She wore ribbons in her hair and it lay with streaks of + grey``:rewrite: + + .. :rewrite: class:: rewrite + + The syntax is similar to that of substitution declarations, and the + directive/role association may resolve implementation issues. The + semantics, ramifications, and implementation details do need to be + worked out though. Syntax idea from Jeffrey C. Jacobs. + + The example above would implement the "rewrite" role as adding a + ``class="rewrite"`` attribute to the interpreted text. The + stylesheet would then pick up on the "class" attribute to do the + actual formatting. + + But what's the doctree element? Shall we introduce an arbitrary + "span" element? Put "interpreted" back for such purposes? + * Implement roles: - "acronym" and "abbreviation": Associate the full text with a short -- cgit v1.2.1 From 9f470b3484dfefd721a47be889938152eb0c64b3 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 4 May 2003 10:34:19 +0000 Subject: Document usage of raw directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1305 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 70627b8f0..2f55e155c 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -54,6 +54,12 @@ Setting/Config Entry Description --documentclass Specify latex documentclass, *but* beaware that books have chapters articles not. (default: "article"). +--------------------- ------------------------------------------------ +--stylesheet Specify a stylesheet file. The file will be + ``input`` by latex in the document header. + If this is set to "" disables generation of + input latex command. + (default: "style.tex"). ===================== ================================================ @@ -97,9 +103,47 @@ docinfowidth The width for the docinfo table. Missing options --------------- -* Selection of latex documentclass and fontsize. +* Selection of latex fontsize. * Assumed reST linelength for table width setting. +Commands directly to LaTeX +========================== + +By means of the reST-raw directive one can give commands directly to +LaTeX, e.g. forcing a page break:: + + .. raw:: latex + + \newpage + + +Or setting formulas in LaTeX:: + + .. raw:: latex + + $$x^3 + 3x^2a + 3xa^2 + a^3,$$ + + +Or making a colorbox: If someone wants to get a red background for a textblock, +she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in +reStructuredText do something like this:: + + |begincolorbox| + Nobody expects the spanish inquisition. + |endcolorbox| + + .. |begincolorbox| raw:: latex + + \\begin{center} + \\colorbox{bg}{ + \\parbox{0.985\\linewidth}{ + + .. |endcolorbox| raw:: latex + + }} + \\end{center} + + Problems ======== @@ -137,6 +181,7 @@ Tables Miscellaneous ------------- +* recongize LaTeX (or even latex) and replace by ```\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. * Sidebar handling. -- cgit v1.2.1 From e95205d5c5b9aef0c7742a47e4c97213e844dffd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 9 May 2003 13:06:43 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1307 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 304 +++++++++++++++++++++++++++++++++++++++++++- docs/ref/docutils.dtd | 9 ++ docs/ref/rst/directives.txt | 23 +++- 3 files changed, 326 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 875237352..de8030b5f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,6 +45,12 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. +* Configuration files (~/.docutils or /etc/docutils.conf or + test/docutils.conf) affect any test suites that use + docutils.core.Publisher (test/test_writers). For example, setting + the default language causes changes in the output. (Reported by + Ludger Humbert.) + General ------- @@ -58,7 +64,7 @@ General checked for correctness and refactored. I'm afraid it's a bit of a spaghetti mess now. -* Add validation? See http://pytrex.sourceforge.net, RELAX NG. +* 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 @@ -308,6 +314,58 @@ General reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output? +* Non-ASCII text in system messages cause a traceback. On 2003-02-10, + I replied to Adam Chodorowski: + + It's the diagnostic output that's causing the problem. There's + a markup error on a section title that includes an accented + character. A system message which includes a non-ASCII + character is being sent to sys.stderr. Python believes your + sys.stderr can't handle anything other than ASCII, and + complains loudly. + + If your sys.stderr *can* handle Latin-1 output, telling Python + about it may help. I'm not sure how to tell Python though -- + perhaps via the default encoding in site.py? + + I'm not sure how to fix this, if it should be fixed, or even if + anything is really broken. If I'm processing encoded text from + an ASCII-only console, what kind of error output *should* I + get? Should Docutils prevent non-ASCII output from being + written to sys.stderr? Whose responsibility is it to set up + the stderr environment for encoded output? + + We could write all error output with + ``encodings.raw_unicode_escape.StreamWriter(sys.stderr).write()``, + but that's kind of drastic. It means that all systems, even + those that are encoding-aware, would get dumbed-down (and not + easily deciphered) error output. + + Adam replied: + + The assumption should, IMHO, be that the user's terminal can + handle the encoding that the file is in. I mean, the user most + likely worked with the file (perhaps a textmode editor, or + 'less', or 'cat', or...) in the terminal, so it seems a good + bet. I would think this is true for 99% of the cases. + + In some other, eg. where you are processing a lot of + documentation in different encodings on the same machine + (eg. documentation for some software or whatever) the user is + also probably more equipped to handle the problems. In any + case, saying that "the error output will be in the same + encoding as the input file" would simplify it a lot in this + scenario too (you can make sane build scripts)... + + I'm not sure that I agree with this. Ideas and discussion are welcome. + + Perhaps Docutils should grow an --error-encoding option. Docutils + could use it to tell Python how to encode sys.stderr. + +* Perhaps we need to re-evaluate the config file format, possibly + enabling a section for each Docutils component so that (for example) + HTML's and LaTeX's stylesheets don't interfere with each other. + Documentation ------------- @@ -356,6 +414,14 @@ Specification See Doc-SIG from 2001-06-19/20. +Web Site +```````` + +* Add an "examples" directory, beside "tools" and "docs", for + interesting examples of Docutils usage? Have a top-level README.txt + file and a subdirectory for each example. (Martin Blais) + + Python Source Reader -------------------- @@ -478,7 +544,9 @@ __ rst/alternatives.html#or-not-to-do contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. -* In target URLs, it would be useful to not explicitly specify the +* .. _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 @@ -486,7 +554,9 @@ __ rst/alternatives.html#or-not-to-do .. _Another Document: another.* - Should the choice be from among existing files only? + 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. @@ -701,6 +771,49 @@ __ rst/alternatives.html#or-not-to-do * Generalize the "target-notes" directive into a command-line option somehow? See docutils-develop 2003-02-13. +* Include (after any necessary cleanup & completion) David Priest's + substitution table for character entities; see + <http://article.gmane.org/gmane.comp.python.documentation/432>. + +* 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. (":recto:" & ":verso:" + options, or ":before: recto/verso" would add 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. Some may react strangely. + + 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). + +* Could the "break" concept above be extended to inline forms? + E.g. "^L" in the middle of a sentence could cause a line break. + Directives `````````` @@ -777,6 +890,10 @@ when used in a document. - _`misc.include`: "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? + * 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 @@ -827,6 +944,67 @@ when used in a document. (enclosing? preceding? following?). See docutils-develop 2003-01-29. + Idea: if the "class" directive has no content, it applies to the + enclosing element; useful for structural elements & containers + (sections, block quotes, etc.). With content, it applies to the + content; useful for body elements (paragraphs, lists, etc.). + + - _`misc.settings`: Set any Docutils runtime setting from within a + document? + + - 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?) @@ -976,6 +1154,57 @@ when used in a document. 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. @@ -1080,7 +1309,31 @@ elements. actual formatting. But what's the doctree element? Shall we introduce an arbitrary - "span" element? Put "interpreted" back for such purposes? + <span>-like element? Put "interpreted" back for such purposes? I + currently like "phrase". But: + + ...my penny on <span>: I think <span> is inherently evil. More + than enough I learned to hate <span> because some HTML pages are + full of it and it is a pain to translate them to a useful + format. + + I think <span> is an indication that you don't have a concept + for what you want to express. <span> is totally unrelated to the + *real* structure of the information and introduces more or less + a new language. I think this should be prevented. + + -- Stefan Merten + + Lesser of two evils? + +* Perhaps a "role" directive can modify existing roles with + attributes? :: + + .. :api-ti: role:: api + :base: twisted.internet + + To start the reactor, use the :api-ti:`reactor.run` method. To + stop it, use :api-ti:`reactor.stop`. * Implement roles: @@ -1096,6 +1349,8 @@ elements. What to do with an undefined acronym or abbreviation? + - "superscript" and "subscript" (synonyms "sup" and "sub"). + - "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 @@ -1192,6 +1447,21 @@ 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). + Filtering System Messages ````````````````````````` @@ -1220,6 +1490,25 @@ HTML Writer somehow, especially the docinfo fields. Part of the ht2html implementation? Generic component output? + I think a separate writer which inherits from html4css1.py would be + a good start. An "inline" or body-only HTML writer has to omit some + of the information given by the full HTML writer. Some applications + won't need this information, but others will; they'll want to deal + with it in different ways. I envision such a writer returning a set + of values: body html, and everything else (metadata). Perhaps a + tuple of this form:: + + (body_html, {'title': value, + 'subtitle': value, + 'docinfo': (tuple of (name, value) pairs), + etc.}) + + By having a separate writer, a different return data structure is + possible. We may need to add support to all of docutils to allow + for this variant output. Should the metadata values be simple text + strings, or HTML snippets (they may contain markup), or both? There + may be other issues to be worked out. + * Add more support for <link> elements, especially for navigation bars. @@ -1235,6 +1524,9 @@ HTML Writer * 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? + Front-End Tools --------------- @@ -1327,8 +1619,8 @@ originators of Ogg Vorbis) put it well when he said: over your codebase, and that's okay with us. -Coding Conventions ------------------- +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 diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 162cf212c..3fec9ed4e 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -536,6 +536,15 @@ following caveats: <!ELEMENT acronym %text.model;> <!ATTLIST acronym %basic.atts;> +<!ELEMENT superscript %text.model;> +<!ATTLIST superscript %basic.atts;> + +<!ELEMENT subscript %text.model;> +<!ATTLIST subscript %basic.atts;> + +<!ELEMENT phrase %text.model;> +<!ATTLIST phrase %basic.atts;> + <!ELEMENT problematic %text.model;> <!ATTLIST problematic %basic.atts; diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 8f142f110..6dc607fed 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -215,12 +215,27 @@ option is recognized: Sets the "width" attribute of the "figure" doctree element. This option does not scale the included image; use the "width" - `image`_ option for that. - -.. [#] `Python Imaging Library`__. + `image`_ option for that. :: + + +---------------------------+ + | figure | + | | + |<------ figwidth --------->| + | | + | +---------------------+ | + | | image | | + | | | | + | |<--- width --------->| | + | +---------------------+ | + | | + |The figure's caption should| + |wrap at this width. | + +---------------------------+ + +.. [#] `Python Imaging Library`_. .. _PIL: -__ http://www.pythonware.com/products/pil/ +.. _Python Imaging Library: http://www.pythonware.com/products/pil/ --------------- -- cgit v1.2.1 From 0802d6cb2081a41881895dc539e9b909186e5afd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 9 May 2003 13:30:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1308 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index de8030b5f..fb6d2c760 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -780,15 +780,16 @@ __ rst/alternatives.html#or-not-to-do 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. (":recto:" & ":verso:" - options, or ":before: recto/verso" would add flexibility.) + 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. Some may react strangely. + 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:: @@ -810,6 +811,8 @@ __ rst/alternatives.html#or-not-to-do 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. -- cgit v1.2.1 From 4ae10b376895ed23eab830ead2e83c056bb078bc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 9 May 2003 14:02:10 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1309 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fb6d2c760..36b234a22 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -57,8 +57,8 @@ General * Refactor - - Rename methods & variables according to the `coding conventions`_ - below. + - Rename methods & variables according to the `Python coding + conventions`_ below. - 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 @@ -1161,7 +1161,7 @@ when used in a document. 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: + doctree fragment:: <literal_block xml:space="preserve"> print 'This is Python code.' @@ -1169,18 +1169,18 @@ when used in a document. print i </literal_block> - into something like this ("</>" is end-tag shorthand): + 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>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": + example rewritten using the generic "phrase":: <literal_block xml:space="preserve" class="python"> <phrase class="keyword">print</> <phrase -- cgit v1.2.1 From 4a7db2bf5beadfb56f80a5f2a1d015188a8c43d2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 May 2003 02:25:09 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1310 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 36b234a22..40f96858e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -955,6 +955,13 @@ when used in a document. - _`misc.settings`: Set any Docutils runtime setting from within a document? + - _`misc.unicode`: Convert one or more numerical character codes + (decimal, or hex if it begins with ``0x`` or ``\u``) to a Unicode + character. Behave like "replace", for character entity + substitution definitions, e.g.:: + + .. |mdash| unicode:: \u2014 + - 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 @@ -1147,6 +1154,10 @@ when used in a document. 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. + - _`admonitions.admonition`: Generic, titled admonition. Use author-supplied title as "class" attribute value? @@ -1294,7 +1305,8 @@ elements. .. _multiple roles: rst/alternatives.html#multiple-roles-in-interpreted-text -* Add document-local role bindings, associating directives with roles? +* Add document-local _`role bindings`, associating directives with + roles? ``She wore ribbons in her hair and it lay with streaks of grey``:rewrite: @@ -1311,9 +1323,18 @@ elements. stylesheet would then pick up on the "class" attribute to do the actual formatting. + The same thing could be done with a directive, albeit a bit more + verbosely:: + + .. role:: rewrite + :class: rewrite + + The advantage of the new syntax would be flexibility. Uses other + than "class" may present themselves. + But what's the doctree element? Shall we introduce an arbitrary <span>-like element? Put "interpreted" back for such purposes? I - currently like "phrase". But: + currently like "phrase". "inline" may be better. But: ...my penny on <span>: I think <span> is inherently evil. More than enough I learned to hate <span> because some HTML pages are @@ -1329,6 +1350,12 @@ elements. Lesser of two evils? +* Add new syntax for _`nested inline markup`? :: + + :role:[inline text] + + From a proposal by Paul Tremblay. + * Perhaps a "role" directive can modify existing roles with attributes? :: -- cgit v1.2.1 From 523163874bf547d3dd1c3c7f50c9210b5b503e0a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 May 2003 05:07:28 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1311 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 40f96858e..a5e990024 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1306,7 +1306,7 @@ elements. rst/alternatives.html#multiple-roles-in-interpreted-text * Add document-local _`role bindings`, associating directives with - roles? + roles? :: ``She wore ribbons in her hair and it lay with streaks of grey``:rewrite: -- cgit v1.2.1 From 815515eb9ab248a052166038a169c9dfdd74bf14 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 May 2003 06:28:20 +0000 Subject: Problem: line blocks and markup over multiple lines. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1312 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 2f55e155c..dda6d7826 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -181,6 +181,8 @@ Tables Miscellaneous ------------- +* line-blocks are set line wise, therfore markups e.g. emphasize + that run over line ends do not work. * recongize LaTeX (or even latex) and replace by ```\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. -- cgit v1.2.1 From 5ff4290ce25679a3dd409045b0173d53fd4bea2d Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 May 2003 06:40:39 +0000 Subject: Fix command line comment in the code and add the option to the documentation. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1313 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index dda6d7826..4987700a4 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -60,6 +60,10 @@ Setting/Config Entry Description If this is set to "" disables generation of input latex command. (default: "style.tex"). +--------------------- ------------------------------------------------ +--footnote-references Format for footnote references: one of + "superscript" or "brackets". + Default is "brackets". ===================== ================================================ -- cgit v1.2.1 From 03cf86d015ae45537eeb9da08862610708b7347b Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 May 2003 07:44:12 +0000 Subject: * add a LaTeX-nbsp (~) before a LaTeX-newline to avoid "LaTeX-Error no line to end here". * line_blocks without use of mbox, to allow markups span over line ends. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1314 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 4987700a4..0bc46d375 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -185,8 +185,6 @@ Tables Miscellaneous ------------- -* line-blocks are set line wise, therfore markups e.g. emphasize - that run over line ends do not work. * recongize LaTeX (or even latex) and replace by ```\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. -- cgit v1.2.1 From 33fd775a0dc4b3a52d5fca6a4d18d8fea366bfec Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 May 2003 03:55:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1318 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a5e990024..88eed33d9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -816,6 +816,40 @@ __ rst/alternatives.html#or-not-to-do * 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. Directives @@ -1842,6 +1876,9 @@ create their own 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:: @@ -1872,6 +1909,8 @@ 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: -- cgit v1.2.1 From 46036e5c6c36075ada2610ae1582354cec8e31cc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 May 2003 04:21:22 +0000 Subject: markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1320 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 88eed33d9..c5cdf5b9a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -837,14 +837,14 @@ __ rst/alternatives.html#or-not-to-do 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 "::": + 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: + begin without a newline after the "::"? Example:: :: while True: print 'hello world' -- cgit v1.2.1 From 776fa1e839b809608473c8270f23f33a48af5e22 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:49:39 +0000 Subject: Added "sidebar", "rubric", "attribution", "admonition", "superscript", "subscript", and "inline" elements. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1337 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 3fec9ed4e..06fe4bf55 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -116,11 +116,11 @@ resolve to either an internal or external reference. <!ENTITY % additional.body.elements ""> <!ENTITY % body.elements " paragraph | literal_block | doctest_block | line_block | block_quote - | table | figure | image | footnote | citation + | table | figure | image | footnote | citation | rubric | bullet_list | enumerated_list | definition_list | field_list | option_list | attention | caution | danger | error | hint | important | note - | tip | warning + | tip | warning | admonition | target | substitution_definition | comment | pending | system_message | raw %additional.body.elements; "> @@ -130,8 +130,8 @@ resolve to either an internal or external reference. " emphasis | strong | literal | reference | footnote_reference | citation_reference | substitution_reference | title_reference - | abbreviation | acronym - | problematic | generated + | abbreviation | acronym | subscript | superscript + | inline | problematic | generated | target | image | raw %additional.inline.elements; "> @@ -368,9 +368,12 @@ or " ") or the text between option arguments (typically either "," or %basic.atts; %fixedspace.att;> -<!ELEMENT block_quote (%body.elements;)+> +<!ELEMENT block_quote ((%body.elements;)+, attribution?)> <!ATTLIST block_quote %basic.atts;> +<!ELEMENT attribution %text.model;> +<!ATTLIST attribution %basic.atts;> + <!ELEMENT doctest_block %text.model;> <!ATTLIST doctest_block %basic.atts; @@ -403,6 +406,9 @@ or " ") or the text between option arguments (typically either "," or <!ELEMENT warning (%body.elements;)+> <!ATTLIST warning %basic.atts;> +<!ELEMENT admonition (title, (%body.elements;)+)> +<!ATTLIST admonition %basic.atts;> + <!ELEMENT footnote (label?, (%body.elements;)+)> <!ATTLIST footnote %basic.atts; @@ -417,6 +423,9 @@ or " ") or the text between option arguments (typically either "," or <!ELEMENT label (#PCDATA)> <!ATTLIST label %basic.atts;> +<!ELEMENT rubric %text.model;> +<!ATTLIST rubric %basic.atts;> + <!-- Empty except when used as an inline element. --> <!ELEMENT target %text.model;> <!ATTLIST target @@ -542,8 +551,8 @@ following caveats: <!ELEMENT subscript %text.model;> <!ATTLIST subscript %basic.atts;> -<!ELEMENT phrase %text.model;> -<!ATTLIST phrase %basic.atts;> +<!ELEMENT inline %text.model;> +<!ATTLIST inline %basic.atts;> <!ELEMENT problematic %text.model;> <!ATTLIST problematic -- cgit v1.2.1 From b84157853aab34be40f1668f0bdecfe7ec503c36 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:50:07 +0000 Subject: Added directives: "admonition", "rubric", "epigraph", "highlights", "unicode" and "class". Added "class" options to "topic", "sidebar", "line-block", "parsed-literal", "contents", and "image"; and "figclass" to "figure". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1338 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 247 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 233 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6dc607fed..0dfb52337 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -44,10 +44,13 @@ type definition. Admonitions ------------- +Specific Admonitions +==================== + :Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning" + "important", "note", "tip", "warning", "admonition" :Doctree Elements: attention, caution, danger, error, hint, important, - note, tip, warning + note, tip, warning, admonition, title :Directive Arguments: None. :Directive Options: None. :Directive Content: Interpreted as body elements. @@ -95,6 +98,43 @@ bullet list consisting of two list items:: - It includes this bullet list. +Generic Admonition +================== + +:Directive Type: "admonition" +:Doctree Elements: admonition, title +:Directive Arguments: One, required (admonition title) +:Directive Options: Possible. +:Directive Content: Interpreted as body elements. + +This is a generic, titled admonition. The title may be anything the +author desires. + +The author-supplied title is also used as a "class" attribute value +after being converted into a valid identifier form (down-cased; +non-alphanumeric characters converted to single hyphens; "admonition-" +prefixed). For example, this admonition:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +becomes the following document tree (pseudo-XML):: + + <document source="test data"> + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + +The following option is recognized: + +``class`` : text + Override the computed "class" attribute value. See the class_ + directive below. + + -------- Images -------- @@ -162,6 +202,10 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. +``class`` : text + Set a "class" attribute value on the image element. See the + class_ directive below. + Figure ====== @@ -203,7 +247,7 @@ legend. To specify a legend without a caption, use an empty comment The "figure" directive supports all of the options of the "image" directive (see `image options`_ above). In addition, the following -option is recognized: +options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space @@ -232,6 +276,10 @@ option is recognized: |wrap at this width. | +---------------------------+ +``figclass`` : text + Set a "class" attribute value on the figure element. See the + class_ directive below. + .. [#] `Python Imaging Library`_. .. _PIL: @@ -248,7 +296,7 @@ Topic :Directive Type: "topic" :Doctree Element: topic :Directive Arguments: 1, required (topic title). -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Interpreted as the topic body. A topic is like a block quote with a title, or a self-contained @@ -267,6 +315,12 @@ interpreted as body elements. For example:: the body of the topic, and are interpreted as body elements. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the topic element. See the + class_ directive below. + Sidebar ======= @@ -274,7 +328,7 @@ Sidebar :Directive Type: "sidebar" :Doctree Element: sidebar :Directive Arguments: One, required (sidebar title). -:Directive Options: Possible; optional subtitle. +:Directive Options: Possible. :Directive Content: Interpreted as the sidebar body. Sidebars are like miniature, parallel documents that occur inside @@ -299,11 +353,15 @@ interpreted as body elements. For example:: the body of the sidebar, and are interpreted as body elements. -The following option is recognized: +The following options are recognized: ``subtitle`` : text The sidebar's subtitle. +``class`` : text + Set a "class" attribute value on the sidebar element. See the + class_ directive below. + Line Block ========== @@ -311,7 +369,7 @@ Line Block :Directive Type: "line-block" :Doctree Element: line_block :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Becomes the body of the line block. The "line-block" directive constructs an element where whitespace @@ -335,6 +393,12 @@ example, here's a classic:: as soon as it comes. Love, Ewan. +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the line_block element. See the + class_ directive below. + Parsed Literal Block ==================== @@ -342,7 +406,7 @@ Parsed Literal Block :Directive Type: "parsed-literal" :Doctree Element: literal_block :Directive Arguments: None. -:Directive Options: None. +:Directive Options: Possible. :Directive Content: Becomes the body of the literal block. Unlike an ordinary literal block, the "parsed-literal" directive @@ -364,6 +428,76 @@ For example, all the element names in this content model are links:: decoration_?, `%structure.model;`_) +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the literal_block element. See + the class_ directive below. + + +Rubric +====== + +:Directive Type: "rubric" +:Doctree Element: rubric +:Directive Arguments: 1, required (rubric text). +:Directive Options: Possible. +:Directive Content: None. + + rubric n. 1. a title, heading, or the like, in a manuscript, + book, statute, etc., written or printed in red or otherwise + distinguished from the rest of the text. ... + + -- Random House Webster's College Dictionary, 1991 + +The "rubric" directive inserts a "rubric" element into the document +tree. A rubric is like an informal heading that doesn't correspond to +the document's structure. + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the rubric element. See the + class_ directive below. + + +Epigraph +======== + +:Directive Type: "epigraph" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces an epigraph-class block quote. For example, this input:: + + .. epigraph:: + + No matter where you go, there you are. + + -- Buckaroo Banzai + +becomes this document tree fragment:: + + <block_quote class="epigraph"> + <paragraph> + No matter where you go, there you are. + <attribution> + Buckaroo Banzai + + +Highlights +======== + +:Directive Type: "highlights" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces a highlights-class block quote. See Epigraph_ above. + ---------------- Document Parts @@ -416,14 +550,20 @@ The following options are recognized: ``depth`` : integer The number of section levels that are collected in the table of contents. The default is unlimited depth. + ``local`` : flag (empty) Generate a local table of contents. Entries will only include subsections of the section in which the directive is given. If no explicit title is given, the table of contents will not be titled. + ``backlinks`` : "entry" or "top" or "none" Generate links from section headers back to the table of contents entries, the table of contents itself, or generate no backlinks. +``class`` : text + Set a "class" attribute value on the topic element. See the + class_ directive below. + Automatic Section Numbering =========================== @@ -618,7 +758,7 @@ Raw Data Pass-Through ===================== :Directive Type: "raw" -:Doctree Element: pending +:Doctree Element: raw :Directive Arguments: One, required (output format type). :Directive Options: Possible. :Directive Content: Stored verbatim, uninterpreted. None (empty) if a @@ -626,10 +766,9 @@ Raw Data Pass-Through The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The name of the output format is -given in the first argument. During the initial parse, a "pending" -element is generated which acts as a placeholder, storing the format -and raw data internally. The interpretation of the code is up to the -Writer. A Writer may ignore any raw output not matching its format. +given in the first argument. The interpretation of the raw data is up +to the Writer. A Writer may ignore any raw output not matching its +format. For example, the following input would be passed untouched by an HTML Writer:: @@ -664,7 +803,7 @@ Replacement Text ================ :Directive Type: "replace" -:Doctree Element: pending +:Doctree Element: Text & inline elements :Directive Arguments: None. :Directive Options: None. :Directive Content: A single paragraph; may contain inline markup. @@ -689,6 +828,86 @@ the "replace" directive:: .. _Python: http://www.python.org/ +Unicode Character Codes +======================= + +:Directive Type: "unicode" +:Doctree Element: Text +:Directive Arguments: One or more, required (Unicode character codes + & text). +:Directive Options: None. +:Directive Content: None. + +The "unicode" directive converts Unicode character codes (numerical +values) to characters, and may be used in substitution definitions +only. Codes may be decimal numbers, hexadecimal numbers (prefixed by +``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numbered +character entities (e.g. ``ᨫ``). Codes may be upper- or +lowercase. Spaces are ignored, and any other text remains as-is. + +Example:: + + "|copy|" is the copyright symbol. + + .. |copy| unicode:: 0xA9 + + +Class +===== + +:Directive Type: "class" +:Doctree Element: pending +:Directive Arguments: One, required (class name / attribute value). +:Directive Options: None. +:Directive Content: None. + +The "class" directive sets a "class" attribute value on the first +immediately following non-comment element [#]_. For details of the +"class" attribute, see `its entry`__ in `The Docutils Document Tree`_. +The "class" attribute value is converted to lowercase and all +non-alphanumeric characters are converted to hyphens in order to match +this regular expression: ``[a-z](-?[a-z0-9]+)*``. See the docstring +from ``docutils.nodes.make_id`` for the rationale. + +Examples:: + + .. class:: special + + This is a "special" paragraph. + + .. class:: exceptional + + An Exceptional Section + ====================== + + This is an ordinary paragraph. + +The text above is parsed and transformed into this doctree fragment:: + + <paragraph class="special"> + This is a "special" paragraph. + <section class="exceptional"> + <title> + An Exceptional Section + <paragraph> + This is an ordinary paragraph. + +.. [#] To set a "class" attribute value on a block quote, the "class" + directive must be followed by an empty comment:: + + .. class:: highlights + .. + + Block quote text. + + The directive doesn't allow content, therefore an empty comment is + required to terminate the directive. Without the empty comment, + the block quote text would be interpreted as the "class" + directive's content, and the parser would complain. + +__ ../doctree.html#class + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From e8c6ddb8ee857e0387997db70b0786243465b84b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:54:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1340 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/problems.txt | 3 +- docs/dev/todo.txt | 72 ++++++++++----- docs/ref/doctree.txt | 186 +++++++++++++++++++++++++++++++------- docs/ref/rst/restructuredtext.txt | 12 ++- docs/ref/transforms.txt | 2 + 5 files changed, 214 insertions(+), 61 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index cead7b5b8..15d975198 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -473,8 +473,7 @@ documentation. Alternatives: could mean multi-line rows, and no bullet list means single-line rows only. -Alternative #1 has been adopted by reStructuredText. Alternatives 3-6 -are under consideration. +Alternatives 1 and 5 has been adopted by reStructuredText. Delimitation of Inline Markup diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c5cdf5b9a..8afecd24d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -851,6 +851,26 @@ __ rst/alternatives.html#or-not-to-do Perhaps. Perhaps not. +* Add attribution parsing to block quotes? Iff the last paragraph + [#]_ begins with "--", it becomes an attribution. This goes back to + Paul Moore's initial "Using blockquote element for quotes" post + (docutils-users 2003-04-18). Example:: + + Structured text is really a great idea for certain situations; + reST is a much better implementation of the idea than any + versions I've seen before. + + -- Guido van Rossum on Python-Dev, 2002-04-04 + + .. [#] Also check for a final definition list with one item, whose + term begins with "--"? If an attribution wraps, it may be + formatted like this:: + + A quote. + + -- An attribution + more info here + Directives `````````` @@ -863,11 +883,13 @@ when used in a document. * Use the language module for directive option names? +* Add "substitution_only" and "substitution_ok" function attributes, + and automate context checking? + * Implement options on existing directives: - - Add a "class" option to many/most directives, to set an arbitrary - "class" attribute on the enclosing element (see `misc.class`_)? - Perhaps "name" as well? + - Add a "name" option to directives, to set an author-supplied + identifier? - _`images.image`: "border"? "link"? @@ -977,25 +999,9 @@ when used in a document. problem similar to the first problem listed for misc.encoding_, although to a lesser degree. - - _`misc.class`: Specify a "class" attribute value to an element - (enclosing? preceding? following?). See docutils-develop - 2003-01-29. - - Idea: if the "class" directive has no content, it applies to the - enclosing element; useful for structural elements & containers - (sections, block quotes, etc.). With content, it applies to the - content; useful for body elements (paragraphs, lists, etc.). - - _`misc.settings`: Set any Docutils runtime setting from within a document? - - _`misc.unicode`: Convert one or more numerical character codes - (decimal, or hex if it begins with ``0x`` or ``\u``) to a Unicode - character. Behave like "replace", for character entity - substitution definitions, e.g.:: - - .. |mdash| unicode:: \u2014 - - 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 @@ -1192,9 +1198,6 @@ when used in a document. internal section structure, with adornment styles independent of the main document. - - _`admonitions.admonition`: Generic, titled admonition. Use - author-supplied title as "class" attribute value? - - _`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" @@ -1339,6 +1342,15 @@ elements. .. _multiple roles: rst/alternatives.html#multiple-roles-in-interpreted-text +* 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 + * Add document-local _`role bindings`, associating directives with roles? :: @@ -1384,11 +1396,23 @@ elements. Lesser of two evils? -* Add new syntax for _`nested inline markup`? :: +* Add new syntax for _`nested inline markup`? From a proposal by Paul + Tremblay:: :role:[inline text] - From a proposal by Paul Tremblay. + Or extend the parser to parse nested interpreted text? :: + + :emphasis:`Some emphasized text with :strong:`some more + emphasized text` in it and **perhaps** :reference:`a link`` + + See the docutils-users `"nested inline tags" thread`__ and earlier + discussions + (http://mail.python.org/pipermail/doc-sig/2001-November/002388.html + and + http://mail.python.org/pipermail/doc-sig/2001-November/002363.html). + + __ http://sf.net/mailarchive/forum.php?thread_id=2073680&forum_id=11444 * Perhaps a "role" directive can modify existing roles with attributes? :: diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index baa45d04e..285bb9c98 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -140,12 +140,13 @@ Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound. -Category members: attention_, block_quote_, bullet_list_, caution_, -citation_, comment_, danger_, definition_list_, doctest_block_, -enumerated_list_, error_, field_list_, figure_, footnote_, hint_, -image_, important_, line_block_, literal_block_, note_, option_list_, -paragraph_, pending_, raw_, substitution_definition_, -system_message_, table_, target_, tip_, warning_ +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, comment_, danger_, definition_list_, +doctest_block_, enumerated_list_, error_, field_list_, figure_, +footnote_, hint_, image_, important_, line_block_, literal_block_, +note_, option_list_, paragraph_, pending_, raw_, rubric_, +substitution_definition_, system_message_, table_, target_, tip_, +warning_ Simple Body Elements @@ -156,8 +157,8 @@ that contain text data may also contain inline elements. Such elements therefore have a "mixed content model". Category members: comment_, doctest_block_, image_, line_block_, -literal_block_, paragraph_, pending_, raw_, substitution_definition_, -target_ +literal_block_, paragraph_, pending_, raw_, rubric_, +substitution_definition_, target_ Compound Body Elements @@ -166,9 +167,9 @@ Compound Body Elements Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data. -Category members: attention_, block_quote_, bullet_list_, caution_, -citation_, danger_, definition_list_, enumerated_list_, error_, -field_list_, figure_, footnote_, hint_, important_, note_, +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, danger_, definition_list_, enumerated_list_, +error_, field_list_, figure_, footnote_, hint_, important_, note_, option_list_, system_message_, table_, tip_, warning_ @@ -182,8 +183,8 @@ elements (containing text data, like field_name_). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.). -Category members (simple): caption_, classifier_, colspec_, -field_name_, label_, option_argument_, option_string_, term_ +Category members (simple): attribution_, caption_, classifier_, +colspec_, field_name_, label_, option_argument_, option_string_, term_ Category members (compound): definition_, definition_list_item_, description_, entry_, field_, field_body_, legend_, list_item_, @@ -199,9 +200,9 @@ further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model". Category members: abbreviation_, acronym_, citation_reference_, -emphasis_, footnote_reference_, generated_, image_, literal_, -problematic_, reference_, strong_, substitution_reference_, target_, -title_reference_, raw_ +emphasis_, footnote_reference_, generated_, image_, inline_, literal_, +problematic_, reference_, strong_, subscript_, +substitution_reference_, superscript_, target_, title_reference_, raw_ .. _HTML: http://www.w3.org/MarkUp/ @@ -340,7 +341,6 @@ Content Model ``address``. - Examples -------- @@ -366,13 +366,79 @@ See docinfo_ for a more complete example, including processing context. +``admonition`` +============== + +This element is a generic, titled admonition. Also see the specific +admonition elements Docutils offers (in alphabetical order): caution_, +danger_, error_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``admonition``. + +:Children: + ``admonition`` elements begin with a title_ and may contain one or + more `body elements`_. + +:Analogues: + ``admonition`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.). + + +Content Model +------------- + +.. parsed-literal:: + + (title_, (`%body.elements;`_)+) + +:Attributes: + The ``admonition`` element contains only the `common attributes`_: + id_, name_, dupname_, source_, and class_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``admonition``. The `%structure.model;`_ parameter entity + indirectly includes ``admonition``. + + +Examples +-------- + +reStructuredText source:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +Pseudo-XML_ fragment from simple parsing:: + + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + + ``attention`` ============= The ``attention`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): caution_, danger_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -429,6 +495,12 @@ Pseudo-XML_ fragment from simple parsing:: All your base are belong to us. +``attribution`` +=============== + +`To be completed`_. + + ``author`` ========== @@ -586,7 +658,8 @@ Details may contain ``block_quote``. :Children: - ``block_quote`` elements may contain `body elements`_. + ``block_quote`` elements contain `body elements`_ followed by an + optional attribution_ element. :Analogues: ``block_quote`` is analogous to the "blockquote" element in both @@ -602,7 +675,7 @@ Content Model .. parsed-literal:: - (`%body.elements;`_)+ + ((`%body.elements;`_)+, attribution_?) :Attributes: The ``block_quote`` element contains only the `common @@ -730,7 +803,7 @@ See list_item_ for another example. The ``caution`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, danger_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -1021,7 +1094,7 @@ context. The ``danger`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, error_, -hint_, important_, note_, tip_, warning_. +hint_, important_, note_, tip_, warning_, and the generic admonition_. Details @@ -1856,7 +1929,8 @@ See list_item_ for another example. The ``error`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, hint_, important_, note_, tip_, warning_. +danger_, hint_, important_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2277,7 +2351,8 @@ None. The ``hint`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, important_, note_, tip_, warning_. +danger_, error_, important_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2346,7 +2421,8 @@ Pseudo-XML_ fragment from simple parsing:: The ``important`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, note_, tip_, warning_. +danger_, error_, hint_, note_, tip_, warning_, and the generic +admonition_. Details @@ -2418,6 +2494,12 @@ Pseudo-XML_ fragment from simple parsing:: Call your mother. +``inline`` +========== + +`To be completed`_. + + ``label`` ========= @@ -2686,7 +2768,8 @@ Pseudo-XML_ fragment from simple parsing:: The ``note`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, tip_, warning_. +danger_, error_, hint_, important_, tip_, warning_, and the generic +admonition_. Details @@ -3299,6 +3382,21 @@ context. `To be completed`_. +``rubric`` +========== + + rubric n. 1. a title, heading, or the like, in a manuscript, + book, statute, etc., written or printed in red or otherwise + distinguished from the rest of the text. ... + + -- Random House Webster's College Dictionary, 1991 + +A rubric is like an informal heading that doesn't correspond to the +document's structure. + +`To be completed`_. + + ``section`` =========== @@ -3549,6 +3647,12 @@ context. `To be completed`_. +``subscript`` +============= + +`To be completed`_. + + ``substitution_definition`` =========================== @@ -3630,6 +3734,12 @@ structural element (document), the subsection's ``id`` and ``name`` attributes are stored in the ``subtitle`` element. +``superscript`` +=============== + +`To be completed`_. + + ``system_message`` ================== @@ -3718,7 +3828,7 @@ classifier_ elements. The ``tip`` element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention_, caution_, danger_, error_, hint_, -important_, note_, warning_. +important_, note_, warning_, and the generic admonition_. Details @@ -3778,7 +3888,7 @@ Pseudo-XML_ fragment from simple parsing:: ========= The ``title`` element stores the title of a document_, section_, -topic_, or sidebar_. +topic_, sidebar_, or generic admonition_. Details @@ -3789,7 +3899,7 @@ Details :Parents: The following elements may contain ``title``: document_, section_, - topic_, sidebar_ + topic_, sidebar_, admonition_ :Children: ``title`` elements may contain text data plus `inline elements`_. @@ -4215,10 +4325,20 @@ The ``bullet`` attribute is used in the bullet_list_ element. `Attribute type`_: ``NMTOKENS``. Default value: none. The ``class`` attribute contains one or more names used to classify an -element. It can be used to carry context forward between a Docutils -Reader and Writer, when a custom structure is reduced to a -standardized document tree. ``class`` is one of the `common -attributes`_, shared by all Docutils elements. +element. The purpose of the attribute is to indicate an "is-a" +variant relationship, to allow an extensible way of defining +sub-classes of existing elements. It can be used to carry context +forward between a Docutils Reader and Writer, when a custom structure +is reduced to a standardized document tree. One common use is in +conjunction with stylesheets, to add selection criteria. It should +not be used to carry formatting instructions or arbitrary content. + +The ``class`` attribute's contents should be ignorable. Writers that +are not familiar with the variant expressed should be able to ignore +the attribute. + +``class`` is one of the `common attributes`_, shared by all Docutils +elements. ``delimiter`` diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 09ae893f7..f4c09c1c9 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -137,7 +137,7 @@ Here are examples of `body elements`_: This theory, that is mine, is mine. - Anne Elk (Miss) + -- Anne Elk (Miss) - `Doctest blocks`_:: @@ -1098,7 +1098,7 @@ Syntax diagram:: Block Quotes ------------ -Doctree element: block_quote. +Doctree element: block_quote, attribution. A text block that is indented relative to the preceding text, without markup indicating it to be a literal block, is a block quote. All @@ -1111,6 +1111,11 @@ within the block quote:: -- Sherlock Holmes +If the final block of a block quote begins with "--" (flush left +within the block quote), it is interpreted as an attribution. If the +attribution consists of multiple lines, the left edges of the second +and subsequent lines must align. + Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote. @@ -1123,6 +1128,9 @@ Syntax diagram:: +---------------------------+ | block quote | | (body elements)+ | + | | + | -- attribution text | + | (optional) | +---------------------------+ diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 7874bca3a..4c5fe135a 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -24,6 +24,8 @@ Transforms Listed in Priority Order ============================== ============================ ======== Transform: module.Class Added By Priority ============================== ============================ ======== +misc.class "class" (d/p) 210 + references.Substitutions standalone (r), pep (r) 220 frontmatter.DocTitle standalone (r) 320 -- cgit v1.2.1 From 01e6459e01ffcd8cad09a6efaa169f164fc31df0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 20:57:15 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1341 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0dfb52337..49eaca399 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -488,7 +488,7 @@ becomes this document tree fragment:: Highlights -======== +========== :Directive Type: "highlights" :Doctree Element: block_quote -- cgit v1.2.1 From 5c5bd6ab687ef6831068f0487f4fc83175e2f498 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 21:18:48 +0000 Subject: correction git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1342 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 285bb9c98..ad1bf7d9f 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -705,8 +705,8 @@ Pseudo-XML_ fragment from simple parsing:: <block_quote> <paragraph> This theory, that is mine, is mine. - <paragraph> - -- Anne Elk (Miss) + <attribution> + Anne Elk (Miss) ``bullet_list`` -- cgit v1.2.1 From 47960d90cec5d956f914d4aa3321feb6019380ef Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 May 2003 21:45:20 +0000 Subject: update git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1343 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 24 +++--------------------- 1 file changed, 3 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8afecd24d..a277fcbba 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1365,9 +1365,9 @@ elements. worked out though. Syntax idea from Jeffrey C. Jacobs. The example above would implement the "rewrite" role as adding a - ``class="rewrite"`` attribute to the interpreted text. The - stylesheet would then pick up on the "class" attribute to do the - actual formatting. + ``class="rewrite"`` attribute to the interpreted text ("inline" + element). The stylesheet would then pick up on the "class" + attribute to do the actual formatting. The same thing could be done with a directive, albeit a bit more verbosely:: @@ -1378,24 +1378,6 @@ elements. The advantage of the new syntax would be flexibility. Uses other than "class" may present themselves. - But what's the doctree element? Shall we introduce an arbitrary - <span>-like element? Put "interpreted" back for such purposes? I - currently like "phrase". "inline" may be better. But: - - ...my penny on <span>: I think <span> is inherently evil. More - than enough I learned to hate <span> because some HTML pages are - full of it and it is a pain to translate them to a useful - format. - - I think <span> is an indication that you don't have a concept - for what you want to express. <span> is totally unrelated to the - *real* structure of the information and introduces more or less - a new language. I think this should be prevented. - - -- Stefan Merten - - Lesser of two evils? - * Add new syntax for _`nested inline markup`? From a proposal by Paul Tremblay:: -- cgit v1.2.1 From e3b4eed0806159df66495014d21d73123b05a72e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 26 May 2003 20:39:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1350 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index ad1bf7d9f..7f0c6cd6d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4600,10 +4600,11 @@ Entity definition: paragraph_ | literal_block_ | doctest_block_ | line_block_ | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_ + | rubric_ | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ | option_list_ | attention_ | caution_ | danger_ | error_ | hint_ | important_ - | note_ | tip_ | warning_ + | note_ | tip_ | warning_ | admonition_ | target_ | substitution_definition_ | comment_ | pending_ | system_message_ | raw_ %additional.body.elements; @@ -4612,11 +4613,11 @@ The ``%additional.body.elements;`` parameter entity can be used by wrapper DTDs to extend ``%body.elements;``. The ``%body.elements;`` parameter entity is directly employed in the -content models of the following elements: attention_, block_quote_, -caution_, citation_, danger_, definition_, description_, entry_, -error_, field_body_, footer_, footnote_, header_, hint_, important_, -legend_, list_item_, note_, sidebar_, system_message_, tip_, topic_, -warning_ +content models of the following elements: admonition_, attention_, +block_quote_, caution_, citation_, danger_, definition_, description_, +entry_, error_, field_body_, footer_, footnote_, header_, hint_, +important_, legend_, list_item_, note_, sidebar_, system_message_, +tip_, topic_, warning_ Via `%structure.model;`_, the ``%body.elements;`` parameter entity is indirectly employed in the content models of the document_ and @@ -4654,8 +4655,8 @@ Entity definition: emphasis_ | strong_ | literal_ | reference_ | footnote_reference_ | citation_reference_ | substitution_reference_ | title_reference_ - | abbreviation_ | acronym_ - | problematic_ | generated_ + | abbreviation_ | acronym_ | subscript_ | superscript_ + | inline_ | problematic_ | generated_ | target_ | image_ | raw_ %additional.inline.elements; @@ -4664,12 +4665,13 @@ wrapper DTDs to extend ``%inline.elements;``. Via `%text.model;`_, the ``%inline.elements;`` parameter entity is indirectly employed in the content models of the following elements: -abbreviation_, acronym_, address_, author_, caption_, classifier_, -contact_, copyright_, date_, doctest_block_, emphasis_, generated_, -line_block_, literal_block_, organization_, paragraph_, problematic_, -raw_, reference_, revision_, status_, strong_, -substitution_definition_, substitution_reference_, subtitle_, target_, -term_, title_, version_ +abbreviation_, acronym_, address_, attribution_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, inline_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, rubric_, +status_, strong_, subscript_, substitution_definition_, +substitution_reference_, subtitle_, superscript_, target_, term_, +title_, title_reference_, version_ ``%reference.atts;`` -- cgit v1.2.1 From 39cca0114ef4d89b91b2c213a673f3a8015d3f16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 May 2003 16:29:54 +0000 Subject: moved a bug into Bugs section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1355 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 96 +++++++++++++++++++++++++++---------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a277fcbba..b0cc2f901 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -51,6 +51,54 @@ Bugs the default language causes changes in the output. (Reported by Ludger Humbert.) +* Non-ASCII text in system messages cause a traceback. On 2003-02-10, + I replied to Adam Chodorowski: + + It's the diagnostic output that's causing the problem. There's + a markup error on a section title that includes an accented + character. A system message which includes a non-ASCII + character is being sent to sys.stderr. Python believes your + sys.stderr can't handle anything other than ASCII, and + complains loudly. + + If your sys.stderr *can* handle Latin-1 output, telling Python + about it may help. I'm not sure how to tell Python though -- + perhaps via the default encoding in site.py? + + I'm not sure how to fix this, if it should be fixed, or even if + anything is really broken. If I'm processing encoded text from + an ASCII-only console, what kind of error output *should* I + get? Should Docutils prevent non-ASCII output from being + written to sys.stderr? Whose responsibility is it to set up + the stderr environment for encoded output? + + We could write all error output with + ``encodings.raw_unicode_escape.StreamWriter(sys.stderr).write()``, + but that's kind of drastic. It means that all systems, even + those that are encoding-aware, would get dumbed-down (and not + easily deciphered) error output. + + Adam replied: + + The assumption should, IMHO, be that the user's terminal can + handle the encoding that the file is in. I mean, the user most + likely worked with the file (perhaps a textmode editor, or + 'less', or 'cat', or...) in the terminal, so it seems a good + bet. I would think this is true for 99% of the cases. + + In some other, eg. where you are processing a lot of + documentation in different encodings on the same machine + (eg. documentation for some software or whatever) the user is + also probably more equipped to handle the problems. In any + case, saying that "the error output will be in the same + encoding as the input file" would simplify it a lot in this + scenario too (you can make sane build scripts)... + + I'm not sure that I agree with this. Ideas and discussion are welcome. + + Perhaps Docutils should grow an --error-encoding option. Docutils + could use it to tell Python how to encode sys.stderr. + General ------- @@ -314,54 +362,6 @@ General reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output? -* Non-ASCII text in system messages cause a traceback. On 2003-02-10, - I replied to Adam Chodorowski: - - It's the diagnostic output that's causing the problem. There's - a markup error on a section title that includes an accented - character. A system message which includes a non-ASCII - character is being sent to sys.stderr. Python believes your - sys.stderr can't handle anything other than ASCII, and - complains loudly. - - If your sys.stderr *can* handle Latin-1 output, telling Python - about it may help. I'm not sure how to tell Python though -- - perhaps via the default encoding in site.py? - - I'm not sure how to fix this, if it should be fixed, or even if - anything is really broken. If I'm processing encoded text from - an ASCII-only console, what kind of error output *should* I - get? Should Docutils prevent non-ASCII output from being - written to sys.stderr? Whose responsibility is it to set up - the stderr environment for encoded output? - - We could write all error output with - ``encodings.raw_unicode_escape.StreamWriter(sys.stderr).write()``, - but that's kind of drastic. It means that all systems, even - those that are encoding-aware, would get dumbed-down (and not - easily deciphered) error output. - - Adam replied: - - The assumption should, IMHO, be that the user's terminal can - handle the encoding that the file is in. I mean, the user most - likely worked with the file (perhaps a textmode editor, or - 'less', or 'cat', or...) in the terminal, so it seems a good - bet. I would think this is true for 99% of the cases. - - In some other, eg. where you are processing a lot of - documentation in different encodings on the same machine - (eg. documentation for some software or whatever) the user is - also probably more equipped to handle the problems. In any - case, saying that "the error output will be in the same - encoding as the input file" would simplify it a lot in this - scenario too (you can make sane build scripts)... - - I'm not sure that I agree with this. Ideas and discussion are welcome. - - Perhaps Docutils should grow an --error-encoding option. Docutils - could use it to tell Python how to encode sys.stderr. - * Perhaps we need to re-evaluate the config file format, possibly enabling a section for each Docutils component so that (for example) HTML's and LaTeX's stylesheets don't interfere with each other. -- cgit v1.2.1 From eb300c6680250e5742832fdff69f34494c8e75ac Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 29 May 2003 15:18:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1360 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 3a95fe675..69726fb52 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -395,6 +395,22 @@ debug Report debug-level system messages. Default: don't (None). Options: ``--debug, --no-debug``. -------------------- ------------------------------------------------ +docinfo_xform (Standalone Reader.) Enable or disable the + bibliographic field list transform + (docutils.transforms.frontmatter.DocInfo). + + Default: enabled (1). Options: + ``--no-doc-info``. +-------------------- ------------------------------------------------ +doctitle_xform (Standalone Reader.) Enable or disable the + promotion of a lone top-level section title to + document title (and subsequent section title to + document subtitle promotion; + docutils.transforms.frontmatter.DocTitle). + + Default: enabled (). Options: + ``--no-doc-title``. +-------------------- ------------------------------------------------ doctype_declaration (XML Writer.) Generate XML with a DOCTYPE declaration. @@ -607,8 +623,8 @@ warning_stream Path to a file for the output of system messages Default: stderr (None). Options: ``--warnings``. -------------------- ------------------------------------------------ -xml_declaration (XML Writer.) Generate XML with an XML - declaration. +xml_declaration (XML and HTML Writers.) Generate XML with an + XML declaration. .. Caution:: The XML declaration carries text encoding information, without which standard -- cgit v1.2.1 From 4635b386ba4ca833b623f3d22ac9456643d9e279 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 May 2003 18:13:07 +0000 Subject: added --attribution option git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1361 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 69726fb52..ea10743e2 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -358,6 +358,12 @@ for some attributes. ==================== ================================================ Setting/Config Entry Description ==================== ================================================ +attribution (HTML Writer.) Format for block quote + attributions: one of "dash" (em-dash prefix), + "parentheses"/"parens", or "none". + + Default: "dash". Options: ``--attribution``. +-------------------- ------------------------------------------------ compact_lists (HTML Writer.) Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all -- cgit v1.2.1 From d8bf21e95c26f4b3ddacd7b6eefbf51cbd1939ee Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 May 2003 18:13:20 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1362 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b0cc2f901..1db66a3e5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -851,25 +851,8 @@ __ rst/alternatives.html#or-not-to-do Perhaps. Perhaps not. -* Add attribution parsing to block quotes? Iff the last paragraph - [#]_ begins with "--", it becomes an attribution. This goes back to - Paul Moore's initial "Using blockquote element for quotes" post - (docutils-users 2003-04-18). Example:: - - Structured text is really a great idea for certain situations; - reST is a much better implementation of the idea than any - versions I've seen before. - - -- Guido van Rossum on Python-Dev, 2002-04-04 - - .. [#] Also check for a final definition list with one item, whose - term begins with "--"? If an attribution wraps, it may be - formatted like this:: - - A quote. - - -- An attribution - more info here +* Allow whitespace before the "::" in directives? Hyperlink targets + too? This would appease some of our French-speaking users. Directives -- cgit v1.2.1 From 34af804b256cc97578f4bf9c16373d06e798029d Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 2 Jun 2003 08:56:36 +0000 Subject: Add attribution and align to the right. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1365 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 0bc46d375..c7b516795 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -64,6 +64,12 @@ Setting/Config Entry Description --footnote-references Format for footnote references: one of "superscript" or "brackets". Default is "brackets". +--------------------- ------------------------------------------------ +--attribution Format for block quote attributions: one of + "dash" (em-dash prefix), "parentheses"/"parens", + or "none". + + Default: "dash". Options: ``--attribution``. ===================== ================================================ -- cgit v1.2.1 From 1963569801478851155150f7fb005defc5a521ad Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 3 Jun 2003 02:12:03 +0000 Subject: Added "error_encoding" and "_disable_config" settings, updated "output_encoding". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1367 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index ea10743e2..ca6f34030 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -460,6 +460,17 @@ embed_stylesheet (HTML Writer.) Embed the stylesheet in the Default: link, don't embed (None). Options: ``--embed-stylesheet, --link-stylesheet``. -------------------- ------------------------------------------------ +error_encoding The text encoding for error output. May also + specify the encoding error handler for + unencodable characters, after a colon (":"). + Acceptable values are the same as for the + "error" parameter of Python's ``encode`` string + method. + + Default: "ascii:backslashreplace" for Python 2.3 + and later; "ascii:replace" otherwise. Options: + ``--error-encoding, -e``. +-------------------- ------------------------------------------------ expose_internals List of internal attribues to expose as external attributes (with "internal:" namespace prefix). @@ -518,8 +529,12 @@ no_random (PEP/HTML Writer.) Workaround for platforms Default: random enabled (None). Options: ``--no-random`` (hidden). -------------------- ------------------------------------------------ -output_encoding Default: UTF-8. Options: ``--output-encoding, - -o``. +output_encoding The text encoding for output. May also specify + the encoding error handler for unencodable + characters (see "error_encoding"). + + Default: "UTF-8:strict". Options: + ``--output-encoding, -o``. -------------------- ------------------------------------------------ pep_home (PEP/HTML Writer.) Home URL prefix for PEPs. @@ -650,6 +665,12 @@ _directories (``buildhtml.py`` front end.) List of paths to Default: current working directory (None). No command-line options. -------------------- ------------------------------------------------ +_disable_config Prevent standard configuration files from being + read. + + Default: config files enabled (None). No + command-line options. +-------------------- ------------------------------------------------ _destination Path to output destination, set from positional arguments. -- cgit v1.2.1 From f43900b985a1c3fae98d7a99847250750039b6b4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 3 Jun 2003 02:16:59 +0000 Subject: Added "pull-quote" directive. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1373 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 49eaca399..93fceb90f 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -499,6 +499,18 @@ Highlights Produces a highlights-class block quote. See Epigraph_ above. +Pull-Quote +========== + +:Directive Type: "pull_quote" +:Doctree Element: block_quote +:Directive Arguments: None. +:Directive Options: None. +:Directive Content: Interpreted as the body of the block quote. + +Produces a pull-quote-class block quote. See Epigraph_ above. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From f4fc97209372be9399682ef969815a3557ceda88 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 3 Jun 2003 02:19:25 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1374 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 1db66a3e5..98de687f5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -851,8 +851,9 @@ __ rst/alternatives.html#or-not-to-do Perhaps. Perhaps not. -* Allow whitespace before the "::" in directives? Hyperlink targets - too? This would appease some of our French-speaking users. +* Allow whitespace before the "::" in directives? Before the ":" in + hyperlink targets too? This would appease some of our + French-speaking users. Directives @@ -919,8 +920,10 @@ when used in a document. 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? Issue: altering the section - structure of a document could render hyperlinks invalid. + 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 -- cgit v1.2.1 From 3c49756fb2895527abdac611c24c6c47fd05228d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 3 Jun 2003 02:42:56 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1376 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 54 ------------------------------------------------------ 1 file changed, 54 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 98de687f5..accc4cd7a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -45,60 +45,6 @@ Bugs whitespace and punctuation as markup delimiters, which may not be applicable in these languages. -* Configuration files (~/.docutils or /etc/docutils.conf or - test/docutils.conf) affect any test suites that use - docutils.core.Publisher (test/test_writers). For example, setting - the default language causes changes in the output. (Reported by - Ludger Humbert.) - -* Non-ASCII text in system messages cause a traceback. On 2003-02-10, - I replied to Adam Chodorowski: - - It's the diagnostic output that's causing the problem. There's - a markup error on a section title that includes an accented - character. A system message which includes a non-ASCII - character is being sent to sys.stderr. Python believes your - sys.stderr can't handle anything other than ASCII, and - complains loudly. - - If your sys.stderr *can* handle Latin-1 output, telling Python - about it may help. I'm not sure how to tell Python though -- - perhaps via the default encoding in site.py? - - I'm not sure how to fix this, if it should be fixed, or even if - anything is really broken. If I'm processing encoded text from - an ASCII-only console, what kind of error output *should* I - get? Should Docutils prevent non-ASCII output from being - written to sys.stderr? Whose responsibility is it to set up - the stderr environment for encoded output? - - We could write all error output with - ``encodings.raw_unicode_escape.StreamWriter(sys.stderr).write()``, - but that's kind of drastic. It means that all systems, even - those that are encoding-aware, would get dumbed-down (and not - easily deciphered) error output. - - Adam replied: - - The assumption should, IMHO, be that the user's terminal can - handle the encoding that the file is in. I mean, the user most - likely worked with the file (perhaps a textmode editor, or - 'less', or 'cat', or...) in the terminal, so it seems a good - bet. I would think this is true for 99% of the cases. - - In some other, eg. where you are processing a lot of - documentation in different encodings on the same machine - (eg. documentation for some software or whatever) the user is - also probably more equipped to handle the problems. In any - case, saying that "the error output will be in the same - encoding as the input file" would simplify it a lot in this - scenario too (you can make sane build scripts)... - - I'm not sure that I agree with this. Ideas and discussion are welcome. - - Perhaps Docutils should grow an --error-encoding option. Docutils - could use it to tell Python how to encode sys.stderr. - General ------- -- cgit v1.2.1 From 6accfecf813ed11c110351c02d98e11b43f57c0a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 5 Jun 2003 15:15:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1385 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 53 +++++++++++++++++++++++++++------- docs/dev/todo.txt | 66 ++++++++++++++++++++++++++++++------------- docs/ref/rst/roles.txt | 64 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 0208e3c0e..a6eaca41d 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -205,9 +205,10 @@ Parameterized Interpreted Text ------------------------------ In some cases it may be expedient to pass parameters to interpreted -text roles, analogous to function calls. Ideas: +text, analogous to function calls. Ideas: -1. Suggested by Jason Diamond:: +1. Parameterize the interpreted text role itself (suggested by Jason + Diamond):: `interpreted text`:role1(foo=bar): @@ -216,12 +217,30 @@ text roles, analogous to function calls. Ideas: `CSS`:acronym(Cascading Style Sheets): is used for HTML, and `CSS`:acronym(Content Scrambling System): is used for DVDs. - Problem: current interpreted text syntax does not recognize roles - containing whitespace. + Technical problem: current interpreted text syntax does not + recognize roles containing whitespace. Design problem: this smells + like programming language syntax, but reStructuredText is not a + programming language. -This pushes inline markup too far; readability becomes a serious -issue. Substitutions may provide a better alternative by pulling the -details out of the text flow:: +2. Put the parameters inside the interpreted text:: + + `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and + `CSS (Content Scrambling System)`:acronym: is used for DVDs. + + Although this could be defined on an individual basis (per role), + we ought to have a standard. Hyperlinks with embedded URIs already + use angle brackets; perhaps they could be used here too:: + + `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and + `CSS <Content Scrambling System>`:acronym: is used for DVDs. + + Do angle brackets connote URLs too much for this to be acceptable? + How about the "tag" connotation -- does it save them or doom them? + +Does this push inline markup too far? Readability becomes a serious +issue. Substitutions may provide a better alternative (at the expense +of verbosity and duplication) by pulling the details out of the text +flow:: |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. @@ -229,9 +248,18 @@ details out of the text flow:: .. |CSS-DVD| acronym:: Content Scrambling System :text: CSS -This is going beyond the scope of reStructuredText though. Documents -requiring this functionality may be better off using XML or another -markup system. +---------------------------------------------------------------------- + +This whole idea may be going beyond the scope of reStructuredText. +Documents requiring this functionality may be better off using XML or +another markup system. + +This argument comes up regularly when pushing the envelope of +reStructuredText syntax. I think it's a useful argument in that it +provides a check on creeping featurism. In many cases, the resulting +verbosity produces such unreadable plaintext that there's a natural +desire *not* to use it unless absolutely necessary. It's a matter of +finding the right balance. Character Processing @@ -262,6 +290,11 @@ the copyright symbol character. If this is not possible in an authoring environment, a pre-processing stage can be added, or a table of substitution definitions can be devised. +A "unicode" directive has been implemented to allow direct +specification of esoteric characters. In combination with the +substitution construct, "include" files defining common sets of +character entities can be defined and used. + To allow for `character-level inline markup`_, a limited form of character processing has been added to the spec and parser: escaped whitespace characters are removed from the processed document. Any diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index accc4cd7a..83a3c8461 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1237,13 +1237,6 @@ 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. -* Add interpreted text support code. (Done) - - Ideally and eventually, the "interpreted" element will disappear - from the Docutils doctree. In its place will be a customizable set - of inline elements including "acronym" and "index_entry", directly - created by the parser. - * Add a test for language mappings. * Alan Jaffray suggested (and I agree) that it would be sensible to: @@ -1257,22 +1250,15 @@ elements. which contain interpreted text with no explicitly specified role (there will always be a default role, so this won't happen) -* Perhaps the default implicit role for interpreted text could be - "title", as in, "title of a book". It'd be a text-only reference, - no hyperlink. Idea from Aahz' 2002-05-09 Doc-SIG post. (Done) - * Add a directive establishing a mapping of interpreted text role aliases? A set of default roles (index, acronym, etc.) could exist, and the directive could assign abbreviations (i, a, etc.) or other alternatives. -* Explicitly add inline markup roles (emphasis, strong, literal) to - the built-in list of interpreted text roles? Useful for - completeness, and potentially useful if `multiple roles`_ ever - become possible. - - .. _multiple roles: - rst/alternatives.html#multiple-roles-in-interpreted-text +* 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-riference (& synonyms). * Add directives for each role as well? This would allow indirect nested markup:: @@ -1349,9 +1335,49 @@ elements. separate file but I'm experimenting with creating a directive that will use some form of reST syntax to let you define them. - What to do with an undefined acronym or abbreviation? + 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? + + 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. + + __ 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`__. - - "superscript" and "subscript" (synonyms "sup" and "sub"). + __ 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 diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 9a720eff0..d65750df6 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -31,6 +31,40 @@ Specification`_ for syntax details. .. contents:: +``:emphasis:`` +============== + +:Aliases: None +:DTD Element: emphasis + +Implements emphasis. These are equivalent:: + + *text* + :emphasis:`text` + + +``:literal:`` +============== + +:Aliases: None +:DTD Element: literal + +Implements inline literal text. These are equivalent:: + + ``text`` + :literal:`text` + +Care must be taken with backslash-escapes though. These are *not* +equivalent:: + + ``text \ and \ backslashes`` + :literal:`text \ and \ backslashes` + +The backslashes in the first line are preserved (and do nothing), +whereas the backslashes in the second line escape the following +spaces. + + ``:pep-reference:`` =================== @@ -69,6 +103,36 @@ This is equivalent to:: __ http://www.faqs.org/rfcs/rfc2822.html +``:strong:`` +============ + +:Aliases: None +:DTD Element: strong + +Implements strong emphasis. These are equivalent:: + + **text** + :strong:`text` + + +``:subscript:`` +=============== + +:Aliases: ``:sub:`` +:DTD Element: subscript + +Implements subscripts. + + +``:superscript:`` +================= + +:Aliases: ``:sup:`` +:DTD Element: superscript + +Implements superscripts. + + ``:title-reference:`` ===================== -- cgit v1.2.1 From 0b36bac7d9c46d69c2cad0a3e2e0b39aa0a5b58b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 8 Jun 2003 20:55:47 +0000 Subject: Converted settings table into a definition list. Updated. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1399 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 668 ++++++++++++++++++++++++++-------------------------- 1 file changed, 336 insertions(+), 332 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index ca6f34030..389c3fa26 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -350,338 +350,342 @@ options is listed in `Configuration File Entries`_ below. Configuration File Entries -------------------------- -Names in the first column of the table below are runtime settings. -Most may be specified in `configuration files`_, where hyphens may be -used in place of underscores. Some knowledge of Python_ is assumed -for some attributes. - -==================== ================================================ -Setting/Config Entry Description -==================== ================================================ -attribution (HTML Writer.) Format for block quote - attributions: one of "dash" (em-dash prefix), - "parentheses"/"parens", or "none". - - Default: "dash". Options: ``--attribution``. --------------------- ------------------------------------------------ -compact_lists (HTML Writer.) Remove extra vertical whitespace - between items of bullet lists and enumerated - lists, when list items are "simple" (i.e., all - items each contain one paragraph and/or one - "simple" sublist only). - - Default: enabled (1). Options: - ``--compact-lists, --no-compact-lists``. --------------------- ------------------------------------------------ -config Path to a configuration file to read (if it - exists) [#pwd]_. Settings may override defaults - and earlier settings. This is only effective as - a command-line option; setting it in a config - file has no effect. - - Filesystem path settings contained within the - config file will be interpreted relative to the - config file's location (*not* relative to the - current working directory). - - Default: None. Options: ``--config``. --------------------- ------------------------------------------------ -datestamp Include a time/datestamp in the document footer. - Contains a format string for Python's - ``time.strftime``. See the `time module - documentation`__. - - Default: None. Options: ``--date, -d, --time, - -t, --no-datestamp``. - - __ http://www.python.org/doc/current/lib/module-time.html --------------------- ------------------------------------------------ -debug Report debug-level system messages. - - Default: don't (None). Options: ``--debug, - --no-debug``. --------------------- ------------------------------------------------ -docinfo_xform (Standalone Reader.) Enable or disable the - bibliographic field list transform - (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: - ``--no-doc-info``. --------------------- ------------------------------------------------ -doctitle_xform (Standalone Reader.) Enable or disable the - promotion of a lone top-level section title to - document title (and subsequent section title to - document subtitle promotion; - docutils.transforms.frontmatter.DocTitle). - - Default: enabled (). Options: - ``--no-doc-title``. --------------------- ------------------------------------------------ -doctype_declaration (XML Writer.) Generate XML with a DOCTYPE - declaration. - - Default: do (1). Options: ``--no-doctype``. --------------------- ------------------------------------------------ -dump_internals At the end of processing, write all internal - attributes of the document - (``document.__dict__``) to stderr. - - Default: don't (None). Options: - ``--dump-internals`` (hidden, for development - use only). --------------------- ------------------------------------------------ -dump_pseudo_xml At the end of processing, write the pseudo-XML - representation of the document to stderr. - - Default: don't (None). Options: - ``--dump-pseudo-xml`` (hidden, for development - use only). --------------------- ------------------------------------------------ -dump_settings At the end of processing, write all Docutils - settings to stderr. - - Default: don't (None). Options: - ``--dump-settings`` (hidden, for development use - only). --------------------- ------------------------------------------------ -dump_transforms At the end of processing, write a list of all - transforms applied to the document to stderr. - - Default: don't (None). Options: - ``--dump-transforms`` (hidden, for development - use only). --------------------- ------------------------------------------------ -embed_stylesheet (HTML Writer.) Embed the stylesheet in the - output HTML file. The stylesheet file must be - accessible during processing. The stylesheet is - embedded inside a comment, so it must not - contain the text "``--``" (two hyphens). - - Default: link, don't embed (None). Options: - ``--embed-stylesheet, --link-stylesheet``. --------------------- ------------------------------------------------ -error_encoding The text encoding for error output. May also - specify the encoding error handler for - unencodable characters, after a colon (":"). - Acceptable values are the same as for the - "error" parameter of Python's ``encode`` string - method. - - Default: "ascii:backslashreplace" for Python 2.3 - and later; "ascii:replace" otherwise. Options: - ``--error-encoding, -e``. --------------------- ------------------------------------------------ -expose_internals List of internal attribues to expose as external - attributes (with "internal:" namespace prefix). - - Default: don't (None). Options: - ``--expose-internal-attribute`` (hidden, for - development use only). --------------------- ------------------------------------------------ -footnote_backlinks Enable or disable backlinks from footnotes and - citations to their references. - - Default: enabled (1). Options: - ``--footnote-backlinks, - --no-footnote-backlinks``. --------------------- ------------------------------------------------ -footnote_references (HTML Writer.) Format for footnote references, - one of "superscript" or "brackets". - - Default: "superscript"; "brackets" in PEP/HTML - Writer. Options: ``--footnote-references``. --------------------- ------------------------------------------------ -generator Include a "Generated by Docutils" credit and - link in the document footer. - - Default: off (None). Options: ``--generator, - -g, --no-generator``. --------------------- ------------------------------------------------ -halt_level The threshold at or above which system messages - are converted to exceptions, halting execution - immediately. - - Default: severe (4). Options: ``--halt, - --strict``. --------------------- ------------------------------------------------ -indents (XML Writer.) Generate XML with indents and - newlines. - - Default: don't (None). Options: ``--indents``. --------------------- ------------------------------------------------ -input_encoding Default: auto-detect (None). Options: - ``--input-encoding, -i``. --------------------- ------------------------------------------------ -language_code `ISO 639`_ 2-letter language code (3-letter - codes used only if no 2-letter code exists). - - Default: English ("en"). Options: ``--language, - -l``. --------------------- ------------------------------------------------ -newlines (XML Writer.) Generate XML with newlines before - and after tags. - - Default: don't (None). Options: ``--newlines``. --------------------- ------------------------------------------------ -no_random (PEP/HTML Writer.) Workaround for platforms - which core-dump on "``import random``". - - Default: random enabled (None). Options: - ``--no-random`` (hidden). --------------------- ------------------------------------------------ -output_encoding The text encoding for output. May also specify - the encoding error handler for unencodable - characters (see "error_encoding"). - - Default: "UTF-8:strict". Options: - ``--output-encoding, -o``. --------------------- ------------------------------------------------ -pep_home (PEP/HTML Writer.) Home URL prefix for PEPs. - - Default: current directory ("."). Options: - ``--pep-home``. --------------------- ------------------------------------------------ -pep_references (reStructuredText Parser.) Recognize and link - to PEP references (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP - Reader. Options: ``--pep-references``. --------------------- ------------------------------------------------ -pep_stylesheet (PEP/HTML Writer.) CSS stylesheet URL, used - verbatim. Overrides HTML stylesheet - (``--stylesheet``). - - Default: None. Options: ``--pep-stylesheet``. --------------------- ------------------------------------------------ -pep_stylesheet_path (PEP/HTML Writer.) Path to CSS stylesheet - [#pwd]_. Path is adjusted relative to the - output HTML file. Overrides HTML stylesheet - (``--stylesheet``) and PEP stylesheet - (``--pep-stylesheet``). - - Default: None. Options: - ``--pep-stylesheet-path``. --------------------- ------------------------------------------------ -pep_template (PEP/HTML Writer.) Path to PEP template file - [#pwd]_. - - Default: "pep-html-template" (in current - directory). Options: ``--pep-template``. --------------------- ------------------------------------------------ -python_home (PEP/HTML Writer.) Python's home URL. - - Default: parent directory (".."). Options: - ``--python-home``. --------------------- ------------------------------------------------ -recurse (``buildhtml.py`` front end.) Recursively scan - subdirectories. - - Default: recurse (1). Options: ``--recurse, - --local``. --------------------- ------------------------------------------------ -report_level Verbosity threshold at or above which system - messages are reported. - - Default: warning (2). Options: ``--report, -r, - --verbose, -v, --quiet, -q``. --------------------- ------------------------------------------------ -rfc_references (reStructuredText Parser.) Recognize and link - to RFC references (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP - Reader. Options: ``--rfc-references``. --------------------- ------------------------------------------------ -silent (``buildhtml.py`` front end.) Work silently (no - progress messages). Independent of - "report_level". - - Default: show progress (None). Options: - ``--silent``. --------------------- ------------------------------------------------ -source_link Include a "View document source" link in the - document footer. URL will be relative to the - destination. - - Default: don't (None). Options: - ``--source-link, --no-source-link``. --------------------- ------------------------------------------------ -source_url An explicit URL for a "View document source" - link, used verbatim. - - Default: compute if source_link (None). - Options: ``--source-uri, --no-source-link``. --------------------- ------------------------------------------------ -stylesheet (HTML Writer.) CSS stylesheet URL, used - verbatim. Overridden by "stylesheet_path" URL - option (``--stylesheet-path``). - - Default: "default.css". Options: - ``--stylesheet``. --------------------- ------------------------------------------------ -stylesheet_path (HTML Writer.) Path to CSS stylesheet [#pwd]_. - Overrides "stylesheet" URL option - (``--stylesheet``). Path is adjusted relative - to the output HTML file. - - Default: None. Options: ``--stylesheet``. --------------------- ------------------------------------------------ -tab_width (reStructuredText Parser.) Number of spaces for - hard tab expansion. - - Default: 8. Options: ``--tab-width``. --------------------- ------------------------------------------------ -toc_backlinks Enable backlinks from section titles to table of - contents entries ("entry"), to the top of the - TOC ("top"), or disable ("none"). - - Default: "entry". Options: - ``--toc-entry-backlinks, --toc-top-backlinks, - --no-toc-backlinks``. --------------------- ------------------------------------------------ -warning_stream Path to a file for the output of system messages - (warnings) [#pwd]_. - - Default: stderr (None). Options: - ``--warnings``. --------------------- ------------------------------------------------ -xml_declaration (XML and HTML Writers.) Generate XML with an - XML declaration. - - .. Caution:: The XML declaration carries text - encoding information, without which standard - tools may be unable to read the generated - XML. - - Default: do (1). Options: - ``--no-xml-declaration``. - --------------------- ------------------------------------------------ -**For Internal Use Only** (setting these in a config file has no effect) ----------------------------------------------------------------------- -_directories (``buildhtml.py`` front end.) List of paths to - source directories, set from positional - arguments. - - Default: current working directory (None). No - command-line options. --------------------- ------------------------------------------------ -_disable_config Prevent standard configuration files from being - read. - - Default: config files enabled (None). No - command-line options. --------------------- ------------------------------------------------ -_destination Path to output destination, set from positional - arguments. - - Default: stdout (None). No command-line - options. --------------------- ------------------------------------------------ -_source Path to input source, set from positional - arguments. - - Default: stdin (None). No command-line options. -==================== ================================================ +Listed below are the Docutils runtime settings. Most may be specified +in `configuration files`_, where hyphens may be used in place of +underscores. Some knowledge of Python_ is assumed for some +attributes. + +attribution + (HTML Writer.) Format for block quote attributions: one of "dash" + (em-dash prefix), "parentheses"/"parens", or "none". + + Default: "dash". Options: ``--attribution``. + +compact_lists + (HTML Writer.) Remove extra vertical whitespace between items of + bullet lists and enumerated lists, when list items are "simple" + (i.e., all items each contain one paragraph and/or one "simple" + sublist only). + + Default: enabled (1). Options: ``--compact-lists, + --no-compact-lists``. + +config + Path to a configuration file to read (if it exists) + [#pwd]_. Settings may override defaults and earlier settings. + This is only effective as a command-line option; setting it in a + config file has no effect. + + Filesystem path settings contained within the config file will be + interpreted relative to the config file's location (*not* relative + to the current working directory). + + Default: None. Options: ``--config``. + +datestamp + Include a time/datestamp in the document footer. Contains a + format string for Python's ``time.strftime``. See the `time + module documentation`__. + + Default: None. Options: ``--date, -d, --time, -t, + --no-datestamp``. + + __ http://www.python.org/doc/current/lib/module-time.html + +debug + Report debug-level system messages. + + Default: don't (None). Options: ``--debug, --no-debug``. + +docinfo_xform + (Standalone Reader.) Enable or disable the bibliographic field + list transform (docutils.transforms.frontmatter.DocInfo). + + Default: enabled (1). Options: ``--no-doc-info``. + +doctitle_xform + + (Standalone Reader.) Enable or disable the promotion of a lone + top-level section title to document title (and subsequent section + title to document subtitle promotion; + docutils.transforms.frontmatter.DocTitle). + + Default: enabled (). Options: ``--no-doc-title``. + +doctype_declaration + (XML Writer.) Generate XML with a DOCTYPE declaration. + + Default: do (1). Options: ``--no-doctype``. + +dump_internals + At the end of processing, write all internal attributes of the + document (``document.__dict__``) to stderr. + + Default: don't (None). Options: ``--dump-internals`` (hidden, for + development use only). + +dump_pseudo_xml + At the end of processing, write the pseudo-XML representation of + the document to stderr. + + Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, + for development use only). + +dump_settings + At the end of processing, write all Docutils settings to stderr. + + Default: don't (None). Options: ``--dump-settings`` (hidden, for + development use only). + +dump_transforms + At the end of processing, write a list of all transforms applied + to the document to stderr. + + Default: don't (None). Options: ``--dump-transforms`` (hidden, + for development use only). + +embed_stylesheet + (HTML Writer.) Embed the stylesheet in the output HTML file. The + stylesheet file must be accessible during processing. The + stylesheet is embedded inside a comment, so it must not contain + the text "``--``" (two hyphens). + + Default: link, don't embed (None). Options: ``--embed-stylesheet, + --link-stylesheet``. + +error_encoding + The text encoding for error output. + + Default: "ascii". Options: ``--error-encoding, -e``. + +error_encoding_error_handler + The encoding error handler for unencodable characters in error + output. Acceptable values are the same as for the "error" + parameter of Python's ``encode`` string method. + + Default: "backslashreplace" for Python 2.3 and later; "replace" + otherwise. Options: ``--error-encoding-error-handler, + --error-encoding, -e``. + +expose_internals + List of internal attribues to expose as external attributes (with + "internal:" namespace prefix). + + Default: don't (None). Options: ``--expose-internal-attribute`` + (hidden, for development use only). + +footnote_backlinks + Enable or disable backlinks from footnotes and citations to their + references. + + Default: enabled (1). Options: ``--footnote-backlinks, + --no-footnote-backlinks``. + +footnote_references + (HTML Writer.) Format for footnote references, one of + "superscript" or "brackets". + + Default: "superscript"; "brackets" in PEP/HTML Writer. Options: + ``--footnote-references``. + +generator + Include a "Generated by Docutils" credit and link in the document + footer. + + Default: off (None). Options: ``--generator, -g, + --no-generator``. + +halt_level + The threshold at or above which system messages are converted to + exceptions, halting execution immediately. + + Default: severe (4). Options: ``--halt, --strict``. + +indents + (XML Writer.) Generate XML with indents and newlines. + + Default: don't (None). Options: ``--indents``. + +input_encoding + The text encoding for input. + + Default: auto-detect (None). Options: ``--input-encoding, -i``. + +language_code + `ISO 639`_ 2-letter language code (3-letter codes used only if no + 2-letter code exists). + + Default: English ("en"). Options: ``--language, -l``. + +newlines + (XML Writer.) Generate XML with newlines before and after tags. + + Default: don't (None). Options: ``--newlines``. + +no_random + (PEP/HTML Writer.) Workaround for platforms which core-dump on + "``import random``". + + Default: random enabled (None). Options: ``--no-random`` + (hidden). + +output_encoding + The text encoding for output. + + Default: "UTF-8". Options: ``--output-encoding, -o``. + +output_encoding_error_handler + The encoding error handler for unencodable characters in output. + Acceptable values are the same as for the "error" parameter of + Python's ``encode`` string method. + + Default: "strict". Options: ``--output-encoding-error-handler, + --output-encoding, -o``. + +pep_home + (PEP/HTML Writer.) Home URL prefix for PEPs. + + Default: current directory ("."). Options: ``--pep-home``. + +pep_references + (reStructuredText Parser.) Recognize and link to PEP references + (like "PEP 258"). + + Default: disabled (None); enabled (1) in PEP Reader. Options: + ``--pep-references``. + +pep_stylesheet + (PEP/HTML Writer.) CSS stylesheet URL, used verbatim. Overrides + HTML stylesheet (``--stylesheet``). + + Default: None. Options: ``--pep-stylesheet``. + +pep_stylesheet_path + (PEP/HTML Writer.) Path to CSS stylesheet [#pwd]_. Path is + adjusted relative to the output HTML file. Overrides HTML + stylesheet (``--stylesheet``) and PEP stylesheet + (``--pep-stylesheet``). + + Default: None. Options: ``--pep-stylesheet-path``. + +pep_template + (PEP/HTML Writer.) Path to PEP template file [#pwd]_. + + Default: "pep-html-template" (in current directory). Options: + ``--pep-template``. + +python_home + (PEP/HTML Writer.) Python's home URL. + + Default: parent directory (".."). Options: ``--python-home``. + +recurse + (``buildhtml.py`` front end.) Recursively scan subdirectories. + + Default: recurse (1). Options: ``--recurse, --local``. + +report_level + Verbosity threshold at or above which system messages are + reported. + + Default: warning (2). Options: ``--report, -r, --verbose, -v, + --quiet, -q``. + +rfc_references + (reStructuredText Parser.) Recognize and link to RFC references + (like "RFC 822"). + + Default: disabled (None); enabled (1) in PEP Reader. Options: + ``--rfc-references``. + +silent + (``buildhtml.py`` front end.) Work silently (no progress + messages). Independent of "report_level". + + Default: show progress (None). Options: ``--silent``. + +source_link + Include a "View document source" link in the document footer. URL + will be relative to the destination. + + Default: don't (None). Options: ``--source-link, + --no-source-link``. + +source_url + An explicit URL for a "View document source" link, used verbatim. + + Default: compute if source_link (None). Options: ``--source-uri, + --no-source-link``. + +stylesheet + (HTML Writer.) CSS stylesheet URL, used verbatim. Overridden by + "stylesheet_path" URL option (``--stylesheet-path``). + + Default: "default.css". Options: ``--stylesheet``. + +stylesheet_path + (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides + "stylesheet" URL option (``--stylesheet``). Path is adjusted + relative to the output HTML file. + + Default: None. Options: ``--stylesheet``. + +tab_width + (reStructuredText Parser.) Number of spaces for hard tab + expansion. + + Default: 8. Options: ``--tab-width``. + +toc_backlinks + Enable backlinks from section titles to table of contents entries + ("entry"), to the top of the TOC ("top"), or disable ("none"). + + Default: "entry". Options: ``--toc-entry-backlinks, + --toc-top-backlinks, --no-toc-backlinks``. + +warning_stream + Path to a file for the output of system messages (warnings) + [#pwd]_. + + Default: stderr (None). Options: ``--warnings``. + +xml_declaration + (XML and HTML Writers.) Generate XML with an XML declaration. + + .. Caution:: The XML declaration carries text encoding + information, without which standard tools may be unable to read + the generated XML. + + Default: do (1). Options: ``--no-xml-declaration``. + + +For Internal Use Only +````````````````````` + +Setting these in a config file has no effect. + + +_directories + (``buildhtml.py`` front end.) List of paths to source + directories, set from positional arguments. + + Default: current working directory (None). No command-line + options. + +_disable_config + Prevent standard configuration files from being read. + + Default: config files enabled (None). No command-line options. + +_destination + Path to output destination, set from positional arguments. + + Default: stdout (None). No command-line options. + +_source + Path to input source, set from positional arguments. + + Default: stdin (None). No command-line options. .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html -- cgit v1.2.1 From bb2f2713e8cdf461d76b7354dc14525ae733545a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 8 Jun 2003 20:58:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1401 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 83a3c8461..04abe3208 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -312,6 +312,10 @@ General enabling a section for each Docutils component so that (for example) HTML's and LaTeX's stylesheets don't interfere with each other. +* The "docutils.conf" included with Docutils should become complete, + with examples of every setting (possibly commented). It's currently + sparse, requiring doc lookups. + Documentation ------------- -- cgit v1.2.1 From 1fc858bc8b0d46f289961e0c03ccabbede70d6fc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Jun 2003 15:06:07 +0000 Subject: Added "--trim-footnote-reference-space" option. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1403 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 389c3fa26..59deeac5a 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -643,6 +643,13 @@ toc_backlinks Default: "entry". Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``. +trim-footnote-reference-space + (reStructuredText Parser.) Remove spaces before footnote + references. + + Default: don't (None). Options: + ``--trim-footnote-reference-space``. + warning_stream Path to a file for the output of system messages (warnings) [#pwd]_. -- cgit v1.2.1 From 2671bd34f6c937267c01599005cc06bcb6168606 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Jun 2003 15:07:47 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1406 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 04abe3208..a834258c5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -801,10 +801,6 @@ __ rst/alternatives.html#or-not-to-do Perhaps. Perhaps not. -* Allow whitespace before the "::" in directives? Before the ":" in - hyperlink targets too? This would appease some of our - French-speaking users. - Directives `````````` -- cgit v1.2.1 From 4cc798623cc64d7cd12d72105edb830ac7af07e6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Jun 2003 21:26:31 +0000 Subject: clarification of public domain status git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1409 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.txt | 1 + docs/dev/rst/alternatives.txt | 1 + docs/dev/rst/problems.txt | 1 + docs/dev/semantics.txt | 1 + docs/dev/todo.txt | 1 + docs/ref/rst/directives.txt | 1 + docs/ref/rst/introduction.txt | 1 + docs/ref/rst/restructuredtext.txt | 1 + docs/ref/rst/roles.txt | 1 + docs/user/tools.txt | 1 + 10 files changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index e1df7fb52..ab677a004 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. This document explores issues around extracting and processing docstrings from Python modules. diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index a6eaca41d..a5bc28f62 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. The following are ideas, alternatives, and justifications that were considered for reStructuredText syntax, which did not originate with diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index 15d975198..a8747af88 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. There are several problems, unresolved issues, and areas of controversy within StructuredText_ (Classic and Next Generation). In diff --git a/docs/dev/semantics.txt b/docs/dev/semantics.txt index e42c9ea01..cd20e15f6 100644 --- a/docs/dev/semantics.txt +++ b/docs/dev/semantics.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +: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 diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a834258c5..0383be561 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Date: $Date$ :Revision: $Revision$ +:Copyright: This document has been placed in the public domain. .. _Docutils: http://docutils.sourceforge.net/ diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 93fceb90f..0761e21bb 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 5ff6d2878..13823b5b7 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for inline diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index f4c09c1c9..1ad25ff35 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. Note:: diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d65750df6..a34c4a5ed 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -5,6 +5,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. This document describes the interpreted text roles implemented in the reference reStructuredText parser. diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 59deeac5a..6b8382056 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -6,6 +6,7 @@ :Contact: goodger@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: -- cgit v1.2.1 From 7975b6bbc36fcc0f07a9a24ada9310fa618681f5 Mon Sep 17 00:00:00 2001 From: richard <richard@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 9 Jun 2003 23:03:03 +0000 Subject: copyright on primer git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1410 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index a810cd878..d936147b0 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -3,6 +3,7 @@ A ReStructuredText Primer :Author: Richard Jones :Version: $Revision$ +:Copyright: This document has been placed in the public domain. .. contents:: -- cgit v1.2.1 From 85a8b7e67defbe6c46c878734904b0f843bb94a9 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 10 Jun 2003 07:14:42 +0000 Subject: Added copyright statement (pd). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1414 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index c7b516795..fb5b51d13 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -6,6 +6,7 @@ :Contact: grubert@users.sourceforge.net :Revision: $Revision$ :Date: $Date$ +:Copyright: This document has been placed in the public domain. .. contents:: -- cgit v1.2.1 From 870e743c3448d40c5578c49f8e2a5a3531285c71 Mon Sep 17 00:00:00 2001 From: tibs <tibs@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 10 Jun 2003 19:19:00 +0000 Subject: Add copyright statement, placing document into public domain, at David's request (this was my original intent). Amend mismatch <h2>..</h3> pair, as found by Roger Erens (to whom thanks). Changed "details?" to "details" throughout, in the links to the main reStructuredText documentation. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1416 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 60 ++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 31 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index a3485679e..438e82ce8 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -11,12 +11,6 @@ <body> <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> - <!-- Hmm - does that (relative) font size work for you? --> - <!-- If David produces a smaller version of the reST title --> - <!-- page's title image, we could do something like: --> - <!-- <h1>Quick <img src="images/title.png" --> - <!-- alt="Quick reStructuredText"></h1> --> - <!-- which might be a better idea... --> <!-- Caveat: if you're reading the HTML for the examples, --> <!-- beware that it was hand-generated, not by Docutils/ReST. --> @@ -24,14 +18,18 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-03-22</em> + <br align="right"><em>Updated 2003-06-10</em> + + <blockquote> + <p>Copyright: This document has been placed in the public domain. + </blockquote> <p>The full details of the markup may be found on the <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> page. This document is just intended as a reminder. - <p>Links that look like "(<a href="#details">details?</a>)" point + <p>Links that look like "(<a href="#details">details</a>)" point into the HTML version of the full <a href="../../spec/rst/reStructuredText.html">reStructuredText specification</a> document. These are relative links; if they @@ -77,7 +75,7 @@ <h2><a href="#contents" name="inline-markup" class="backref" >Inline Markup</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details</a>) <p>Inline markup allows words and phrases within text to have character styles (like italics and boldface) and functionality @@ -210,7 +208,7 @@ >Escaping with Backslashes</a></h2> <p>(<a - href="../../spec/rst/reStructuredText.html#backslashes">details?</a>) + href="../../spec/rst/reStructuredText.html#backslashes">details</a>) <p>reStructuredText uses backslashes ("\") to override the special meaning given to markup characters and get the literal characters @@ -258,7 +256,7 @@ <h2><a href="#contents" name="section-structure" class="backref" >Section Structure</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#sections">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#sections">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -297,7 +295,7 @@ <h2><a href="#contents" name="paragraphs" class="backref" >Paragraphs</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#paragraphs">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#paragraphs">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -325,7 +323,7 @@ <h2><a href="#contents" name="bullet-lists" class="backref" >Bullet Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#bullet-lists">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#bullet-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -363,7 +361,7 @@ <h2><a href="#contents" name="enumerated-lists" class="backref" >Enumerated Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#enumerated-lists">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#enumerated-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -399,7 +397,7 @@ <h2><a href="#contents" name="definition-lists" class="backref" >Definition Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#definition-lists">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#definition-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -440,7 +438,7 @@ <h2><a href="#contents" name="field-lists" class="backref" >Field Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#field-lists">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#field-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -479,7 +477,7 @@ <h2><a href="#contents" name="option-lists" class="backref" >Option Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#option-lists">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#option-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -527,7 +525,7 @@ <h2><a href="#contents" name="literal-blocks" class="backref" >Literal Blocks</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#literal-blocks">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#literal-blocks">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -606,7 +604,7 @@ This means that something like: <h2><a href="#contents" name="block-quotes" class="backref" >Block Quotes</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#block-quotes">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#block-quotes">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -635,7 +633,7 @@ This means that something like: <h2><a href="#contents" name="doctest-blocks" class="backref" >Doctest Blocks</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#doctest-blocks">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#doctest-blocks">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -671,7 +669,7 @@ This means that something like: <h2><a href="#contents" name="tables" class="backref" >Tables</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#tables">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#tables">details</a>) <p>There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are @@ -780,7 +778,7 @@ This means that something like: <h2><a href="#contents" name="transitions" class="backref" >Transitions</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#transitions">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#transitions">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -819,7 +817,7 @@ A transition marker is a horizontal line signaling changes in subject, time, point of view, or emphasis. <h2><a href="#contents" name="explicit-markup" class="backref" - >Explicit Markup</a></h3> + >Explicit Markup</a></h2> <p>Explicit markup blocks are used for constructs which float (footnotes), have no direct paper-document representation @@ -830,7 +828,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="footnotes" class="backref" >Footnotes</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -923,7 +921,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="citations" class="backref" >Citations</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#citations">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#citations">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -976,7 +974,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="hyperlink-targets" class="backref" >Hyperlink Targets</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details</a>) <h4><a href="#contents" name="external-hyperlink-targets" class="backref" >External Hyperlink Targets</a></h4> @@ -1056,7 +1054,7 @@ A transition marker is a horizontal line <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" >Indirect Hyperlink Targets</a></h4> - <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -1096,7 +1094,7 @@ A transition marker is a horizontal line <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" >Implicit Hyperlink Targets</a></h4> - <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details</a>) <p>Section titles, footnotes, and citations automatically generate hyperlink targets (the title text or footnote/citation label is @@ -1123,7 +1121,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="directives" class="backref" >Directives</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#directives">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#directives">details</a>) <p>Directives are a general-purpose extension mechanism, a way of adding support for new constructs without adding new syntax. For @@ -1151,7 +1149,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="substitution-references-and-definitions" class="backref" >Substitution References and Definitions</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details</a>) <p>Substitutions are like inline directives, allowing graphics and arbitrary constructs within text. @@ -1182,7 +1180,7 @@ dispose of medical waste.</samp> <h3><a href="#contents" name="comments" class="backref" >Comments</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#comments">details?</a>) + <p>(<a href="../../spec/rst/reStructuredText.html#comments">details</a>) <p>Any text which begins with an explicit markup start but doesn't use the syntax of any of the constructs above, is a comment. -- cgit v1.2.1 From 7a2ae317ae865392d8f63530c987c1cd6f558709 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 11 Jun 2003 16:06:48 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1419 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 ++ docs/user/tools.txt | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0383be561..c18a81aaa 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -317,6 +317,8 @@ General with examples of every setting (possibly commented). It's currently sparse, requiring doc lookups. +* Add front-end support for "-" => stdin/stdout. + Documentation ------------- diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 6b8382056..6c8c4e83d 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -609,7 +609,7 @@ source_link Include a "View document source" link in the document footer. URL will be relative to the destination. - Default: don't (None). Options: ``--source-link, + Default: don't (None). Options: ``--source-link, -s, --no-source-link``. source_url -- cgit v1.2.1 From dc8dca4f32421ea6fe1a6a20e7500201558b0216 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 12 Jun 2003 02:28:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1425 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c18a81aaa..b1e4f2668 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -937,6 +937,10 @@ when used in a document. - _`misc.settings`: Set any Docutils runtime setting from within a document? + - _`misc.charents`: Equivalent to:: + + .. include:: {includepath}/charents.txt + - 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 @@ -1734,6 +1738,13 @@ 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. +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 <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, +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 -- cgit v1.2.1 From 8d87788ce3afbd0e4274d14c85b897eb913739b6 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 13 Jun 2003 16:55:42 +0000 Subject: Add rubric support. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1445 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index fb5b51d13..4ab2e1d7b 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -109,6 +109,14 @@ docinfowidth The width for the docinfo table. Default: 0.9*textwidth, changed to e.g.:: \setlength{\docinfowidth}{0.7\textwidth} +--------------------- ------------------------------------------------ +rubric style The header contains the definition of a new + LaTeX command rubric. The line:: + + \renewcommand{\rubric}[1]{{\LARGE #1}} + + changes the style of rubric to left aligned, + LARGE text. ===================== ================================================ Missing options -- cgit v1.2.1 From d8757edc730c6dd045521917b437a5b2fce66593 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 14 Jun 2003 07:00:26 +0000 Subject: change rubric style to subsection italic. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1449 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 4ab2e1d7b..d90523c9e 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -111,12 +111,14 @@ docinfowidth The width for the docinfo table. \setlength{\docinfowidth}{0.7\textwidth} --------------------- ------------------------------------------------ rubric style The header contains the definition of a new - LaTeX command rubric. The line:: + LaTeX command rubric. Inserting:: - \renewcommand{\rubric}[1]{{\LARGE #1}} + \renewcommand{\rubric}[1]{\subsection*{ + ~\hfill {\color{red} #1} \hfill ~}} - changes the style of rubric to left aligned, - LARGE text. + sets rubric to subsection style in red. + + Default: subsection style italic. ===================== ================================================ Missing options -- cgit v1.2.1 From 4d5856ed0b53ed121be993e520271fc0e4a1ce55 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 16 Jun 2003 03:26:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1470 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 37 ++++++++++++++++++++++++------------- docs/peps/pep-0258.txt | 21 ++++++++++++--------- 2 files changed, 36 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b1e4f2668..f742ef9c7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -297,11 +297,6 @@ General option could be added to Docutils front ends to do this. (Idea from Engelbert Gruber.) -* Should I/O objects be passed simple encoding name strings instead of - a full-blown settings object? Yes. - - @@@ Remove "settings" parameters before next release. - * Change the "class" attribute of elements (set with Element.set_class) to a list? @@ -317,8 +312,6 @@ General with examples of every setting (possibly commented). It's currently sparse, requiring doc lookups. -* Add front-end support for "-" => stdin/stdout. - Documentation ------------- @@ -1160,7 +1153,7 @@ when used in a document. <literal_block xml:space="preserve" class="python"> <keyword>print</> <string>'This is Python code.'</> - <keyword>for</> <identifier>i</> <keyword + <keyword>for</> <identifier>i</> <keyword >in</> <expression>range(10)</>: <keyword>print</> <expression>i</> </literal_block> @@ -1927,7 +1920,7 @@ projects in sync when there are changes made to the core Docutils code. -Release Checklist +Release Procedure ================= * Edit the version number in the following files: @@ -1942,16 +1935,34 @@ Release Checklist * Run the test suite: ``cd test ; alltests.py``. -* Create the release tarball. (@@@ Expand this.) +* Create the release tarball: + + 1. Create a new empty directory and ``cd`` into it. + + 2. Get a clean snapshot of the CVS files:: + + cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \ + export -rHEAD docutils + + 3. Use Distutils to create the release tarball:: + + cd docutils + python setup.py sdist + +* Expand and install the release tarball **in isolation**: -* Expand and install the release tarball in isolation (no PYTHONPATH, - clear out old installation, etc.). + 1. Remove the old installation from site-packages (including + roman.py, and optparse.py, textwrap.py for pre-2.3 + installations). + 2. Expand the tarball in a new location, not over any existing files. + 3. Clear/unset the PYTHONPATH environment variable. + 4. ``python setup.py install`` * Run the test suite from the expanded archive directory: ``cd test ; alltests.py``. * Run ``cd tools ; buildhtml.py ..`` to confirm that there are no - major problems with the docs. + unexpected issues with the docs. .. diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index c984cd0ad..09bec5d88 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -366,13 +366,6 @@ Docutils Package Structure element class library plus tree-traversal Visitor pattern base classes. See `Document Tree`_ below. - - Module "docutils.optik" provides option parsing and command-line - help; from Greg Ward's http://optik.sf.net/ project, included for - convenience. - - - Module "docutils.roman" contains Roman numeral conversion - routines. - - Module "docutils.statemachine" contains a finite state machine specialized for regular-expression-based text filters and parsers. The reStructuredText parser implementation is based on this @@ -455,11 +448,21 @@ Docutils Package Structure - Function "get_language(language_code)", returns matching language module. (``docutils/languages/__init__.py``) - - Modules: en.py (English), de.py (German), fr.py (French), sk.py - (Slovak), sv.py (Swedish). + - Modules: en.py (English), de.py (German), fr.py (French), it.py + (Italian), sk.py (Slovak), sv.py (Swedish). - Other languages to be added. +* Third-party modules: "extras" directory. These modules are + installed only if they're not already present in the Python + installation. + + - ``extras/optparse.py`` and ``extras/textwrap.py`` provide + option parsing and command-line help; from Greg Ward's + http://optik.sf.net/ project, included for convenience. + + - ``extras/roman.py`` contains Roman numeral conversion routines. + Front-End Tools =============== -- cgit v1.2.1 From 5d7980f4bff963f41deb58c2360a47469ec8a48c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 16 Jun 2003 03:55:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1471 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f742ef9c7..fe1a67604 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1935,6 +1935,14 @@ Release Procedure * Run the test suite: ``cd test ; alltests.py``. +* Isolate from outside influence: + + 1. Remove the old installation from site-packages (including + roman.py, and optparse.py, textwrap.py for pre-2.3 + installations). + + 2. Clear/unset the PYTHONPATH environment variable. + * Create the release tarball: 1. Create a new empty directory and ``cd`` into it. @@ -1951,12 +1959,9 @@ Release Procedure * Expand and install the release tarball **in isolation**: - 1. Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py for pre-2.3 - installations). - 2. Expand the tarball in a new location, not over any existing files. - 3. Clear/unset the PYTHONPATH environment variable. - 4. ``python setup.py install`` + 1. Expand the tarball in a new location, not over any existing files. + + 2. ``python setup.py install`` * Run the test suite from the expanded archive directory: ``cd test ; alltests.py``. -- cgit v1.2.1 From e06cf51d3dede234202492119c983807952a5522 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 16 Jun 2003 04:34:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1475 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index e27b69381..f03174fce 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -135,6 +135,15 @@ attribute: The keys should be translated to the target language. +``roles`` + + This is a mapping language-dependent role names to canonical role + names for interpreted text. The canonical directive names are + registered in ``docutils/parsers/rst/states.py``, in + ``Inliner._interpreted_roles`` (this may change). + + The keys should be translated to the target language. + Testing the Language Modules ============================ -- cgit v1.2.1 From 7592ea40f88e6901efa7b8f67dc9ca09cf5de441 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 16 Jun 2003 05:03:31 +0000 Subject: blank git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1476 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index f03174fce..8c13ac580 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -136,7 +136,6 @@ attribute: The keys should be translated to the target language. ``roles`` - This is a mapping language-dependent role names to canonical role names for interpreted text. The canonical directive names are registered in ``docutils/parsers/rst/states.py``, in -- cgit v1.2.1 From a546d701795706cda0f378fb29f18fa5a45c1c9f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 16 Jun 2003 17:31:37 +0000 Subject: Added "exit_level" setting ("--exit" option). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1479 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 6c8c4e83d..5012be308 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -468,6 +468,14 @@ error_encoding_error_handler otherwise. Options: ``--error-encoding-error-handler, --error-encoding, -e``. +exit_level + A system message level threshold; non-halting system messages at + or above this level will produce a non-zero exit status at normal + exit. Exit status is the maximum system message level plus 10 (11 + for INFO, etc.). + + Default: disabled (5). Options: ``--exit``. + expose_internals List of internal attribues to expose as external attributes (with "internal:" namespace prefix). -- cgit v1.2.1 From 4ae66667744277e09e730b7a7762d665b1739462 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 17 Jun 2003 07:29:46 +0000 Subject: A example for papersize. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1487 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index d90523c9e..88de8c60b 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -90,6 +90,10 @@ papersize Default: a4paper. Paper geometry can be changed * landscape, portrait, twoside. and a ton of other option setting margins. + + An example:: + + \geometry{a5paper,landscape} --------------------- ------------------------------------------------ paragraph indent By default latex indents the forst line in a paragraph. The following lines set indentation -- cgit v1.2.1 From 20e87fa4f9ffbbebe7263362af51618aa5c2e785 Mon Sep 17 00:00:00 2001 From: tibs <tibs@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 19 Jun 2003 11:37:17 +0000 Subject: Remove the no-longer-working email address "tony@lsl.co.uk". git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1491 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 438e82ce8..b60cbf1b0 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -1234,8 +1234,7 @@ dispose of medical waste.</samp> <address> <p>Authors: <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or - <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) + (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) and David Goodger (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) </address> -- cgit v1.2.1 From 07e99283acdc2bc67dc0b75f596fbe468ab3ccd3 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 21 Jun 2003 03:30:51 +0000 Subject: Take care of too wide tables (dave abrahams). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1492 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 88de8c60b..fbcfad782 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -181,6 +181,8 @@ Tables tablewidth is set relative to this value. If someone produces documents with line length of 132 this will fail. + Table width is tried to fit in page even if it is wider than + the assumed linewidth, still assumed linewidth is a hook. * In tools.txt the option tables right column, there should be some more spacing between the description and the next paragraph "Default:". -- cgit v1.2.1 From 32a23ee7c9485ff3e220a84e098265eb38ebc068 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 21 Jun 2003 04:03:04 +0000 Subject: font selection. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1493 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index fbcfad782..1b3d0b53b 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -123,6 +123,8 @@ rubric style The header contains the definition of a new sets rubric to subsection style in red. Default: subsection style italic. +--------------------- ------------------------------------------------ +font selection see below ===================== ================================================ Missing options @@ -131,6 +133,21 @@ Missing options * Selection of latex fontsize. * Assumed reST linelength for table width setting. +Font selection +-------------- + +When generating pdf-files from LaTeX, use the pdflatex command, the files +are a lot smaller if postscript fonts are used. To do so put +``\usepackage{times}`` into the styleshee + +It is said that the typewriter font in computer modern font, the default +LaTeX font package, is too heavy compared to the others. There is a package +or some commands too fix this, which i currently cannot find. + +Some people diagnose a similar unbalance for the postscript fonts, the +package to fix this is ```\usepackage{pslatex}``. + + Commands directly to LaTeX ========================== -- cgit v1.2.1 From 34e673460e676a67ed552c7c66e2381c6e0c2dbb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 22 Jun 2003 22:21:28 +0000 Subject: added comments to "unicode" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1494 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0761e21bb..0dd63e154 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -846,23 +846,27 @@ Unicode Character Codes :Directive Type: "unicode" :Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes - & text). +:Directive Arguments: One or more, required (Unicode character codes, + optional text, and comments). :Directive Options: None. :Directive Content: None. The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numbered -character entities (e.g. ``ᨫ``). Codes may be upper- or -lowercase. Spaces are ignored, and any other text remains as-is. +``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric +character entities (e.g. ``ᨫ``). Codes are case-insensitive. + +Text following " .. " is a comment and is ignored. Spaces are +ignored, and any other text remains as-is. Example:: - "|copy|" is the copyright symbol. + Copyright |copy| 2003, |BogusMegaCorp (TM)|. - .. |copy| unicode:: 0xA9 + .. |copy| unicode:: 0xA9 .. copyright sign + .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 + .. with trademark sign Class -- cgit v1.2.1 From 35268ac488831635e492cf6b193950765ce507b9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 22 Jun 2003 22:47:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1495 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fe1a67604..775771442 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -636,6 +636,9 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. +* 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 -- cgit v1.2.1 From 01385ee6e20091f864e1966e5709d935a8646181 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 23 Jun 2003 04:41:22 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1498 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 775771442..26c944ba3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -41,11 +41,18 @@ Bugs Idea: two-pass hyperlink resolution, ignoring errors on the first pass? + Perhaps the directive should do a bit more work up-front: create the + "topic" and "title", and leave the "pending" node for contents. + * 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. +* In text inserted by the "include" directive, errors are often not + reported with the correct "source" or "line" numbers. Perhaps all + Reporter calls need a "base_node" parameter. + General ------- -- cgit v1.2.1 From 178416c046fdd3b8826b2ecdf2625cf18b0559b9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Jun 2003 15:19:18 +0000 Subject: added "Nested Inline Markup" section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1500 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 111 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index a5bc28f62..edcd29f71 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -184,10 +184,10 @@ email mode, where we may be able to rely on less complex structure Multiple Roles in Interpreted Text ---------------------------------- -In reStructuredText, inline markup cannot be nested. This also -applies to interpreted text. In order to simultaneously combine -multiple roles for a single piece of text, a syntax extension would be -necessary. Ideas: +In reStructuredText, inline markup cannot be nested (yet; `see +below`__). This also applies to interpreted text. In order to +simultaneously combine multiple roles for a single piece of text, a +syntax extension would be necessary. Ideas: 1. Initial idea:: @@ -201,6 +201,8 @@ If a document is so complex as to require nested inline markup, perhaps another markup system should be considered. By design, reStructuredText does not have the flexibility of XML. +__ `Nested Inline Markup`_ + Parameterized Interpreted Text ------------------------------ @@ -1875,6 +1877,107 @@ Solution 3 was chosen for incorporation into the document tree model. .. _HTML: http://www.w3.org/MarkUp/ +Nested Inline Markup +==================== + +These are collected notes on a long-discussed issue. The original +mailing list messages should be referred to for details. + +* In a 2001-10-31 discussion I wrote: + + Try, for example, `Ed Loper's 2001-03-21 post`_, which details + some rules for nested inline markup. I think the complexity is + prohibitive for the marginal benefit. (And if you can understand + that tree without going mad, you're a better man than I. ;-) + + Inline markup is already fragile. Allowing nested inline markup + would only be asking for trouble IMHO. If it proves absolutely + necessary, it can be added later. The rules for what can appear + inside what must be well thought out first though. + + .. _Ed Loper's 2001-03-21 post: + http://mail.python.org/pipermail/doc-sig/2001-March/001487.html + + -- http://mail.python.org/pipermail/doc-sig/2001-October/002354.html + +* In a 2001-11-09 Doc-SIG post, I wrote: + + The problem is that in the + what-you-see-is-more-or-less-what-you-get markup language that + is reStructuredText, the symbols used for inline markup ("*", + "**", "`", "``", etc.) may preclude nesting. + + I've rethought this position. Nested markup is not precluded, just + tricky. People and software parse "double and 'single' quotes" all + the time. Continuing, + + I've thought over how we might implement nested inline + markup. The first algorithm ("first identify the outer inline + markup as we do now, then recursively scan for nested inline + markup") won't work; counterexamples were given in my `last post + <http://mail.python.org/pipermail/doc-sig/2001-November/002363.html>`__. + + The second algorithm makes my head hurt:: + + while 1: + scan for start-string + if found: + push on stack + scan for start or end string + if new start string found: + recurse + elif matching end string found: + pop stack + elif non-matching end string found: + if its a markup error: + generate warning + elif the initial start-string was misinterpreted: + # e.g. in this case: ***strong** in emphasis* + restart with the other interpretation + # but it might be several layers back ... + ... + + This is similar to how the parser does section title + recognition, but sections are much more regular and + deterministic. + + Bottom line is, I don't think the benefits are worth the effort, + even if it is possible. I'm not going to try to write the code, + at least not now. If somebody codes up a consistent, working, + general solution, I'll be happy to consider it. + + -- http://mail.python.org/pipermail/doc-sig/2001-November/002388.html + +* In a `2003-05-06 Docutils-Users post`__ Paul Tremblay proposed a new + syntax to allow for easier nesting. It eventually evolved into + this:: + + :role:[inline text] + + The duplication with the existing interpreted text syntax is + problematic though. + + __ http://article.gmane.org/gmane.text.docutils.user/317 + +* Could the parser be extended to parse nested interpreted text? :: + + :emphasis:`Some emphasized text with :strong:`some more + emphasized text` in it and **perhaps** :reference:`a link`` + +* In a `2003-06-18 Docutils-Develop post`__, Mark Nodine reported on + his implementation of a form of nested inline markup in his + Perl-based parser (unpublished). He brought up some interesting + ideas. The implementation was flawed, however, by the change in + semantics required for backslash escapes. + + __ http://article.gmane.org/gmane.text.docutils.devel/795 + +It may be possible to accomplish nested inline markup in general with +a more powerful inline markup parser. There may be some issues, but +I'm not averse to the idea of nested inline markup in general. I just +don't have the time or inclination to write a new parser now. Of +course, a good patch would be welcome! + .. Local Variables: -- cgit v1.2.1 From 64e05c6cc5be2f4f8fe77743fcbed81bff5f6585 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Jun 2003 15:20:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1501 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 22 ++++------------------ 1 file changed, 4 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 26c944ba3..cd1eac774 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -807,6 +807,10 @@ __ rst/alternatives.html#or-not-to-do Perhaps. Perhaps not. +* Add new syntax for _`nested inline markup`? Or extend the parser to + parse nested inline markup somehow? See the `collected notes + <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. + Directives `````````` @@ -1306,24 +1310,6 @@ elements. The advantage of the new syntax would be flexibility. Uses other than "class" may present themselves. -* Add new syntax for _`nested inline markup`? From a proposal by Paul - Tremblay:: - - :role:[inline text] - - Or extend the parser to parse nested interpreted text? :: - - :emphasis:`Some emphasized text with :strong:`some more - emphasized text` in it and **perhaps** :reference:`a link`` - - See the docutils-users `"nested inline tags" thread`__ and earlier - discussions - (http://mail.python.org/pipermail/doc-sig/2001-November/002388.html - and - http://mail.python.org/pipermail/doc-sig/2001-November/002363.html). - - __ http://sf.net/mailarchive/forum.php?thread_id=2073680&forum_id=11444 - * Perhaps a "role" directive can modify existing roles with attributes? :: -- cgit v1.2.1 From 621e76899b06dfc39058fda7b6bdf77df282d8e6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Jun 2003 15:31:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1503 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index cd1eac774..15e9773f0 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -51,7 +51,9 @@ Bugs * In text inserted by the "include" directive, errors are often not reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need a "base_node" parameter. + Reporter calls need a "base_node" parameter. There's a test in + test/test_parsers/test_rst/test_directives/test_include.py + (commented out, because the test fails). General -- cgit v1.2.1 From b48b803fa2457708113c059d539e9053abdaeb3f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Jun 2003 01:47:04 +0000 Subject: ready for release 0.3 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1504 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 113 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 86 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 15e9773f0..2b26acf03 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1921,51 +1921,110 @@ code. Release Procedure ================= -* Edit the version number in the following files: +1. Edit the version number in the following files: - + docutils: + * docutils: - - setup.py - - HISTORY.txt - - docutils/__init__.py + - setup.py + - HISTORY.txt + - docutils/__init__.py - + web: index.txt + * web: index.txt -* Run the test suite: ``cd test ; alltests.py``. +2. Run the test suite: ``cd test ; alltests.py``. -* Isolate from outside influence: +3. Isolate from outside influence: - 1. Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py for pre-2.3 - installations). + (a) Remove the old installation from site-packages (including + roman.py, and optparse.py, textwrap.py for pre-2.3 + installations). - 2. Clear/unset the PYTHONPATH environment variable. + (b) Clear/unset the PYTHONPATH environment variable. -* Create the release tarball: +4. Create the release tarball: - 1. Create a new empty directory and ``cd`` into it. + (a) Create a new empty directory and ``cd`` into it. - 2. Get a clean snapshot of the CVS files:: + (b) Get a clean snapshot of the CVS files:: - cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \ - export -rHEAD docutils + cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \ + export -rHEAD docutils - 3. Use Distutils to create the release tarball:: + (c) Use Distutils to create the release tarball:: - cd docutils - python setup.py sdist + cd docutils + python setup.py sdist -* Expand and install the release tarball **in isolation**: +5. Expand and install the release tarball **in isolation** (as per + step 3 above): - 1. Expand the tarball in a new location, not over any existing files. + (a) Expand the tarball in a new location, not over any existing + files. - 2. ``python setup.py install`` + (b) ``python setup.py install`` -* Run the test suite from the expanded archive directory: ``cd test ; - alltests.py``. +6. Run the test suite from the expanded archive directory: ``cd test ; + alltests.py``. -* Run ``cd tools ; buildhtml.py ..`` to confirm that there are no - unexpected issues with the docs. +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@lists.sourceforge.net + * docutils-users@lists.sourceforge.net + * doc-sig@python.org + * python-list@python.org + * python-announce@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? .. -- cgit v1.2.1 From 159b168a1eb5dd71d2fc5c346e8f8ef527ecd16d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 25 Jun 2003 02:25:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1506 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2b26acf03..514789b22 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -55,6 +55,11 @@ Bugs test/test_parsers/test_rst/test_directives/test_include.py (commented out, because the test fails). +* tools/buildhtml.py needs a mechanism to skip directories + (e.g. licenses, test). Perhaps a ".prune-buildhtml" file? A + command-line option wouldn't work because it would require user + action. + General ------- @@ -1961,7 +1966,12 @@ Release Procedure (a) Expand the tarball in a new location, not over any existing files. - (b) ``python setup.py install`` + (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``. -- cgit v1.2.1 From 95ef74bb317f78ef64addb296b4b9df3da819792 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 26 Jun 2003 18:36:15 +0000 Subject: explain ISO 3166 subtags git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1511 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 8c13ac580..a679f9aa9 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -48,12 +48,16 @@ Language modules are named using a case-insensitive language identifier as defined in `RFC 1766`_. A typical language identifier consists of a 2-letter language code from `ISO 639`_ (3-letter codes can be used if no 2-letter code exists; RFC 1766 is currently being -revised to allow 3-letter codes). If no language identifier is +revised to allow 3-letter codes). The language identifier can have an +optional subtag, typically for variations based on country (from `ISO +3166`_ 2-letter country codes). If no language identifier is specified, the default is "en" for English. Examples of module names -include ``en.py``, ``fr.py``, and ``ja.py`` +include ``en.py``, ``fr.py``, ``ja.py``, and ``pt-br.py``. .. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html +.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/ + 02iso-3166-code-lists/index.html Python Code -- cgit v1.2.1 From 75c8fe7bbd61005c982c51b1ba2c55fefc5777de Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 27 Jun 2003 15:05:09 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1514 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 17 +++++++++++++++++ docs/dev/todo.txt | 2 +- 2 files changed, 18 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index edcd29f71..b089d58b2 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1978,6 +1978,23 @@ I'm not averse to the idea of nested inline markup in general. I just don't have the time or inclination to write a new parser now. Of course, a good patch would be welcome! +I envisage something like this. Explicit-role interpreted text must +be nestable. Prefix-based is probably preferred, since suffix-based +will look like inline literals:: + + ``text`:role1:`:role2: + +But it can be disambiguated, so it ought to be left up to the author:: + + `\ `text`:role1:`:role2: + +In addition, other forms of inline markup may be nested if +unambiguous:: + + *emphasized ``literal`` and |substitution ref| and link_* + +IOW, the parser ought to be as permissive as possible. + .. Local Variables: diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 514789b22..886b3fa78 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1258,7 +1258,7 @@ 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. -* Add a test for language mappings. +* @@@ Add a test for language mappings of roles. * Alan Jaffray suggested (and I agree) that it would be sensible to: -- cgit v1.2.1 From d3b536fa3c58d6e267882311e4eb3ec057f4214f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 28 Jun 2003 04:31:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1518 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index a679f9aa9..11a8d13bd 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -98,7 +98,8 @@ Each Docutils language module contains three module attributes: components when they encounter document tree elements whose class names are the mapping keys. - The entry values should be translated to the target language. + The entry values (*not* the keys) should be translated to the + target language. ``bibliographic_fields`` This is a mapping of language-dependent field names (converted to @@ -137,7 +138,9 @@ attribute: registered in ``docutils/parsers/rst/directives/__init__.py``, in ``_directive_registry``. - The keys should be translated to the target language. + The keys should be translated to the target language. Synonyms + (multiple keys with the same values) are allowed; this is useful + for abbreviations. ``roles`` This is a mapping language-dependent role names to canonical role @@ -145,7 +148,9 @@ attribute: registered in ``docutils/parsers/rst/states.py``, in ``Inliner._interpreted_roles`` (this may change). - The keys should be translated to the target language. + The keys should be translated to the target language. Synonyms + (multiple keys with the same values) are allowed; this is useful + for abbreviations. Testing the Language Modules -- cgit v1.2.1 From c0094853f248b511348b5976da81a829f572b986 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 29 Jun 2003 04:55:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1526 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 886b3fa78..3b86cc09b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -322,6 +322,18 @@ General enabling a section for each Docutils component so that (for example) HTML's and LaTeX's stylesheets don't interfere with each other. + Idea: adopt sections in the config file corresponding to Docutils + components, which define flat namespaces that can be applied in an + overlay fashion defined by the components themselves. For example, + if the "pep_html" writer defines itself as derivative of the + "html4css1" writer, the "stylesheet" setting in the "[html4css1]" + section will be used unless the "[pep_html]" section overrides it. + In the absence of any "stylesheet" setting in either section, a + "stylesheet" setting in "[general]" would be used. This would also + allow component-specific definitions of general or + other-component-specific settings, such as writer-specific overrides + for the "trim_footnote_reference_space" parser setting. + * The "docutils.conf" included with Docutils should become complete, with examples of every setting (possibly commented). It's currently sparse, requiring doc lookups. -- cgit v1.2.1 From c6f916cd102138083ff84c41df35e84fc00cf277 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 30 Jun 2003 16:04:34 +0000 Subject: Added "traceback" setting. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1535 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 5012be308..b9af291f6 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -652,6 +652,12 @@ toc_backlinks Default: "entry". Options: ``--toc-entry-backlinks, --toc-top-backlinks, --no-toc-backlinks``. +traceback + Enable Python tracebacks when an error occurs. + + Default: disabled (None). Options: ``--traceback, + --no-traceback``. + trim-footnote-reference-space (reStructuredText Parser.) Remove spaces before footnote references. -- cgit v1.2.1 From ed3436ae71ddcc09dfe7d2be38c01f90934cf486 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jul 2003 02:23:49 +0000 Subject: added explicit targets of directive names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1536 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 0dd63e154..5fc316a99 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -45,6 +45,16 @@ type definition. Admonitions ------------- +.. _attention: +.. _caution: +.. _danger: +.. _error: +.. _hint: +.. _important: +.. _note: +.. _tip: +.. _warning: + Specific Admonitions ==================== @@ -99,6 +109,8 @@ bullet list consisting of two list items:: - It includes this bullet list. +.. _admonition: + Generic Admonition ================== @@ -401,6 +413,8 @@ The following option is recognized: class_ directive below. +.. _parsed-literal: + Parsed Literal Block ==================== @@ -503,7 +517,7 @@ Produces a highlights-class block quote. See Epigraph_ above. Pull-Quote ========== -:Directive Type: "pull_quote" +:Directive Type: "pull-quote" :Doctree Element: block_quote :Directive Arguments: None. :Directive Options: None. @@ -516,6 +530,8 @@ Produces a pull-quote-class block quote. See Epigraph_ above. Document Parts ---------------- +.. _contents: + Table of Contents ================= @@ -578,6 +594,9 @@ The following options are recognized: class_ directive below. +.. _sectnum: +.. _section-autonumbering: + Automatic Section Numbering =========================== @@ -612,6 +631,8 @@ The following options are recognized: References ------------ +.. _target-notes: + Target Footnotes ================ @@ -728,6 +749,8 @@ Non-standard element: imagemap. Miscellaneous --------------- +.. _include: + Including an External Document Fragment ======================================= @@ -767,6 +790,8 @@ The following options are recognized: literal block (useful for program listings). +.. _raw: + Raw Data Pass-Through ===================== @@ -812,6 +837,8 @@ The following options are recognized: An Internet URL reference to a raw data file to be included. +.. _replace: + Replacement Text ================ @@ -841,6 +868,8 @@ the "replace" directive:: .. _Python: http://www.python.org/ +.. _unicode: + Unicode Character Codes ======================= -- cgit v1.2.1 From f565dc4f3160a9646d72d0b0c5f7f1cb73d0431e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jul 2003 02:24:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1537 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3b86cc09b..0d937e255 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -746,9 +746,10 @@ __ rst/alternatives.html#or-not-to-do * Generalize the "target-notes" directive into a command-line option somehow? See docutils-develop 2003-02-13. -* Include (after any necessary cleanup & completion) David Priest's - substitution table for character entities; see - <http://article.gmane.org/gmane.comp.python.documentation/432>. +* Include the _`character entity substitution definition files` + `temporarily stored here <tmp/charents>`__, perhaps in a + ``docutils/parsers/rst/includes/`` directory. See `misc.include`_ + below. * Should ^L (or something else in reST) be defined to mean force/suggest page breaks in whatever output we have? @@ -914,6 +915,30 @@ when used in a document. Option to label lines? + Default directory for "built-in includes", using the C syntax + ``#include <name>``? + + Use C-preprocessor semantics for locating include files? + E.g., ``.. include:: file.txt`` will read another file into + the current one, relative to the current file's directory, and + ``.. include:: <standard>`` will read a standard include file + from ``docutils/include/``. (Should "quotes" be required + around non-standard include files?) + + -- http://sf.net/mailarchive/message.php?msg_id=1938401 + + I now think that ``docutils/parsers/rst/include/`` is a better + place for these files, since they're reStructuredText-specific. + + Keeping standard data files together with the package code makes + sense to me. It seems much less complex to implement than a + separate system data directory, such as ``/usr/share/docutils``. + Any reason a system data directory should be used? How does + Distutils handle data files? + + For a specific application, see the discussion of `character + entity substitution definition files`_ above. + * Implement directives. Each of the list items below begins with an identifier of the form, "module_name.directive_function_name". The directive name itself could be the same as the -- cgit v1.2.1 From 5bc35df9224dbf152ac6384f8b66e9f6328b7192 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jul 2003 13:26:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1545 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0d937e255..96650ea7b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -831,6 +831,27 @@ __ rst/alternatives.html#or-not-to-do parse nested inline markup somehow? See the `collected notes <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. +* Idea from Beni Cherniavsky:: + + I'm writing a README document linking to all other interesting + files in its directory. If these were full URLs I could just + write them in the text but these are relative links that can't + be auto-recognized. The shortest way to make such links that I + found was `file_name <file_name>`_. Perhaps a shortcut for such + usage could be added, e.g. `<file_name>`_ would take the target + as the link name? + + IOW these would be equivalent:: + + `<file_name>`_ + `file_name <file_name>`_ + + Another possibility is to drop the backticks. Should the angle + brackets be kept in the output or not? This syntax could be adopted + in addition to the one above:: + + <file_name>_ + Directives `````````` -- cgit v1.2.1 From 6689573fc15a5d47f7ad736ae5524f4e930407d8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Jul 2003 03:22:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1548 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 54 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 96650ea7b..eab2208fe 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -338,6 +338,10 @@ General with examples of every setting (possibly commented). It's currently sparse, requiring doc lookups. +* Add internationalization to footer boilerplate text (resulting from + "--generator", "--source-link", and "--date" etc.), allowing + translations. + Documentation ------------- @@ -929,36 +933,42 @@ when used in a document. Add an option to include topics in the TOC? Another for sidebars? See docutils-develop 2003-01-29. - - _`misc.include`: "encoding" option? Take default from runtime - settings. Use Input component to read it in? + - _`misc.include`: + + - "encoding" option? Take default from runtime settings. Use + Input component to read it in? + + - Option to select a range of lines? - Option to select a range of lines? + - Option to label lines? - Option to label lines? + - Default directory for "built-in includes", using the C syntax + ``#include <name>``? - 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?) - 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 - -- 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. - 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? - 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. + For a specific application, see the discussion of `character + entity substitution definition files`_ above. * Implement directives. Each of the list items below begins with an identifier of the form, "module_name.directive_function_name". The -- cgit v1.2.1 From ec700704b14f4c3fc540cfa3dc62bf105f95730f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jul 2003 22:08:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 52 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index eab2208fe..333334877 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -58,7 +58,7 @@ Bugs * tools/buildhtml.py needs a mechanism to skip directories (e.g. licenses, test). Perhaps a ".prune-buildhtml" file? A command-line option wouldn't work because it would require user - action. + action. Config file setting? General @@ -318,25 +318,32 @@ General reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output? -* Perhaps we need to re-evaluate the config file format, possibly - enabling a section for each Docutils component so that (for example) - HTML's and LaTeX's stylesheets don't interfere with each other. - - Idea: adopt sections in the config file corresponding to Docutils - components, which define flat namespaces that can be applied in an - overlay fashion defined by the components themselves. For example, - if the "pep_html" writer defines itself as derivative of the - "html4css1" writer, the "stylesheet" setting in the "[html4css1]" - section will be used unless the "[pep_html]" section overrides it. - In the absence of any "stylesheet" setting in either section, a - "stylesheet" setting in "[general]" would be used. This would also - allow component-specific definitions of general or - other-component-specific settings, such as writer-specific overrides - for the "trim_footnote_reference_space" parser setting. +* @@@ Re-evaluate the config file format, enabling a section for each + Docutils component so that (for example) HTML's and LaTeX's + stylesheets don't interfere with each other. + + Details: <http://article.gmane.org/gmane.text.docutils.devel/876>. + +* Rationalize Writer settings (HTML/LaTeX/PEP). * The "docutils.conf" included with Docutils should become complete, - with examples of every setting (possibly commented). It's currently - sparse, requiring doc lookups. + with examples of every setting (many/most commented out). It's + currently sparse, requiring doc lookups. + +* Rework docs/tools.txt for the new configuration sections. Merge + doc/latex.txt info into tools.txt. + +* Add validation/conversion to SettingsSpec objects? Entry in the + keyword argument dictionary, to be handled by OptionParser? How to + pass it on to ConfigParser? Or keep the exclusive responsibility in + OptionParser? Problem with the current "validation" attribute of + docutils.frontend.ConfigParser is that it separates this information + from the rest of the settings_spec. + + Specifically, boolean values like "xml_declaration" ought to accept + "0" for false (not just '' empty string as now), and "false", "no", + and "off" too. True values should be any of "1", "true", "yes", and + "on". * Add internationalization to footer boilerplate text (resulting from "--generator", "--source-link", and "--date" etc.), allowing @@ -1211,8 +1218,17 @@ when used in a document. 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 -- cgit v1.2.1 From e25f1ab32f676a18f0cc3cc6ab2a62e40dabf17e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jul 2003 21:15:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1576 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 333334877..de3a33d14 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -673,6 +673,73 @@ __ rst/alternatives.html#or-not-to-do first blank line ends it) where every line begins with the same non-alphanumeric non-whitespace character. + On 2003-06-17 Peter Simons requested a similar feature in the + "Literal Haskell Support" thread on docutils-develop. Regarding + this to-do item, he wrote + + I think that the '::' solution is not optimal. IMHO the leading + '>' should be enough for "docutils-hs2whatever" to know this is + a code block. In a perfect world, additional mark-up should not + be required. + + My reply was + + Who said it's a perfect world? ;-) + + The "::" reduces ambiguity, especially in the case of + single-line quoted blocks with certain quote characters. + + Do we limit the characters that can be used for quoting? If so, + what characters? Or would all non-alphanumeric non-whitespace 7-bit + ASCII characters be OK? This would include all of these:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + There are many situations where some kind of left border is used for + quoting. I've often seen vertical bars used:: + + | Quoted text + | here. + + I've seen legal documents that have something like this:: + + ) Quoted text + ) here. + + Or was it the other way around? :: + + ( Quoted text + ( here. + + A problem: if whitespace wasn't required, this could occur + accidentally in ordinary text:: + + (Quoted text here?) + + I think we'd have to require whitespace (perhaps allowing for + multiple quote characters before the whitespace, which would allow + for email). + + What about asterisks? :: + + * Quoted text + * here. + + Big problem! That's a bullet list. So we can't allow "*", "-", or + "+", unless we disambiguate with "::". + + Other conceivable quote characters include: # $ % : ; = [ ] { } + + If we required multiple lines, it would be easier to be sure the + text is unambiguous. I don't think we can require that though. + + Another issue: do the quoting characters stay in the literal block + (i.e., do they show up in the processed document)? + + Relax the "::" requirement somehow? Runtime setting & directive to + specify literal line prefix? Extend to doctest-like blocks (marker + on the first line sufficient)? + * Should the "doctest" element go away, and the construct simply be a front-end to generic literal blocks? -- cgit v1.2.1 From 5fa4d3b2f10a3fb657a03e04733b4f0a346b6dcc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Jul 2003 18:00:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1578 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index 377ca31ad..85a7b9a4b 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -132,8 +132,11 @@ value ``None``. Three directive function attributes are recognized: argument (raises ``ValueError`` if found), returns ``None`` for valid flag options. - - ``unchanged``: Returns the argument, unchanged. Raises - ``ValueError`` if no argument is found. + - ``unchanged_required``: Returns the text argument, unchanged. + Raises ``ValueError`` if no argument is found. + + - ``unchanged``: Returns the text argument, unchanged. Returns an + empty string ("") if no argument is found. - ``path``: Returns the path argument unwrapped (with newlines removed). Raises ``ValueError`` if no argument is found or if the @@ -142,6 +145,10 @@ value ``None``. Three directive function attributes are recognized: - ``nonnegative_int``: Checks for a nonnegative integer argument, and raises ``ValueError`` if not. + - ``class_option``: Converts the argument into an ID-compatible + string and returns it. Raises ``ValueError`` if no argument is + found. + A further utility function, ``choice``, is supplied to enable options whose argument must be a member of a finite set of possible values. A custom conversion function must be written to use it. -- cgit v1.2.1 From 34a400ee099f773ca96b1820d30a92779987cd44 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jul 2003 06:22:52 +0000 Subject: updates git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1582 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index b089d58b2..7baf71714 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -296,7 +296,13 @@ of substitution definitions can be devised. A "unicode" directive has been implemented to allow direct specification of esoteric characters. In combination with the substitution construct, "include" files defining common sets of -character entities can be defined and used. +character entities can be defined and used. `A set of character +entity set definition files have been defined`__ (`tarball`__). +There's also `a description and instructions for use`__. + +__ http://docutils.sf.net/tmp/charents/ +__ http://docutils.sf.net/tmp/charents.tgz +__ http://docutils.sf.net/tmp/charents/README.html To allow for `character-level inline markup`_, a limited form of character processing has been added to the spec and parser: escaped -- cgit v1.2.1 From 180fb329f6e70b36a04e3ae54238964eec9adf44 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jul 2003 02:05:37 +0000 Subject: Allowed true em-dash character as block quote attribution marker. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1584 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 1ad25ff35..46bf3dd16 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1112,10 +1112,10 @@ within the block quote:: -- Sherlock Holmes -If the final block of a block quote begins with "--" (flush left -within the block quote), it is interpreted as an attribution. If the -attribution consists of multiple lines, the left edges of the second -and subsequent lines must align. +If the final block of a block quote begins with "--" or a true em-dash +(flush left within the block quote), it is interpreted as an +attribution. If the attribution consists of multiple lines, the left +edges of the second and subsequent lines must align. Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote. -- cgit v1.2.1 From 3c4ec123863c437a6357bf69a374872b70a8f227 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 12 Jul 2003 18:59:02 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1587 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 5fc316a99..021ddb6a0 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -883,7 +883,7 @@ Unicode Character Codes The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric +``0x``, ``x``, ``\x``, ``U+``, ``u``, or ``\u``), or XML-style numeric character entities (e.g. ``ᨫ``). Codes are case-insensitive. Text following " .. " is a comment and is ignored. Spaces are -- cgit v1.2.1 From a3418f12380f5ca855453fa104445fcb52ed396c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 12 Jul 2003 18:59:30 +0000 Subject: allow "---" for block quote attributions too git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1588 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 46bf3dd16..7a83bdbc8 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1112,8 +1112,8 @@ within the block quote:: -- Sherlock Holmes -If the final block of a block quote begins with "--" or a true em-dash -(flush left within the block quote), it is interpreted as an +If the final block of a block quote begins with "--", "---", or a true +em-dash (flush left within the block quote), it is interpreted as an attribution. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align. -- cgit v1.2.1 From 5dfbb36b4a867d48619e9dc37600d5900b51bbf5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 15 Jul 2003 00:45:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1590 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 021ddb6a0..e6890e230 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -756,13 +756,15 @@ Including an External Document Fragment :Directive Type: "include" :Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to include file). +:Directive Arguments: One, required. :Directive Options: Possible. :Directive Content: None. The "include" directive reads a reStructuredText-formatted text file and parses it in the current document's context at the point of the -directive. For example:: +directive. The directive argument is the path to the file to be +included, relative to the document containing the directive. For +example:: This first example will be parsed at the document level, and can thus contain any construct, including section headers. -- cgit v1.2.1 From 1a833ee0870342beeec1ec57400bc9c6100ca445 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 15 Jul 2003 02:06:48 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1591 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index de3a33d14..cf7cf6868 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -349,6 +349,11 @@ General "--generator", "--source-link", and "--date" etc.), allowing translations. +* 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. + Documentation ------------- -- cgit v1.2.1 From 1869c1f9c42fb5e9a97b1c24d0c50bf48156083f Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 15 Jul 2003 16:11:36 +0000 Subject: Fix: no latex tableofcontents was generated if no docinfo item was specified. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1593 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 1b3d0b53b..945af8410 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -48,6 +48,9 @@ Setting/Config Entry Description table of contents must be generated by latex. Usually latex must be run twice to get numbers correct. + + *Note:* LaTeX will number the sections, which + might be a bug in this case. --------------------- ------------------------------------------------ --hyperlink-color Color of any hyperlinks embedded in text (default: "blue", "0" to disable). -- cgit v1.2.1 From 17e70b2f9a8bcba9a85ae6643931b5bebc40e4d3 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 22 Jul 2003 12:06:09 +0000 Subject: Add howto get a list of figures. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1602 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 945af8410..2d38918f5 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -150,6 +150,16 @@ or some commands too fix this, which i currently cannot find. Some people diagnose a similar unbalance for the postscript fonts, the package to fix this is ```\usepackage{pslatex}``. +Table of figures +---------------- + +A table of figures can be generated by a command directly to latex:: + + .. raw:: latex + + \listoffigures + +LaTeX also has a command ``\listoftables``. Commands directly to LaTeX ========================== -- cgit v1.2.1 From a72e63e11fc74ce398fc5461779b3ae3644d111c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 29 Jul 2003 05:14:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1610 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 7baf71714..8e50f017d 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -313,6 +313,17 @@ than of the character-encoding type. .. _character-level inline markup: reStructuredText.html#character-level-inline-markup +* Directive idea:: + + .. text-replace:: "pattern" "replacement" + + - Support Unicode "U+XXXX" codes. + - Support regexps, perhaps with alternative "regexp-replace" + directive. + - Flags for regexps; ":flags:" option, or individuals. + - Specifically, should the default be case-sensistive or + -insensitive? + Field Lists =========== -- cgit v1.2.1 From 10ec30c47351534c0238e2709c812148ddbb6c7c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 29 Jul 2003 05:21:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1611 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index cf7cf6868..66fcb1b07 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -60,6 +60,12 @@ Bugs command-line option wouldn't work because it would require user action. Config file setting? +* Explicit targets are sometimes mis-located. In particular, placing + a target before a section header puts the target at the end of the + previous section instead of the start of the next section. The code + in docutils.transforms.misc.ClassAttribute could be used to fix + this. (Reported by David Priest.) + General ------- @@ -1449,8 +1455,8 @@ elements. * Add document-local _`role bindings`, associating directives with roles? :: - ``She wore ribbons in her hair and it lay with streaks of - grey``:rewrite: + `She wore ribbons in her hair and it lay with streaks of + grey`:rewrite: .. :rewrite: class:: rewrite -- cgit v1.2.1 From 136a6588779fc1a29ed5b9eb3fc0a52f64840c06 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 29 Jul 2003 20:35:43 +0000 Subject: target git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1613 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 66fcb1b07..1ccbf1e21 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1113,7 +1113,7 @@ when used in a document. 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. + 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:: -- cgit v1.2.1 From 9c05cb1a66e3ca53179c55ea6e914ee02e957474 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 4 Aug 2003 18:15:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1620 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 1ccbf1e21..b3277598a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -598,9 +598,9 @@ __ rst/alternatives.html#or-not-to-do 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:: +* 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 @@ -631,9 +631,15 @@ __ rst/alternatives.html#or-not-to-do 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. Also - docutils-users, 2003-02-17. + 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`__. + + __ 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 * Make the parser modular. Allow syntax constructs to be added or disabled at run-time. Or is subclassing enough? -- cgit v1.2.1 From 0504917a3757ffc8ce858152d068669c64be010e Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 16 Aug 2003 19:13:46 +0000 Subject: Add option use-latex-footnotes. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1634 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 2d38918f5..2cf3b5bea 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -52,6 +52,12 @@ Setting/Config Entry Description *Note:* LaTeX will number the sections, which might be a bug in this case. --------------------- ------------------------------------------------ +--use-latex-footnotes Use LaTeX-footnotes not a figure simulation. + This might give no Hyperrefs on /to footnotes, + but should be able to handle more. + + By default this is off. +--------------------- ------------------------------------------------ --hyperlink-color Color of any hyperlinks embedded in text (default: "blue", "0" to disable). --------------------- ------------------------------------------------ -- cgit v1.2.1 From 150390347801881a0179bad8a4930b60856d7029 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 17 Aug 2003 14:14:01 +0000 Subject: link fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1635 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- docs/ref/rst/restructuredtext.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index e6890e230..3eaaa9ef5 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -38,7 +38,7 @@ type definition. .. _Directives: ./reStructuredText.html#directives .. _reStructuredText Markup Specification: ./reStructuredText.html .. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../gpdi.dtd +.. _Docutils Generic DTD: ../docutils.dtd ------------- diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 7a83bdbc8..e0950b3b5 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2642,7 +2642,7 @@ Markup errors are handled according to the specification in `PEP .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _Docutils: http://docutils.sourceforge.net/ .. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../gpdi.dtd +.. _Docutils Generic DTD: ../docutils.dtd .. _transforms: http://docutils.sourceforge.net/docutils/transforms/ .. _Grouch: http://www.mems-exchange.org/software/grouch/ -- cgit v1.2.1 From 17dd4b0571b12951b72c5d19c259d82b82c1f60b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 27 Aug 2003 20:41:48 +0000 Subject: "Docutils Configuration Files", added to project. Moved config file entry descriptions from tools.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1639 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 565 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 565 insertions(+) create mode 100644 docs/user/config.txt (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt new file mode 100644 index 000000000..461273095 --- /dev/null +++ b/docs/user/config.txt @@ -0,0 +1,565 @@ +============================== + Docutils Configuration Files +============================== + +:Author: David Goodger +:Contact: goodger@python.org +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + +.. Cross-reference command-line options with configuration file + settings? Make alphabetical indexes of both. + +Configuration files are used for persistent customization; they can be +set once and take effect every time you use a front-end tool. +Configuration file settings override the built-in defaults, and +command-line options override all. + +By default, Docutils checks the following places for configuration +files, in the following order: + +1. ``/etc/docutils.conf``: This is a system-wide configuration file, + applicable to all Docutils processing on the system. + +2. ``./docutils.conf``: This is a project-specific configuration file, + located in the current directory. The Docutils front end has to be + executed from the directory containing this configuration file for + it to take effect (note that this may have nothing to do with the + location of the source files). Settings in the project-specific + configuration file will override corresponding settings in the + system-wide file. + +3. ``~/.docutils``: This is a user-specific configuration file, + located in the user's home directory. Settings in this file will + override corresponding settings in both the system-wide and + project-specific configuration files. + +If more than one configuration file is found, all will be read but +later entries will override earlier ones. For example, a "stylesheet" +entry in a user-specific configuration file will override a +"stylesheet" entry in the system-wide file. + +In addition, a configuration file may be explicitly specified with the +"--config" command-line option. This configuration file is read after +the three implicit ones listed above, and its entries will have +priority. + + +------------------------------------- +Configuration File Sections & Entries +------------------------------------- + +Configuration files use the standard ConfigParser.py_ Python_ module. +From its documentation: + + The configuration file consists of sections, lead by a "[section]" + header and followed by "name: value" entries, with continuations + in the style of `RFC 822`_; "name=value" is also accepted. Note + that leading whitespace is removed from values. The optional + values can contain format strings which refer to other values in + the same section, or values in a special DEFAULT section. + Additional defaults can be provided upon initialization and + retrieval. Lines beginning with "#" or ";" are ignored and may be + used to provide comments. + +Configuration file entry names correspond to internal runtime +settings. Underscores ("_") and hyphens ("-") can be used +interchangably in entry names; hyphens are automatically converted to +underscores. + +Below are the Docutils runtime settings, listed by config file +section. Any setting may be specified in any section, but only +settings from active sections will be used. Sections correspond to +Docutils components (module name or alias; section names are always in +lowercase letters). Each `Docutils application`_ uses a specific set +of components; corresponding configuration file sections are applied +when the application is used. Configuration sections are applied in +general-to-specific order, as follows: + +1. `[general]`_ + +2. `[parsers]`_, parser dependencies, and the section specific to the + Parser used ("[... parser]"). Currently, only `[restructuredtext + parser]`_ is applicable. + +3. `[readers]`_, reader dependencies, and the section specific to the + Reader used ("[... reader]"). For example, `[pep reader]`_ depends + on `[standalone reader]`_. + +4. `[writers]`_, writer dependencies, and the section specific to the + Writer used ("[... writer]"). For example, `[pep_html writer]`_ + depends on `[html4css1 writer]`_. + +5. `[applications]`_, application dependencies, and the section + specific to the Application (front-end tool) in use + ("[... application]"). + +Since any setting may be specified in any section, this ordering +allows component- or application-specific overrides of earlier +settings. For example, there may be Reader-specific overrides of +general settings; Writer-specific overrides of Parser settings; +Application-specific overrides of Writer settings; and so on. + +If multiple configuration files are applicable, the process is +completed (all sections are applied in the order given) for each one +before going on to the next. For example, a "[pep_html writer] +stylesheet" setting in an earlier configuration file would be +overridden by an "[html4css1 writer] stylesheet" setting in a later +file. + +Some knowledge of Python_ is assumed for some attributes. + +.. _ConfigParser.py: + http://www.python.org/doc/current/lib/module-ConfigParser.html +.. _Python: http://www.python.org/ +.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt +.. _Docutils application: tools.html + + +[general] +========= + +Settings in the "[general]" section are always applied. + +_`datestamp` + Include a time/datestamp in the document footer. Contains a + format string for Python's ``time.strftime``. See the `time + module documentation`__. + + Default: None. Options: ``--date, -d, --time, -t, + --no-datestamp``. + + __ http://www.python.org/doc/current/lib/module-time.html + +_`debug` + Report debug-level system messages. + + Default: don't (None). Options: ``--debug, --no-debug``. + +_`dump_internals` + At the end of processing, write all internal attributes of the + document (``document.__dict__``) to stderr. + + Default: don't (None). Options: ``--dump-internals`` (hidden, for + development use only). + +_`dump_pseudo_xml` + At the end of processing, write the pseudo-XML representation of + the document to stderr. + + Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, + for development use only). + +_`dump_settings` + At the end of processing, write all Docutils settings to stderr. + + Default: don't (None). Options: ``--dump-settings`` (hidden, for + development use only). + +_`dump_transforms` + At the end of processing, write a list of all transforms applied + to the document to stderr. + + Default: don't (None). Options: ``--dump-transforms`` (hidden, + for development use only). + +_`error_encoding` + The text encoding for error output. + + Default: "ascii". Options: ``--error-encoding, -e``. + +_`error_encoding_error_handler` + The encoding error handler for unencodable characters in error + output. Acceptable values are the same as for the "error" + parameter of Python's ``encode`` string method. + + Default: "backslashreplace" for Python 2.3 and later; "replace" + otherwise. Options: ``--error-encoding-error-handler, + --error-encoding, -e``. + +_`exit_level` + A system message level threshold; non-halting system messages at + or above this level will produce a non-zero exit status at normal + exit. Exit status is the maximum system message level plus 10 (11 + for INFO, etc.). + + Default: disabled (5). Options: ``--exit``. + +_`expose_internals` + List of internal attribues to expose as external attributes (with + "internal:" namespace prefix). + + Default: don't (None). Options: ``--expose-internal-attribute`` + (hidden, for development use only). + +_`footnote_backlinks` + Enable or disable backlinks from footnotes and citations to their + references. + + Default: enabled (1). Options: ``--footnote-backlinks, + --no-footnote-backlinks``. + +_`generator` + Include a "Generated by Docutils" credit and link in the document + footer. + + Default: off (None). Options: ``--generator, -g, + --no-generator``. + +_`halt_level` + The threshold at or above which system messages are converted to + exceptions, halting execution immediately. + + Default: severe (4). Options: ``--halt, --strict``. + +_`input_encoding` + The text encoding for input. + + Default: auto-detect (None). Options: ``--input-encoding, -i``. + +_`language_code` + `ISO 639`_ 2-letter language code (3-letter codes used only if no + 2-letter code exists). + + Default: English ("en"). Options: ``--language, -l``. + +_`output_encoding` + The text encoding for output. + + Default: "UTF-8". Options: ``--output-encoding, -o``. + +_`output_encoding_error_handler` + The encoding error handler for unencodable characters in output. + Acceptable values are the same as for the "error" parameter of + Python's ``encode`` string method. + + Default: "strict". Options: ``--output-encoding-error-handler, + --output-encoding, -o``. + +_`report_level` + Verbosity threshold at or above which system messages are + reported. + + Default: warning (2). Options: ``--report, -r, --verbose, -v, + --quiet, -q``. + +_`source_link` + Include a "View document source" link in the document footer. URL + will be relative to the destination. + + Default: don't (None). Options: ``--source-link, -s, + --no-source-link``. + +_`source_url` + An explicit URL for a "View document source" link, used verbatim. + + Default: compute if source_link (None). Options: ``--source-uri, + --no-source-link``. + +_`toc_backlinks` + Enable backlinks from section titles to table of contents entries + ("entry"), to the top of the TOC ("top"), or disable ("none"). + + Default: "entry". Options: ``--toc-entry-backlinks, + --toc-top-backlinks, --no-toc-backlinks``. + +_`traceback` + Enable Python tracebacks when an error occurs. + + Default: disabled (None). Options: ``--traceback, + --no-traceback``. + +_`warning_stream` + Path to a file for the output of system messages (warnings) + [#pwd]_. + + Default: stderr (None). Options: ``--warnings``. + + +[parsers] +--------- + +Docutils currently supports only one parser, for reStructuredText. + + +[restructuredtext parser] +````````````````````````` + +_`pep_references` + Recognize and link to PEP references (like "PEP 258"). + + Default: disabled (None); enabled (1) in PEP Reader. Options: + ``--pep-references``. + +_`rfc_references` + Recognize and link to RFC references (like "RFC 822"). + + Default: disabled (None); enabled (1) in PEP Reader. Options: + ``--rfc-references``. + +_`tab_width` + Number of spaces for hard tab expansion. + + Default: 8. Options: ``--tab-width``. + +_`trim-footnote-reference-space` + Remove spaces before footnote references. + + Default: don't (None). Options: + ``--trim-footnote-reference-space``. + + +[readers] +--------- + + +[standalone reader] +``````````````````` + +_`docinfo_xform` + Enable or disable the bibliographic field list transform + (docutils.transforms.frontmatter.DocInfo). + + Default: enabled (1). Options: ``--no-doc-info``. + +_`doctitle_xform` + Enable or disable the promotion of a lone top-level section title + to document title (and subsequent section title to document + subtitle promotion; docutils.transforms.frontmatter.DocTitle). + + Default: enabled (). Options: ``--no-doc-title``. + + +[pep reader] +```````````` + +The `pep_references`_ and `rfc_references`_ options +(`[restructuredtext parser]`_) are set on by default. + + +[python reader] +``````````````` + +Under construction. + + +[writers] +--------- + +[docutils_xml writer] +````````````````````` + +_`doctype_declaration` + Generate XML with a DOCTYPE declaration. + + Default: do (1). Options: ``--no-doctype``. + +_`indents` + Generate XML with indents and newlines. + + Default: don't (None). Options: ``--indents``. + +_`newlines` + Generate XML with newlines before and after tags. + + Default: don't (None). Options: ``--newlines``. + +.. _xml_declaration [docutils_xml writer]: + +xml_declaration + Generate XML with an XML declaration. Also defined for the + `HTML Writer`__. + + .. Caution:: The XML declaration carries text encoding + information, without which standard tools may be unable to read + the generated XML. + + Default: do (1). Options: ``--no-xml-declaration``. + + __ `xml_declaration [html4css1 writer]`_ + + +[html4css1 writer] +`````````````````` + +_`attribution` + Format for block quote attributions: one of "dash" (em-dash + prefix), "parentheses"/"parens", or "none". + + Default: "dash". Options: ``--attribution``. + +_`compact_lists` + Remove extra vertical whitespace between items of bullet lists and + enumerated lists, when list items are "simple" (i.e., all items + each contain one paragraph and/or one "simple" sublist only). + + Default: enabled (1). Options: ``--compact-lists, + --no-compact-lists``. + +_`embed_stylesheet` + Embed the stylesheet in the output HTML file. The stylesheet file + must be accessible during processing. The stylesheet is embedded + inside a comment, so it must not contain the text "``--``" (two + hyphens). + + Default: link, don't embed (None). Options: ``--embed-stylesheet, + --link-stylesheet``. + +_`footnote_references` + Format for footnote references, one of "superscript" or + "brackets". + + Default: "superscript"; "brackets" in PEP/HTML Writer. Options: + ``--footnote-references``. + +_`stylesheet` + CSS stylesheet URL, used verbatim. Overridden by + "stylesheet_path" URL option (``--stylesheet-path``). + + Default: "default.css". Options: ``--stylesheet``. + +_`stylesheet_path` + Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option + (``--stylesheet``). Path is adjusted relative to the output HTML + file. + + Default: None. Options: ``--stylesheet``. + +.. _xml_declaration [html4css1 writer]: + +xml_declaration + Generate XML with an XML declaration. Also defined for the + `Docutils XML Writer`__. + + .. Caution:: The XML declaration carries text encoding + information, without which standard tools may be unable to read + the generated XML. + + Default: do (1). Options: ``--no-xml-declaration``. + + __ `xml_declaration [docutils_xml writer]`_ + + +[pep_html writer] +................. + +The PEP/HTML Writer derives from the standard HTML Writer, and shares +all settings defined in the `[html4css1 writer]`_ section. The +"[html4css1 writer]" section is processed before "[pep_html writer]". + +_`no_random` + Workaround for platforms which core-dump on "``import random``". + + Default: random enabled (None). Options: ``--no-random`` + (hidden). + +_`pep_home` + Home URL prefix for PEPs. + + Default: current directory ("."). Options: ``--pep-home``. + +_`template` + Path to PEP template file [#pwd]_. + + Default: "pep-html-template" (in current directory). Options: + ``--template``. + +_`python_home` + Python's home URL. + + Default: parent directory (".."). Options: ``--python-home``. + + +[latex2e writer] +```````````````` + +(To be completed.) + + +[pseudoxml writer] +`````````````````` + +No settings are defined for this Writer. + + +[applications] +-------------- + +[buildhtml application] +``````````````````````` + +_`prune` + List of directories not to process. To specify multiple + directories in configuration files, use colon-separated paths; on + the command line, the option may be used more than once. + + Default: none ([]). Options: ``--prune``. + +_`recurse` + Recursively scan subdirectories, or ignore subdirectories. + + Default: recurse (1). Options: ``--recurse, --local``. + +_`silent` + Work silently (no progress messages). Independent of + "report_level". + + Default: show progress (None). Options: ``--silent``. + + +[docfactory application] +```````````````````````` + +(To be completed.) + + +Other Settings +============== + +These settings are only effective as command-line options, positional +arguments, or for internal use; setting them in configuration files +has no effect. + +_`config` + Path to a configuration file to read (if it exists) [#pwd]_. + Settings may override defaults and earlier settings. The config + file is processed immediately. Multiple ``--config`` options may + be specified; each will be processed in turn. + + Filesystem path settings contained within the config file will be + interpreted relative to the config file's location (*not* relative + to the current working directory). + + Default: None. Options: ``--config``. + +_`_directories` + (``buildhtml.py`` front end.) List of paths to source + directories, set from positional arguments. + + Default: current working directory (None). No command-line + options. + +_`_disable_config` + Prevent standard configuration files from being read. For + internal use only. + + Default: config files enabled (None). No command-line options. + +_`_destination` + Path to output destination, set from positional arguments. + + Default: stdout (None). No command-line options. + +_`_source` + Path to input source, set from positional arguments. + + Default: stdin (None). No command-line options. + + +.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html + +.. [#pwd] Path relative to the working directory of the process at + launch. -- cgit v1.2.1 From 51c4332861451d613410d206e52ef33615cee997 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 27 Aug 2003 20:42:04 +0000 Subject: Moved config file entry descriptions to config.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1640 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 473 ++++------------------------------------------------ 1 file changed, 30 insertions(+), 443 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index b9af291f6..ee8277589 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -20,12 +20,14 @@ processing. Rather than a single all-purpose program, Docutils has many small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), a "Parser" (which understands the syntax of the text), and a "Writer" (which knows how -to generate a specific data format). Most front ends have common -options and the same command-line usage pattern:: +to generate a specific data format). + +Most front ends have common options and the same command-line usage +pattern:: toolname [options] [<source> [<destination]] -The exceptions are buildhtml.py_ and pep2html.py_. See html.py_ for +(The exceptions are buildhtml.py_ and pep2html.py_.) See html.py_ for concrete examples. Each tool has a "``--help``" option which lists the `command-line options`_ and arguments it supports. Processing can also be customized with `configuration files`_. @@ -86,10 +88,10 @@ The current directory (and all subdirectories) is chosen by default if no directory is named. Some files may generate system messages (tools/test.txt contains intentional errors); use the ``--quiet`` option to suppress all warnings. The ``--config`` option ensures that -the correct stylesheets, templates, and settings are in place -(``./docutils.conf`` is picked up automatically). Command-line -options may be used to override config file settings or replace them -altogether. +the correct stylesheets, templates, and settings are in place (a +``docutils.conf`` configuration file in the current directory is +picked up automatically). Command-line options may be used to +override config file settings or replace them altogether. html.py @@ -108,8 +110,9 @@ browsers. For example, to process a reStructuredText file In fact, there *is* a "``test.txt``" file in the "``tools``" directory. It contains "at least one example of each reStructuredText -construct", including intentional errors. Use it to put the system -through its paces and compare input to output. +construct", including several intentional errors (to test the error +reporting system). Use it to put the system through its paces and +compare input to output. Now open the "``test.html``" file in your favorite browser to see the results. To get a footer with a link to the source file, date & time @@ -183,9 +186,10 @@ Fredrik Lundh, with support for Docutils added. It reads the beginning of a PEP text file to determine the format (old-style indented or new-style reStructuredText) and processes accordingly. Since it does not use the Docutils front end mechanism (the common -command-line options are not supported), it must be configured using -`configuration files`_. The template and stylesheet requirements of -``pep2html.py`` are the same as those of `pep.py`_ above. +command-line options are not supported), it can only be configured +using `configuration files`_. The template and stylesheet +requirements of ``pep2html.py`` are the same as those of `pep.py`_ +above. Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt files. If no arguments are given, all files of the form @@ -210,14 +214,15 @@ or ``pdflatex`` to get a typeset document. Some limitations and difference apply: -- Gif,jpg or png images are not handled, when processed with - ``latex``, use ``pdflatex`` instead. -- Only Latin-1 is tested up to now. +- GIF, JPG and PNG images are not handled, when processed with + ``latex``; use ``pdflatex`` instead. +- Only the Latin-1 output encoding has been tested up to now (Latin-1 + has been made the default output encoding for LaTeX). - The generated file includes a file ``style.tex``, which allows the inclusion of special packages or changes to settings made in the header. -- Not all constructs are possible (e.g. multirow/multicoumn entries in - tables are not). +- Not all constructs are possible (e.g. row/column spans in tables are + not). docutils-xml.py @@ -239,8 +244,8 @@ publish.py :Parser: reStructuredText :Writer: Pseudo-XML -``publish.py`` is used for debugging the Docutils Reader to Transform -to Writer pipeline. It produces a compact pretty-printed +``publish.py`` is used for debugging the Docutils "Reader to Transform +to Writer" pipeline. It produces a compact pretty-printed "pseudo-XML", where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given. @@ -275,12 +280,13 @@ Command-Line Options Each front-end tool supports command-line options for one-off customization. For persistent customization, use `configuration -files`_. +files`_. Command-line options take priority over configuration file +settings. Use the "--help" option on each of the front ends to list the command-line options it supports. Command-line options and their -corresponding configuration file entry names are listed in -`Configuration File Entries`_ below. +corresponding configuration file entry names are listed in the +`Docutils Configuration Files`_ document. .. _configuration file: @@ -291,428 +297,9 @@ Configuration Files Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool. -By default, Docutils checks the following places for configuration -files, in the following order: - -1. ``/etc/docutils.conf``: This is a system-wide configuration file, - applicable to all Docutils processing on the system. - -2. ``./docutils.conf``: This is a project-specific configuration file, - located in the current directory. The Docutils front end has to be - executed from the directory containing this configuration file for - it to take effect (note that this may have nothing to do with the - location of the source files). Settings in the project-specific - configuration file will override corresponding settings in the - system-wide file. - -3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. Settings in this file will - override corresponding settings in both the system-wide and - project-specific configuration files. - -If more than one configuration file is found, all will be read but -later entries will override earlier ones. For example, a "stylesheet" -entry in a user-specific configuration file will override a -"stylesheet" entry in the system-wide file. - -In addition, a configuration file may be explicitly specified with the -"--config" command-line option. This configuration file is read after -the three implicit ones listed above. - -Configuration files use the standard ConfigParser.py_ Python_ module. -From its documentation: - - The configuration file consists of sections, lead by a "[section]" - header and followed by "name: value" entries, with continuations - in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. The optional - values can contain format strings which refer to other values in - the same section, or values in a special DEFAULT section. - Additional defaults can be provided upon initialization and - retrieval. Lines beginning with "#" or ";" are ignored and may be - used to provide comments. - -Docutils currently only uses an "[options]" section; all other -sections are ignored. - -.. Note:: The configuration file format may change in the future. - -Configuration entry names correspond to internal option attributes. -Underscores ("_") and hyphens ("-") can be used interchangably in -entry names. The correspondence between entry names and command-line -options is listed in `Configuration File Entries`_ below. - -.. _ConfigParser.py: - http://www.python.org/doc/current/lib/module-ConfigParser.html -.. _Python: http://www.python.org/ -.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt - - -Configuration File Entries --------------------------- - -Listed below are the Docutils runtime settings. Most may be specified -in `configuration files`_, where hyphens may be used in place of -underscores. Some knowledge of Python_ is assumed for some -attributes. - -attribution - (HTML Writer.) Format for block quote attributions: one of "dash" - (em-dash prefix), "parentheses"/"parens", or "none". - - Default: "dash". Options: ``--attribution``. - -compact_lists - (HTML Writer.) Remove extra vertical whitespace between items of - bullet lists and enumerated lists, when list items are "simple" - (i.e., all items each contain one paragraph and/or one "simple" - sublist only). - - Default: enabled (1). Options: ``--compact-lists, - --no-compact-lists``. - -config - Path to a configuration file to read (if it exists) - [#pwd]_. Settings may override defaults and earlier settings. - This is only effective as a command-line option; setting it in a - config file has no effect. - - Filesystem path settings contained within the config file will be - interpreted relative to the config file's location (*not* relative - to the current working directory). - - Default: None. Options: ``--config``. - -datestamp - Include a time/datestamp in the document footer. Contains a - format string for Python's ``time.strftime``. See the `time - module documentation`__. - - Default: None. Options: ``--date, -d, --time, -t, - --no-datestamp``. - - __ http://www.python.org/doc/current/lib/module-time.html - -debug - Report debug-level system messages. - - Default: don't (None). Options: ``--debug, --no-debug``. - -docinfo_xform - (Standalone Reader.) Enable or disable the bibliographic field - list transform (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: ``--no-doc-info``. - -doctitle_xform - - (Standalone Reader.) Enable or disable the promotion of a lone - top-level section title to document title (and subsequent section - title to document subtitle promotion; - docutils.transforms.frontmatter.DocTitle). - - Default: enabled (). Options: ``--no-doc-title``. - -doctype_declaration - (XML Writer.) Generate XML with a DOCTYPE declaration. - - Default: do (1). Options: ``--no-doctype``. - -dump_internals - At the end of processing, write all internal attributes of the - document (``document.__dict__``) to stderr. - - Default: don't (None). Options: ``--dump-internals`` (hidden, for - development use only). - -dump_pseudo_xml - At the end of processing, write the pseudo-XML representation of - the document to stderr. - - Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, - for development use only). - -dump_settings - At the end of processing, write all Docutils settings to stderr. - - Default: don't (None). Options: ``--dump-settings`` (hidden, for - development use only). - -dump_transforms - At the end of processing, write a list of all transforms applied - to the document to stderr. - - Default: don't (None). Options: ``--dump-transforms`` (hidden, - for development use only). - -embed_stylesheet - (HTML Writer.) Embed the stylesheet in the output HTML file. The - stylesheet file must be accessible during processing. The - stylesheet is embedded inside a comment, so it must not contain - the text "``--``" (two hyphens). - - Default: link, don't embed (None). Options: ``--embed-stylesheet, - --link-stylesheet``. - -error_encoding - The text encoding for error output. - - Default: "ascii". Options: ``--error-encoding, -e``. - -error_encoding_error_handler - The encoding error handler for unencodable characters in error - output. Acceptable values are the same as for the "error" - parameter of Python's ``encode`` string method. - - Default: "backslashreplace" for Python 2.3 and later; "replace" - otherwise. Options: ``--error-encoding-error-handler, - --error-encoding, -e``. - -exit_level - A system message level threshold; non-halting system messages at - or above this level will produce a non-zero exit status at normal - exit. Exit status is the maximum system message level plus 10 (11 - for INFO, etc.). - - Default: disabled (5). Options: ``--exit``. - -expose_internals - List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). - - Default: don't (None). Options: ``--expose-internal-attribute`` - (hidden, for development use only). - -footnote_backlinks - Enable or disable backlinks from footnotes and citations to their - references. - - Default: enabled (1). Options: ``--footnote-backlinks, - --no-footnote-backlinks``. - -footnote_references - (HTML Writer.) Format for footnote references, one of - "superscript" or "brackets". - - Default: "superscript"; "brackets" in PEP/HTML Writer. Options: - ``--footnote-references``. - -generator - Include a "Generated by Docutils" credit and link in the document - footer. - - Default: off (None). Options: ``--generator, -g, - --no-generator``. - -halt_level - The threshold at or above which system messages are converted to - exceptions, halting execution immediately. - - Default: severe (4). Options: ``--halt, --strict``. - -indents - (XML Writer.) Generate XML with indents and newlines. - - Default: don't (None). Options: ``--indents``. - -input_encoding - The text encoding for input. - - Default: auto-detect (None). Options: ``--input-encoding, -i``. - -language_code - `ISO 639`_ 2-letter language code (3-letter codes used only if no - 2-letter code exists). - - Default: English ("en"). Options: ``--language, -l``. - -newlines - (XML Writer.) Generate XML with newlines before and after tags. - - Default: don't (None). Options: ``--newlines``. - -no_random - (PEP/HTML Writer.) Workaround for platforms which core-dump on - "``import random``". - - Default: random enabled (None). Options: ``--no-random`` - (hidden). - -output_encoding - The text encoding for output. - - Default: "UTF-8". Options: ``--output-encoding, -o``. - -output_encoding_error_handler - The encoding error handler for unencodable characters in output. - Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method. - - Default: "strict". Options: ``--output-encoding-error-handler, - --output-encoding, -o``. - -pep_home - (PEP/HTML Writer.) Home URL prefix for PEPs. - - Default: current directory ("."). Options: ``--pep-home``. - -pep_references - (reStructuredText Parser.) Recognize and link to PEP references - (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--pep-references``. - -pep_stylesheet - (PEP/HTML Writer.) CSS stylesheet URL, used verbatim. Overrides - HTML stylesheet (``--stylesheet``). - - Default: None. Options: ``--pep-stylesheet``. - -pep_stylesheet_path - (PEP/HTML Writer.) Path to CSS stylesheet [#pwd]_. Path is - adjusted relative to the output HTML file. Overrides HTML - stylesheet (``--stylesheet``) and PEP stylesheet - (``--pep-stylesheet``). - - Default: None. Options: ``--pep-stylesheet-path``. - -pep_template - (PEP/HTML Writer.) Path to PEP template file [#pwd]_. - - Default: "pep-html-template" (in current directory). Options: - ``--pep-template``. - -python_home - (PEP/HTML Writer.) Python's home URL. - - Default: parent directory (".."). Options: ``--python-home``. - -recurse - (``buildhtml.py`` front end.) Recursively scan subdirectories. - - Default: recurse (1). Options: ``--recurse, --local``. - -report_level - Verbosity threshold at or above which system messages are - reported. - - Default: warning (2). Options: ``--report, -r, --verbose, -v, - --quiet, -q``. - -rfc_references - (reStructuredText Parser.) Recognize and link to RFC references - (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--rfc-references``. - -silent - (``buildhtml.py`` front end.) Work silently (no progress - messages). Independent of "report_level". - - Default: show progress (None). Options: ``--silent``. - -source_link - Include a "View document source" link in the document footer. URL - will be relative to the destination. - - Default: don't (None). Options: ``--source-link, -s, - --no-source-link``. - -source_url - An explicit URL for a "View document source" link, used verbatim. - - Default: compute if source_link (None). Options: ``--source-uri, - --no-source-link``. - -stylesheet - (HTML Writer.) CSS stylesheet URL, used verbatim. Overridden by - "stylesheet_path" URL option (``--stylesheet-path``). - - Default: "default.css". Options: ``--stylesheet``. - -stylesheet_path - (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides - "stylesheet" URL option (``--stylesheet``). Path is adjusted - relative to the output HTML file. - - Default: None. Options: ``--stylesheet``. - -tab_width - (reStructuredText Parser.) Number of spaces for hard tab - expansion. - - Default: 8. Options: ``--tab-width``. - -toc_backlinks - Enable backlinks from section titles to table of contents entries - ("entry"), to the top of the TOC ("top"), or disable ("none"). - - Default: "entry". Options: ``--toc-entry-backlinks, - --toc-top-backlinks, --no-toc-backlinks``. - -traceback - Enable Python tracebacks when an error occurs. - - Default: disabled (None). Options: ``--traceback, - --no-traceback``. - -trim-footnote-reference-space - (reStructuredText Parser.) Remove spaces before footnote - references. - - Default: don't (None). Options: - ``--trim-footnote-reference-space``. - -warning_stream - Path to a file for the output of system messages (warnings) - [#pwd]_. - - Default: stderr (None). Options: ``--warnings``. - -xml_declaration - (XML and HTML Writers.) Generate XML with an XML declaration. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - -For Internal Use Only -````````````````````` - -Setting these in a config file has no effect. - - -_directories - (``buildhtml.py`` front end.) List of paths to source - directories, set from positional arguments. - - Default: current working directory (None). No command-line - options. - -_disable_config - Prevent standard configuration files from being read. - - Default: config files enabled (None). No command-line options. - -_destination - Path to output destination, set from positional arguments. - - Default: stdout (None). No command-line options. - -_source - Path to input source, set from positional arguments. - - Default: stdin (None). No command-line options. - -.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html +For details, see `Docutils Configuration Files`_. -.. [#pwd] Path relative to the working directory of the process at - launch. +.. _Docutils Configuration Files: config.html .. -- cgit v1.2.1 From f7c8d424d0809f0ca8359a2c6341147fcd05da6c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 27 Aug 2003 20:53:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1646 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b3277598a..f763e6f36 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -324,22 +324,15 @@ General reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output? -* @@@ Re-evaluate the config file format, enabling a section for each - Docutils component so that (for example) HTML's and LaTeX's - stylesheets don't interfere with each other. - - Details: <http://article.gmane.org/gmane.text.docutils.devel/876>. - -* Rationalize Writer settings (HTML/LaTeX/PEP). +* 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. -* Rework docs/tools.txt for the new configuration sections. Merge - doc/latex.txt info into tools.txt. +* Merge doc/latex.txt info into tools.txt and config.txt. -* Add validation/conversion to SettingsSpec objects? Entry in the +* @@@ Add validation/conversion to SettingsSpec objects? Entry in the keyword argument dictionary, to be handled by OptionParser? How to pass it on to ConfigParser? Or keep the exclusive responsibility in OptionParser? Problem with the current "validation" attribute of -- cgit v1.2.1 From de4f0bee3293c2211de29b98508dbbdb562deeac Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 27 Aug 2003 23:42:44 +0000 Subject: added "Web Site" section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1652 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f763e6f36..2e3cc3826 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -2084,6 +2084,30 @@ projects in sync when there are changes made to the core Docutils code. +Web Site +======== + +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 + 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. + +The docutils-update__ script is in CVS as +``sandbox/davidg/infrastructure/docutils-update``. + +__ http://docutils.sf.net/sandbox/davidg/infrastructure/docutils-update + + Release Procedure ================= -- cgit v1.2.1 From 2c7a78d2a7daf68af2915e532ebe2fab3162c50e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 27 Aug 2003 23:47:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1653 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2e3cc3826..cea602cd7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -359,6 +359,10 @@ Documentation * User docs. What's needed? +* Add an "examples" directory, beside "tools" and "docs", for + interesting examples of Docutils usage? Have a top-level README.txt + file and a subdirectory for each example. (Martin Blais) + Implementation Docs ``````````````````` @@ -401,14 +405,6 @@ Specification See Doc-SIG from 2001-06-19/20. -Web Site -```````` - -* Add an "examples" directory, beside "tools" and "docs", for - interesting examples of Docutils usage? Have a top-level README.txt - file and a subdirectory for each example. (Martin Blais) - - Python Source Reader -------------------- -- cgit v1.2.1 From b489cdcc98a2adc156dfa606567679bcb131374d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 29 Aug 2003 14:28:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1654 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index cea602cd7..c943a609c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1463,7 +1463,7 @@ elements. The example above would implement the "rewrite" role as adding a ``class="rewrite"`` attribute to the interpreted text ("inline" element). The stylesheet would then pick up on the "class" - attribute to do the actual formatting. + attribute to do the actual formatting. (Allow other base elements?) The same thing could be done with a directive, albeit a bit more verbosely:: @@ -1500,7 +1500,18 @@ elements. 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? + (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: @@ -1521,12 +1532,13 @@ elements. Then again, a glossary could be formed by gathering individual definitions from around the document. - 2. Some kind of `inline parameter syntax`__? :: + 2. Some kind of `inline parameter syntax`_? :: `reST <reStructuredText>`:acronym: is `WYSIWYG <what you see is what you get>`:acronym: plaintext markup. - __ rst/alternatives.html#parameterized-interpreted-text + .. _inline parameter syntax: + rst/alternatives.html#parameterized-interpreted-text 3. A combination of 1 & 2? -- cgit v1.2.1 From 4771aa9c9dc9dcdc4ba14125e3137f4cb8e5de03 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 29 Aug 2003 15:45:18 +0000 Subject: LaTeX writer no longer has a default stylesheet. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1655 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 2cf3b5bea..fd542dc69 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -69,7 +69,7 @@ Setting/Config Entry Description ``input`` by latex in the document header. If this is set to "" disables generation of input latex command. - (default: "style.tex"). + (default: "no stylesheet"). --------------------- ------------------------------------------------ --footnote-references Format for footnote references: one of "superscript" or "brackets". -- cgit v1.2.1 From 8fdc04fd1a6333420794da6d94cc509e464316f8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 1 Sep 2003 15:13:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1664 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 ++++------------ docs/user/config.txt | 32 ++++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c943a609c..fadbdd288 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -332,18 +332,6 @@ General * Merge doc/latex.txt info into tools.txt and config.txt. -* @@@ Add validation/conversion to SettingsSpec objects? Entry in the - keyword argument dictionary, to be handled by OptionParser? How to - pass it on to ConfigParser? Or keep the exclusive responsibility in - OptionParser? Problem with the current "validation" attribute of - docutils.frontend.ConfigParser is that it separates this information - from the rest of the settings_spec. - - Specifically, boolean values like "xml_declaration" ought to accept - "0" for false (not just '' empty string as now), and "false", "no", - and "off" too. True values should be any of "1", "true", "yes", and - "on". - * Add internationalization to footer boilerplate text (resulting from "--generator", "--source-link", and "--date" etc.), allowing translations. @@ -353,6 +341,10 @@ General Especially useful for character entity sets, text transform specs, boilerplate, etc. +* @@@ Add an easy way for applications to identify themselves for + config file purposes. Perhaps another keyword argument to the + docutils.core.publish_* convenience functions etc. + Documentation ------------- diff --git a/docs/user/config.txt b/docs/user/config.txt index 461273095..f908b1f7e 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -48,9 +48,9 @@ the three implicit ones listed above, and its entries will have priority. -------------------------------------- -Configuration File Sections & Entries -------------------------------------- +------------------------- +Configuration File Syntax +------------------------- Configuration files use the standard ConfigParser.py_ Python_ module. From its documentation: @@ -58,18 +58,28 @@ From its documentation: The configuration file consists of sections, lead by a "[section]" header and followed by "name: value" entries, with continuations in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. The optional - values can contain format strings which refer to other values in - the same section, or values in a special DEFAULT section. - Additional defaults can be provided upon initialization and - retrieval. Lines beginning with "#" or ";" are ignored and may be - used to provide comments. + that leading whitespace is removed from values. ... Lines + beginning with "#" or ";" are ignored and may be used to provide + comments. + +.. Note:: No format string interpolation is done. Configuration file entry names correspond to internal runtime settings. Underscores ("_") and hyphens ("-") can be used interchangably in entry names; hyphens are automatically converted to underscores. +For on/off switch settings (booleans), the following values are +recognized: + +* On: "true", "yes", "on", "1" +* Off: "false", "no", "off", "0", "" (no value) + + +------------------------------------- +Configuration File Sections & Entries +------------------------------------- + Below are the Docutils runtime settings, listed by config file section. Any setting may be specified in any section, but only settings from active sections will be used. Sections correspond to @@ -190,7 +200,9 @@ _`exit_level` _`expose_internals` List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). + "internal:" namespace prefix). To specify multiple attributes in + configuration files, use colons to separate names; on the command + line, the option may be used more than once. Default: don't (None). Options: ``--expose-internal-attribute`` (hidden, for development use only). -- cgit v1.2.1 From f8500a11e45dc44858bdd0e27b04a5e96d8a8fc0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 1 Sep 2003 21:14:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1668 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fadbdd288..528bd514a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -341,10 +341,6 @@ General Especially useful for character entity sets, text transform specs, boilerplate, etc. -* @@@ Add an easy way for applications to identify themselves for - config file purposes. Perhaps another keyword argument to the - docutils.core.publish_* convenience functions etc. - Documentation ------------- @@ -1407,8 +1403,6 @@ 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. -* @@@ Add a test for language mappings of roles. - * Alan Jaffray suggested (and I agree) that it would be sensible to: - have a directive and/or command-line option to specify a default -- cgit v1.2.1 From caa3223df85722cfc92f1cc1c8af38b2eca0f84a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 1 Sep 2003 22:25:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1670 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 528bd514a..2c60e4df3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -611,12 +611,13 @@ __ rst/alternatives.html#or-not-to-do 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`__. + 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? -- cgit v1.2.1 From 88920f7db59954908fa82c9a39538f6c683666f9 Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 11 Sep 2003 09:52:06 +0000 Subject: Added support for ``DOCUTILSCONFIG`` environment variable. Added method `OptionParser.get_config_files()` to allow overriding this behavior in a subclass. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1674 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index f908b1f7e..2648ce0ed 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -36,16 +36,22 @@ files, in the following order: located in the user's home directory. Settings in this file will override corresponding settings in both the system-wide and project-specific configuration files. - + If more than one configuration file is found, all will be read but later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file. +You can override the default 3 pathes by the environment variable +``DOCUTILSCONFIG``, which should a colon-separated +(semicolon-separated on windows) sequence of pathes to search instead +(leave it empty to search no files at all). Tilde-expansion is +performed; relative pathes are relative to current working directory. + In addition, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is read after -the three implicit ones listed above, and its entries will have -priority. +the three implicit ones listed above (or the ones defined by +``DOCUTILSCONFIG``), and its entries will have priority. ------------------------- -- cgit v1.2.1 From 5261c45badb074fa23f7cad47808d96b572b717e Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 11 Sep 2003 14:58:04 +0000 Subject: - Fixed stupid bug that made last change a no-op. - Explicitly made 'DOCUTILSCONFIG' ignore empty path items. - Refactored `test_settings.ConfigFileTests`: - Centralized reading of config files and combining of multiple setting dicts. - Subclassed with a class that runs the very same tests but sets `os.environ['DOCUTILSCONFIG']` instead of reading files directly. - Added test method that reads no files at all, for completeness. - Improved diff display in `compare_output` (order & trailing newlines). - Fixed bug in `test_old_and_new`: it used 'old' expected settings (which are surely the same as 'one') but read the 'one' config file. Assuming it's a cut-and-paste typo, changed to read 'one' file. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1675 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 2648ce0ed..2c6204148 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -42,11 +42,12 @@ later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file. -You can override the default 3 pathes by the environment variable -``DOCUTILSCONFIG``, which should a colon-separated -(semicolon-separated on windows) sequence of pathes to search instead -(leave it empty to search no files at all). Tilde-expansion is -performed; relative pathes are relative to current working directory. +You can replace the default 3 pathes with the environment variable +``DOCUTILSCONFIG``. It should a colon-separated (semicolon-separated +on windows) sequence of files to search instead (leave it empty to +search no files at all). Tilde-expansion is performed; relative +pathes are relative to current working directory; empty-string path +items are ignored. In addition, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is read after -- cgit v1.2.1 From f0fb4ccd4478cbda87f35b69e1328d2658670ed3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 11 Sep 2003 22:42:06 +0000 Subject: revised DOCUTILSCONFIG envar text git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1677 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 2c6204148..45db23ab1 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -36,23 +36,25 @@ files, in the following order: located in the user's home directory. Settings in this file will override corresponding settings in both the system-wide and project-specific configuration files. - + If more than one configuration file is found, all will be read but later entries will override earlier ones. For example, a "stylesheet" entry in a user-specific configuration file will override a "stylesheet" entry in the system-wide file. -You can replace the default 3 pathes with the environment variable -``DOCUTILSCONFIG``. It should a colon-separated (semicolon-separated -on windows) sequence of files to search instead (leave it empty to -search no files at all). Tilde-expansion is performed; relative -pathes are relative to current working directory; empty-string path -items are ignored. +The default implicit config file paths can be overridden by the +``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should +contain a colon-separated (semicolon-separated on Windows) sequence of +config file paths to search for; leave it empty to disable implicit +config files altogether. Tilde-expansion is performed on paths. +Paths are interpreted relative to the current working directory. +Empty path items are ignored. In addition, a configuration file may be explicitly specified with the "--config" command-line option. This configuration file is read after -the three implicit ones listed above (or the ones defined by -``DOCUTILSCONFIG``), and its entries will have priority. +the three implicit ones listed above (or the ones defined by the +``DOCUTILSCONFIG`` environment variable), and its entries will have +priority. ------------------------- -- cgit v1.2.1 From 1dd10faf5fbee665b98600d878f2764dec0ebfcd Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 14 Sep 2003 18:17:27 +0000 Subject: Add documentation how to change maketitle. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1685 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index fd542dc69..4eeca027f 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -205,6 +205,26 @@ reStructuredText do something like this:: \\end{center} +Custom title page +----------------- + +Currently maketitle only shows the title and subtitle, date and author are shown +in the docinfo table. + +To change the titlepage layout, e.g. see fancyhdr, one must redefine the +maketitle command in the stylesheet:: + + \renewcommand{\maketitle}{ + \begin{titlepage} + \begin{center} + \textsf{TITLE \@title} \\ + Date: \today + \end{center} + \end{titlepage} + } + +``\@title`` contains the title. + Problems ======== -- cgit v1.2.1 From 11e3c38e93026663be06890832de6c2b26a22bfe Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 15 Sep 2003 13:16:19 +0000 Subject: Move option documentation into config.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1689 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++- docs/user/latex.txt | 48 ++--------------------------------------------- 2 files changed, 54 insertions(+), 47 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 45db23ab1..4e2ec93d3 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -497,7 +497,58 @@ _`python_home` [latex2e writer] ```````````````` -(To be completed.) +_`use_latex_toc` + To get pagenumbers in the table of contents the table of contents + must be generated by latex. Usually latex must be run twice to get + numbers correct. + + *Note:* LaTeX will number the sections, which might be a bug in + this case. + + Default: off. Options: ``--use-latex-toc``. + +_`use_latex_footnotes` + Use LaTeX-footnotes not a figure simulation. This might give no + Hyperrefs on /to footnotes, but should be able to handle an unlimited + number of footnotes. + + Default: off. Options: ``--use-latex-footnotes``. + +_`hyperlink_color` + Color of any hyperlinks embedded in text. Use "0" to disable coloring + of links. + + Default: "blue", use "0" to disable. Options + +_`documentclass` + Specify latex documentclass, *but* beaware that books have chapters + articles not. + + Default: "article". + +_`documentoptions` + Specify document options. Multiple options can be given, separated by + commas. + + Default is "10pt". + +stylesheet + Specify a stylesheet file. The file will be ``input`` by latex in the + document header. If this is set to "" disables generation of input + latex command. + + Default: "no stylesheet". + +footnote_references + Format for footnote references: one of "superscript" or "brackets". + + Default is "brackets". + +attribution + Format for block quote attributions, the same as for the html-writer: + one of "dash" (em-dash prefix), "parentheses"/"parens" or "none". + + Default: "dash". [pseudoxml writer] diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 4eeca027f..91409ea14 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -38,53 +38,9 @@ latex installation (if such a thing exists), therefore the document contains default settings. To allow *overwriting defaults* the stylesheet is included at last. -Options on the Commandline --------------------------- +Run ``rst2latex.py --help`` to see the command-line options, or have look in +config documentytion. -===================== ================================================ -Setting/Config Entry Description -===================== ================================================ ---use-latex-toc To get pagenumbers in the table of contents the - table of contents must be generated by latex. - Usually latex must be run twice to get numbers - correct. - - *Note:* LaTeX will number the sections, which - might be a bug in this case. ---------------------- ------------------------------------------------ ---use-latex-footnotes Use LaTeX-footnotes not a figure simulation. - This might give no Hyperrefs on /to footnotes, - but should be able to handle more. - - By default this is off. ---------------------- ------------------------------------------------ ---hyperlink-color Color of any hyperlinks embedded in text - (default: "blue", "0" to disable). ---------------------- ------------------------------------------------ ---documentclass Specify latex documentclass, *but* beaware that - books have chapters articles not. - (default: "article"). ---------------------- ------------------------------------------------ ---stylesheet Specify a stylesheet file. The file will be - ``input`` by latex in the document header. - If this is set to "" disables generation of - input latex command. - (default: "no stylesheet"). ---------------------- ------------------------------------------------ ---footnote-references Format for footnote references: one of - "superscript" or "brackets". - Default is "brackets". ---------------------- ------------------------------------------------ ---attribution Format for block quote attributions: one of - "dash" (em-dash prefix), "parentheses"/"parens", - or "none". - - Default: "dash". Options: ``--attribution``. -===================== ================================================ - - -Options in the Stylesheet -------------------------- ===================== ================================================ Setting/Config Entry Description -- cgit v1.2.1 From 04f4937f776a56d8cd8f0b305ddd793af59b99dd Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 17 Sep 2003 14:45:21 +0000 Subject: - Added some documentation about text-containing vs. compound elements. - Improved images in LaTeX writer: - Fixed inline images (used to always break the paragraph). - Implemented ``align`` and ``scale`` options. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1691 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 7f0c6cd6d..5bd635bb9 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -109,6 +109,8 @@ Structural Subelements ---------------------- Structural subelements are child elements of structural elements. +Simple structuctural subelements (title_, subtitle_) contain text +data; the others are compound and do not directly contain text data. Category members: title_, subtitle_, docinfo_, decoration_, transition_ @@ -118,7 +120,10 @@ Bibliographic Elements `````````````````````` The docinfo_ element is an optional child of document_. It groups -bibliographic elements together. +bibliographic elements together. All bibliographic elements except +authors_ and field_ contain text data. authors_ contains further +bibliographic elements (most notably author_). field_ contains +field_name_ and field_body_ body subelements. Category members: address_, author_, authors_, contact_, copyright_, date_, field_, organization_, revision_, status_, version_ -- cgit v1.2.1 From 65d150aa232b7c22427a03b9a224d01853caff8e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 20 Sep 2003 17:40:33 +0000 Subject: updated option argument (option list) spec git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1699 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index e0950b3b5..125bff591 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1002,7 +1002,14 @@ given, supported by notes about truncation if and when applicable. Options may be followed by an argument placeholder, whose role and syntax should be explained in the description text. Either a space or an equals sign may be used as a delimiter between options and option -argument placeholders. +argument placeholders; short options ("-" or "+" prefix only) may omit +the delimiter. Option arguments may take one of two forms: + +- Begin with a letter ([a-zA-Z]) and subsequently consist of letters, + numbers, underscores and hyphens ([a-zA-Z0-9_-]). +- Begin with an open-angle-bracket (<) and end with a + close-angle-bracket (>); any characters except angle brackets are + allowed internally. Multiple option "synonyms" may be listed, sharing a single description. They must be separated by comma-space. -- cgit v1.2.1 From 995ce3620fdbe36596a3bb3d0f307775cff6554a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 21 Sep 2003 03:12:17 +0000 Subject: fixed unintended reference; text tweaks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1701 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 125bff591..705de4a64 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1005,11 +1005,11 @@ an equals sign may be used as a delimiter between options and option argument placeholders; short options ("-" or "+" prefix only) may omit the delimiter. Option arguments may take one of two forms: -- Begin with a letter ([a-zA-Z]) and subsequently consist of letters, - numbers, underscores and hyphens ([a-zA-Z0-9_-]). -- Begin with an open-angle-bracket (<) and end with a - close-angle-bracket (>); any characters except angle brackets are - allowed internally. +- Begins with a letter (``[a-zA-Z]``) and subsequently consists of + letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``). +- Begins with an open-angle-bracket (``<``) and ends with a + close-angle-bracket (``>``); any characters except angle brackets + are allowed internally. Multiple option "synonyms" may be listed, sharing a single description. They must be separated by comma-space. -- cgit v1.2.1 From 20ec49f0e786ce9c9089de64987ebf2a11af9fc5 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Sep 2003 10:48:13 +0000 Subject: Option use-LaTeX-docinfo. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1708 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 91409ea14..620bc9fd2 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -14,16 +14,18 @@ Introduction ============ -Producing latex code from reST input could be done in at least two ways: +Producing LaTeX code from reST input could be done in at least two ways: -a. Transform the internal markup into corresponding latex markup e.g. +a. Transform the internal markup into corresponding LaTeX markup e.g. a section title would be written as ```\section{this section ...}``. -b. Using latex as a typesetting system to produce desired paperwork +b. Using LaTeX as a typesetting system to produce desired paperwork without caring about loosing document structure information. -The former might be preferable, but limits to latexs capabilities, so -in reality it is a mix. - +The former might be preferable, but limits to LaTeXs capabilities, so +in reality it is a mix. The reality is that LaTeX has a titlepage with +title, author and date, by default only title is used. Author and date +are shown in the docutils docinfo table and set to blank for LaTeX. +To get author and date set by LaTeX specify option "use-LaTeX-docinfo". Options ======= @@ -31,14 +33,14 @@ Options Configuration can be done in two ways (again): 1. Options to the docutils tool: e.g. language selection. -2. Options to latex via the stylesheet file. +2. Options to LaTeX via the stylesheet file. -The generated latex documents should be kept processable by a standard -latex installation (if such a thing exists), therefore the document +The generated LaTeX documents should be kept processable by a standard +LaTeX installation (if such a thing exists), therefore the document contains default settings. To allow *overwriting defaults* the stylesheet is included at last. -Run ``rst2latex.py --help`` to see the command-line options, or have look in +Run ``rst2LaTeX.py --help`` to see the command-line options, or have look in config documentytion. @@ -60,7 +62,7 @@ papersize Default: a4paper. Paper geometry can be changed \geometry{a5paper,landscape} --------------------- ------------------------------------------------ -paragraph indent By default latex indents the forst line in a +paragraph indent By default LaTeX indents the forst line in a paragraph. The following lines set indentation to zero but add a vertical space between paragraphs.:: @@ -95,13 +97,13 @@ font selection see below Missing options --------------- -* Selection of latex fontsize. +* Selection of LaTeX fontsize. * Assumed reST linelength for table width setting. Font selection -------------- -When generating pdf-files from LaTeX, use the pdflatex command, the files +When generating pdf-files from LaTeX, use the pdfLaTeX command, the files are a lot smaller if postscript fonts are used. To do so put ``\usepackage{times}`` into the styleshee @@ -110,14 +112,14 @@ LaTeX font package, is too heavy compared to the others. There is a package or some commands too fix this, which i currently cannot find. Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ```\usepackage{pslatex}``. +package to fix this is ```\usepackage{psLaTeX}``. Table of figures ---------------- -A table of figures can be generated by a command directly to latex:: +A table of figures can be generated by a command directly to LaTeX:: - .. raw:: latex + .. raw:: LaTeX \listoffigures @@ -129,14 +131,14 @@ Commands directly to LaTeX By means of the reST-raw directive one can give commands directly to LaTeX, e.g. forcing a page break:: - .. raw:: latex + .. raw:: LaTeX \newpage Or setting formulas in LaTeX:: - .. raw:: latex + .. raw:: LaTeX $$x^3 + 3x^2a + 3xa^2 + a^3,$$ @@ -149,13 +151,13 @@ reStructuredText do something like this:: Nobody expects the spanish inquisition. |endcolorbox| - .. |begincolorbox| raw:: latex + .. |begincolorbox| raw:: LaTeX \\begin{center} \\colorbox{bg}{ \\parbox{0.985\\linewidth}{ - .. |endcolorbox| raw:: latex + .. |endcolorbox| raw:: LaTeX }} \\end{center} @@ -220,14 +222,14 @@ Tables Miscellaneous ------------- -* recongize LaTeX (or even latex) and replace by ```\LaTeX``. +* recongize LaTeX (or even LaTeX) and replace by ```\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. * Sidebar handling. * Maybe add end of line after term in definition list. see http://roundup.sf.net/doc-0.5/features.pdf * Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH). -* center subsection{Abstract} gives a latex error here. +* center subsection{Abstract} gives a LaTeX error here. ``! LaTeX Error: Something's wrong--perhaps a missing \item.`` Committed a HACK: centering by hfill. * Document errors are also too silent. -- cgit v1.2.1 From 8e9a5d0f3a761aea8764d5bfb0f1047b0a10ca90 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 5 Oct 2003 16:40:27 +0000 Subject: How to not print LaTeX's section numbers. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1713 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 620bc9fd2..6ad4f67c4 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -125,6 +125,21 @@ A table of figures can be generated by a command directly to LaTeX:: LaTeX also has a command ``\listoftables``. +Section numbering +----------------- + +If section numbering and LaTeX table of contents is used LaTeX and +docutils will number sections. To switch off displaying of LaTeX's +numbers one has to add following lines to the stylesheet :: + + % no section number display + \makeatletter + \def\@seccntformat#1{} + \makeatother + % no numbers in toc + \renewcommand{\numberline}[1]{} + + Commands directly to LaTeX ========================== -- cgit v1.2.1 From 3d83e266cd60737fdaed517259b67eed77411ad2 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 18 Oct 2003 21:42:39 +0000 Subject: Fix: having too wide tables in sidebars. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1720 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 6ad4f67c4..c348f85b6 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -272,4 +272,16 @@ Miscellaneous * For additional docinfo items: the field_body is inserted as text, i.e. no markup is done. * Multiple author entries in docinfo (same thing as in html). +* pslatex has not textbackslash ind bold ? +* make use (but test against pslatex) :: + + \textbackslash \backslash \ + \textbar \mid | + \textless < < + \textgreater > > + \textasciicircum \hat ^ + \textasciitilde \tilde ~ + \textbullet \bullet gefüllter Kreis auf halber Höhe + \textperiodcentered \cdot · + \textvisiblespace (n.v.) sichtbares Leerzeichen -- cgit v1.2.1 From 6219365dc5686d1bdd18762eaeec07a3126c5323 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 29 Oct 2003 08:51:13 +0000 Subject: Fix a typo in LaTeX.txt. Fix vertical bar: by using textbar Change <> by using textless/greater. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1729 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index c348f85b6..d3b097966 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -237,7 +237,7 @@ Tables Miscellaneous ------------- -* recongize LaTeX (or even LaTeX) and replace by ```\LaTeX``. +* recongize LaTeX (or even LaTeX) and replace by ``\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. * Sidebar handling. -- cgit v1.2.1 From 95de065e062f216f4e5499da692ac28cae4c9cce Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 11 Nov 2003 17:01:24 +0000 Subject: added datestamp examples git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1735 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 4e2ec93d3..b3eaa7245 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -151,6 +151,19 @@ _`datestamp` Default: None. Options: ``--date, -d, --time, -t, --no-datestamp``. + Configuration file entry examples:: + + # Equivalent to --date command-line option, results in + # ISO 8601 extended format datestamp, e.g. "2001-12-21": + datestamp: %Y-%m-%d + + # Equivalent to --time command-line option, results in + # date/timestamp like "2001-12-21 18:43 UTC": + datestamp: %Y-%m-%d %H:%M UTC + + # Disables datestamp; equivalent to --no-datestamp: + datestamp: + __ http://www.python.org/doc/current/lib/module-time.html _`debug` @@ -502,18 +515,18 @@ _`use_latex_toc` must be generated by latex. Usually latex must be run twice to get numbers correct. - *Note:* LaTeX will number the sections, which might be a bug in + *Note:* LaTeX will number the sections, which might be a bug in this case. Default: off. Options: ``--use-latex-toc``. _`use_latex_footnotes` - Use LaTeX-footnotes not a figure simulation. This might give no + Use LaTeX-footnotes not a figure simulation. This might give no Hyperrefs on /to footnotes, but should be able to handle an unlimited number of footnotes. Default: off. Options: ``--use-latex-footnotes``. - + _`hyperlink_color` Color of any hyperlinks embedded in text. Use "0" to disable coloring of links. @@ -522,33 +535,33 @@ _`hyperlink_color` _`documentclass` Specify latex documentclass, *but* beaware that books have chapters - articles not. + articles not. Default: "article". _`documentoptions` - Specify document options. Multiple options can be given, separated by - commas. + Specify document options. Multiple options can be given, separated by + commas. Default is "10pt". stylesheet Specify a stylesheet file. The file will be ``input`` by latex in the - document header. If this is set to "" disables generation of input + document header. If this is set to "" disables generation of input latex command. Default: "no stylesheet". footnote_references - Format for footnote references: one of "superscript" or "brackets". + Format for footnote references: one of "superscript" or "brackets". Default is "brackets". attribution - Format for block quote attributions, the same as for the html-writer: + Format for block quote attributions, the same as for the html-writer: one of "dash" (em-dash prefix), "parentheses"/"parens" or "none". - Default: "dash". + Default: "dash". [pseudoxml writer] -- cgit v1.2.1 From 5b08bc218ca9841bd2ccaa908485bf952cdc9f14 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 14 Nov 2003 14:46:12 +0000 Subject: capitalization git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1737 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index d3b097966..de2b2eac4 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -1,5 +1,5 @@ ======================= - Docutils LaTex Writer + Docutils LaTeX Writer ======================= :Author: Engelbert Gruber @@ -40,7 +40,7 @@ LaTeX installation (if such a thing exists), therefore the document contains default settings. To allow *overwriting defaults* the stylesheet is included at last. -Run ``rst2LaTeX.py --help`` to see the command-line options, or have look in +Run ``rst2latex.py --help`` to see the command-line options, or have look in config documentytion. @@ -103,7 +103,7 @@ Missing options Font selection -------------- -When generating pdf-files from LaTeX, use the pdfLaTeX command, the files +When generating pdf-files from LaTeX, use the pdflatex command, the files are a lot smaller if postscript fonts are used. To do so put ``\usepackage{times}`` into the styleshee @@ -112,7 +112,7 @@ LaTeX font package, is too heavy compared to the others. There is a package or some commands too fix this, which i currently cannot find. Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ```\usepackage{psLaTeX}``. +package to fix this is ```\usepackage{pslatex}``. Table of figures ---------------- -- cgit v1.2.1 From 48d5ae4d6486afae950c39ad157eed4d9666b79c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 14 Nov 2003 14:52:26 +0000 Subject: added section for old-format config files; cross-references git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1738 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 78 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index b3eaa7245..b50456e4b 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -419,12 +419,17 @@ xml_declaration [html4css1 writer] `````````````````` -_`attribution` +.. _attribution [html4css1 writer]: + +attribution Format for block quote attributions: one of "dash" (em-dash - prefix), "parentheses"/"parens", or "none". + prefix), "parentheses"/"parens", or "none". Also defined for the + `LaTeX Writer`__. Default: "dash". Options: ``--attribution``. + __ `attribution [latex2e writer]`_ + _`compact_lists` Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all items @@ -442,19 +447,28 @@ _`embed_stylesheet` Default: link, don't embed (None). Options: ``--embed-stylesheet, --link-stylesheet``. -_`footnote_references` +.. _footnote_references [html4css1 writer]: + +footnote_references Format for footnote references, one of "superscript" or - "brackets". + "brackets". Also defined for the `LaTeX Writer`__. Default: "superscript"; "brackets" in PEP/HTML Writer. Options: ``--footnote-references``. -_`stylesheet` + __ `footnote_references [latex2e writer]`_ + +.. _stylesheet [html4css1 writer]: + +stylesheet CSS stylesheet URL, used verbatim. Overridden by - "stylesheet_path" URL option (``--stylesheet-path``). + "stylesheet_path" URL option (``--stylesheet-path``). Also + defined for the `LaTeX Writer`__. Default: "default.css". Options: ``--stylesheet``. + __ `stylesheet [latex2e writer]`_ + _`stylesheet_path` Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option (``--stylesheet``). Path is adjusted relative to the output HTML @@ -545,24 +559,39 @@ _`documentoptions` Default is "10pt". +.. _stylesheet [latex2e writer]: + stylesheet - Specify a stylesheet file. The file will be ``input`` by latex in the - document header. If this is set to "" disables generation of input - latex command. + Specify a stylesheet file. The file will be ``input`` by latex in + the document header. If this is set to "" disables generation of + input latex command. Also defined for the `HTML Writer`__. - Default: "no stylesheet". + Default: no stylesheet (""). + + __ `stylesheet [html4css1 writer]`_ + +.. _footnote_references [latex2e writer]: footnote_references - Format for footnote references: one of "superscript" or "brackets". + Format for footnote references: one of "superscript" or + "brackets". Also defined for the `HTML Writer`__. Default is "brackets". + __ `footnote_references [html4css1 writer]`_ + +.. _attribution [latex2e writer]: + attribution - Format for block quote attributions, the same as for the html-writer: - one of "dash" (em-dash prefix), "parentheses"/"parens" or "none". + Format for block quote attributions, the same as for the + html-writer: one of "dash" (em-dash prefix), + "parentheses"/"parens" or "none". Also defined for the `HTML + Writer`__. Default: "dash". + __ `attribution [html4css1 writer]`_ + [pseudoxml writer] `````````````````` @@ -648,3 +677,26 @@ _`_source` .. [#pwd] Path relative to the working directory of the process at launch. + + +------------------------------ +Old-Format Configuration Files +------------------------------ + +Formerly, Docutils configuration files contained a single "[options]" +section only. This was found to be inflexible, and in August 2003 +Docutils adopted the current component-based configuration file +sections as described above. Docutils will still recognize the old +"[options]" section, but complains with a deprecation warning. + +To convert existing config files, the easiest way is to change the +section title: change "[options]" to "[general]". Most settings +haven't changed. The only ones to watch out for are these: + +===================== ===================================== +Old-Format Setting New Section & Setting +===================== ===================================== +pep_stylesheet [pep_html writer] stylesheet +pep_stylesheet_path [pep_html writer] stylesheet_path +pep_template [pep_html writer] template +===================== ===================================== -- cgit v1.2.1 From bbc6433ec9b8b1ccf9d02180e8d54cba6a74c055 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 25 Nov 2003 14:49:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1746 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2c60e4df3..6caef7c52 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -181,10 +181,10 @@ General .. _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). +* 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). -- cgit v1.2.1 From c722d702ef10e454fbd837aa3b8c1e47eff8a7ff Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 5 Dec 2003 17:57:05 +0000 Subject: added hint git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1760 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index a34c4a5ed..d028405c6 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -124,6 +124,20 @@ Implements strong emphasis. These are equivalent:: Implements subscripts. +.. Tip:: + + Whitespace or punctuation is required around interpreted text, but + often not desired with subscripts & superscripts. + Backslash-escaped whitespace can be used; the whitespace will be + removed from the processed document:: + + H\ :sub:`2`O + E = mc\ :sup:`2` + + See `the reStructuredText spec`__ for further information. + + __ ./reStructuredText.html#character-level-inline-markup + ``:superscript:`` ================= @@ -131,7 +145,7 @@ Implements subscripts. :Aliases: ``:sup:`` :DTD Element: superscript -Implements superscripts. +Implements superscripts. See the tip in `:subscript:`_ above. ``:title-reference:`` -- cgit v1.2.1 From 94021c3e27455b3d8961caf45ae0159e4e41d92c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 5 Dec 2003 19:14:14 +0000 Subject: fixed hint git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1761 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d028405c6..d3c6ba260 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -131,7 +131,7 @@ Implements subscripts. Backslash-escaped whitespace can be used; the whitespace will be removed from the processed document:: - H\ :sub:`2`O + H\ :sub:`2`\ O E = mc\ :sup:`2` See `the reStructuredText spec`__ for further information. -- cgit v1.2.1 From 52e134d8526146e6b736b0daa9f72e23467556c8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Dec 2003 16:30:09 +0000 Subject: updated from Ueli Schlaepfer's suggestion git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1763 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d3c6ba260..82c5646e8 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -136,7 +136,19 @@ Implements subscripts. See `the reStructuredText spec`__ for further information. + In such cases, readability of the plain text can be greatly + improved with substitutions:: + + The chemical formula for pure water is |H20|. + + .. |H20| replace:: H\ :sub:`2`\ O + + See `the reStructuredText spec`__ for further information on + `character-level markup`__ and `the substitution mechanism`__. + + __ ./reStructuredText.html __ ./reStructuredText.html#character-level-inline-markup + __ ./reStructuredText.html#substitution-references ``:superscript:`` -- cgit v1.2.1 From 6d0e5cffcf3342e394b3820fb572d1811d5a75f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 6 Dec 2003 18:32:35 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1764 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 82c5646e8..fb5ddeb89 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -134,14 +134,12 @@ Implements subscripts. H\ :sub:`2`\ O E = mc\ :sup:`2` - See `the reStructuredText spec`__ for further information. - In such cases, readability of the plain text can be greatly improved with substitutions:: - The chemical formula for pure water is |H20|. + The chemical formula for pure water is |H2O|. - .. |H20| replace:: H\ :sub:`2`\ O + .. |H2O| replace:: H\ :sub:`2`\ O See `the reStructuredText spec`__ for further information on `character-level markup`__ and `the substitution mechanism`__. -- cgit v1.2.1 From 86ed64f45c43e3493269ad582e28899c4b0d2a1c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 15 Dec 2003 14:51:56 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1768 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index b50456e4b..df4f07765 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -290,7 +290,7 @@ _`source_link` _`source_url` An explicit URL for a "View document source" link, used verbatim. - Default: compute if source_link (None). Options: ``--source-uri, + Default: compute if source_link (None). Options: ``--source-url, --no-source-link``. _`toc_backlinks` -- cgit v1.2.1 From c5e249ae47c1c7b96367b911b7aa7817ba85c797 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 19 Dec 2003 14:30:13 +0000 Subject: Added inline markup parsing to field lists' field names git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1771 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 19 +++++++++---------- docs/ref/docutils.dtd | 2 +- docs/ref/rst/restructuredtext.txt | 15 ++++++++------- 3 files changed, 18 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 5bd635bb9..f4b96608d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2181,22 +2181,21 @@ Pseudo-XML_ fragment from simple parsing:: ``field_name`` ============== -The ``field_name`` element contains text data only. It is analogous -to a database field's name. +The ``field_name`` element contains text; it is analogous to a +database field's name. Details ------- :Category: - `Body Subelements`_ + `Body Subelements`_ (simple) :Parents: Only the field_ element contains ``field_name``. :Children: - ``field_name`` elements have no children. They may contain text - data only. + ``field_name`` elements may contain text data plus `inline elements`_. :Analogues: ``field_name`` has no direct analogues in common DTDs. @@ -2210,7 +2209,7 @@ Content Model .. parsed-literal:: - (#PCDATA) + `%text.model;`_ :Attributes: The ``field_name`` element contains only the `common attributes`_: @@ -4829,10 +4828,10 @@ Entity definition: The ``%text.model;`` parameter entity is directly employed in the content models of the following elements: abbreviation_, acronym_, address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, generated_, line_block_, literal_block_, -organization_, paragraph_, problematic_, raw_, reference_, revision_, -status_, strong_, substitution_definition_, substitution_reference_, -subtitle_, target_, term_, title_, version_ +doctest_block_, emphasis_, field_name_, generated_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 06fe4bf55..dc58a9739 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -322,7 +322,7 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT field (field_name, field_body)> <!ATTLIST field %basic.atts;> -<!ELEMENT field_name (#PCDATA)> +<!ELEMENT field_name %text.model;> <!ATTLIST field_name %basic.atts;> <!-- May be empty. --> diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 705de4a64..ff732af1b 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -802,13 +802,14 @@ directives in `reStructuredText Directives`_. Field lists are mappings from field names to field bodies, modeled on RFC822_ headers. A field name is made up of one or more letters, -numbers, whitespace, and punctuation, except colons (":"). Field -names are case-insensitive. The field name, along with a single colon -prefix and suffix, together form the field marker. The field marker -is followed by whitespace and the field body. The field body may -contain multiple body elements, indented relative to the field marker. -The first line after the field name marker determines the indentation -of the field body. For example:: +numbers, whitespace, and punctuation, except colons (":"). Inline +markup is parsed in field names. Field names are case-insensitive +when further processed or transformed. The field name, along with a +single colon prefix and suffix, together form the field marker. The +field marker is followed by whitespace and the field body. The field +body may contain multiple body elements, indented relative to the +field marker. The first line after the field name marker determines +the indentation of the field body. For example:: :Date: 2001-08-16 :Version: 1 -- cgit v1.2.1 From f74494c19b8a9de8a1bb4d6c2acce694b24d802b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 20 Dec 2003 18:48:23 +0000 Subject: Added support for quoted (and unindented) literal blocks. Driven in part by a bribe from Frank Siebenlist (thanks!). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1773 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 84 --------------------------------------- docs/ref/rst/restructuredtext.txt | 77 +++++++++++++++++++++++++++++------ docs/user/rst/quickref.html | 26 ++++++++---- 3 files changed, 82 insertions(+), 105 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6caef7c52..3784fa46c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -651,90 +651,6 @@ __ rst/alternatives.html#or-not-to-do Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback"). -* Generalize the "literal block" construct to allow blocks with a - per-line quoting to avoid indentation? For example, in this email - reply quoting the original, the block quoted with "``>``" (and - prefaced by "``::``") would be treated as a literal block:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - - The literal block would have to be a continuous text block (the - first blank line ends it) where every line begins with the same - non-alphanumeric non-whitespace character. - - On 2003-06-17 Peter Simons requested a similar feature in the - "Literal Haskell Support" thread on docutils-develop. Regarding - this to-do item, he wrote - - I think that the '::' solution is not optimal. IMHO the leading - '>' should be enough for "docutils-hs2whatever" to know this is - a code block. In a perfect world, additional mark-up should not - be required. - - My reply was - - Who said it's a perfect world? ;-) - - The "::" reduces ambiguity, especially in the case of - single-line quoted blocks with certain quote characters. - - Do we limit the characters that can be used for quoting? If so, - what characters? Or would all non-alphanumeric non-whitespace 7-bit - ASCII characters be OK? This would include all of these:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - There are many situations where some kind of left border is used for - quoting. I've often seen vertical bars used:: - - | Quoted text - | here. - - I've seen legal documents that have something like this:: - - ) Quoted text - ) here. - - Or was it the other way around? :: - - ( Quoted text - ( here. - - A problem: if whitespace wasn't required, this could occur - accidentally in ordinary text:: - - (Quoted text here?) - - I think we'd have to require whitespace (perhaps allowing for - multiple quote characters before the whitespace, which would allow - for email). - - What about asterisks? :: - - * Quoted text - * here. - - Big problem! That's a bullet list. So we can't allow "*", "-", or - "+", unless we disambiguate with "::". - - Other conceivable quote characters include: # $ % : ; = [ ] { } - - If we required multiple lines, it would be easier to be sure the - text is unambiguous. I don't think we can require that though. - - Another issue: do the quoting characters stay in the literal block - (i.e., do they show up in the processed document)? - - Relax the "::" requirement somehow? Runtime setting & directive to - specify literal line prefix? Extend to doctest-like blocks (marker - on the first line sufficient)? - * Should the "doctest" element go away, and the construct simply be a front-end to generic literal blocks? diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index ff732af1b..b63979f70 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -124,8 +124,9 @@ Here are examples of `body elements`_: - `Literal blocks`_:: - Literal blocks are indented, and indicated with a double-colon - ("::") at the end of the preceding paragraph (right here -->):: + Literal blocks are either indented or line-prefix-quoted blocks, + and indicated with a double-colon ("::") at the end of the + preceding paragraph (right here -->):: if literal_block: text = 'is left as-is' @@ -1036,12 +1037,13 @@ Literal Blocks Doctree element: literal_block. -A paragraph consisting of two colons ("::") signifies that all -following **indented** text blocks comprise a literal block. No -markup processing is done within a literal block. It is left as-is, -and is typically rendered in a monospaced typeface:: +A paragraph consisting of two colons ("::") signifies that the +following text block(s) comprise a literal block. The literal block +must either be indented or quoted (see below). No markup processing +is done within a literal block. It is left as-is, and is typically +rendered in a monospaced typeface:: - This is a typical paragraph. A literal block follows. + This is a typical paragraph. An indented literal block follows. :: @@ -1087,11 +1089,21 @@ colons after "Paragraph"): Literal block -The minimum leading whitespace will be removed from each line of the -literal block. Other than that, all whitespace (including line -breaks) is preserved. Blank lines are required before and after a -literal block, but these blank lines are not included as part of the -literal block. +All whitespace (including line breaks, but excluding minimum +indentation for indented literal blocks) is preserved. Blank lines +are required before and after a literal block, but these blank lines +are not included as part of the literal block. + + +Indented Literal Blocks +``````````````````````` + +Indented literal blocks are indicated by indentation relative to the +surrounding text (leading whitespace on each line). The minimum +indentation will be removed from each line of an indented literal +block. The literal block need not be contiguous; blank lines are +allowed between sections of indented text. The literal block ends +with the end of the indentation. Syntax diagram:: @@ -1100,10 +1112,49 @@ Syntax diagram:: | (ends with "::") | +------------------------------+ +---------------------------+ - | literal block | + | indented literal block | +---------------------------+ +Quoted Literal Blocks +````````````````````` + +Quoted literal blocks are unindented contiguous blocks of text where +each line begins with the same non-alphanumeric printable 7-bit ASCII +character [#]_. A blank line ends a quoted literal block. The +quoting characters are preserved in the processed document. + +.. [#] + The following are all valid quoting characters:: + + ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ + + Note that these are the same characters as are valid for title + adornment of sections_. + +Possible uses include literate programming in Haskell and email +quoting:: + + John Doe wrote:: + + >> Great idea! + > + > Why didn't I think of that? + + You just did! ;-) + +Syntax diagram:: + + +------------------------------+ + | paragraph | + | (ends with "::") | + +------------------------------+ + +------------------------------+ + | ">" per-line-quoted | + | ">" contiguous literal block | + +------------------------------+ + + Block Quotes ------------ diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index b60cbf1b0..f89d89352 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -18,7 +18,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-06-10</em> + <br align="right"><em>Updated 2003-12-20</em> <blockquote> <p>Copyright: This document has been placed in the public domain. @@ -538,7 +538,7 @@ <td> <samp>A paragraph containing only two colons</samp> <br><samp>indicates that the following indented</samp> -<br><samp>text is a literal block.</samp> +<br><samp>or quoted text is a literal block.</samp> <br> <br><samp>::</samp> <br> @@ -559,17 +559,22 @@ <br> <br><samp>Literal blocks end when text returns to</samp> <br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like::</samp> +<br><samp>This means that something like this</samp> +<br><samp>is possible::</samp> <br> <br><samp>      We start here</samp> <br><samp>    and continue here</samp> <br><samp>  and end here.</samp> <br> -<br><samp>is possible.</samp> +<br><samp>Per-line quoting can also be used on</samp> +<br><samp>unindented literal blocks:</samp> +<br> +<br><samp>> Useful for quotes from email and</samp> +<br><samp>> for Haskell literate programming.<samp> <td> <p>A paragraph containing only two colons -indicates that the following indented +indicates that the following indented or quoted text is a literal block. <pre> @@ -591,14 +596,19 @@ colon if preceded by text, like this: <p>Literal blocks end when text returns to the preceding paragraph's indentation. -This means that something like: +This means that something like this is possible: <pre> We start here and continue here and end here.</pre> - <p>is possible. + <p>Per-line quoting can also be used on +unindented literal blocks: + + <pre> + > Useful for quotes from email and + > for Haskell literate programming.</pre> </table> <h2><a href="#contents" name="block-quotes" class="backref" @@ -1236,7 +1246,7 @@ dispose of medical waste.</samp> <a href="http://www.tibsnjoan.co.uk/">Tibs</a> (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) and David Goodger - (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) + (<a href="mailto:goodger@python.org">goodger@python.org</a>) </address> <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> </body> -- cgit v1.2.1 From 1a9d3d2ed89b62a7ed5126355e3f11b70ed1e5c1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:05:18 +0000 Subject: Upon reviewing RFC 2396, I see that asterisks are valid URL characters, sometimes actually used. There's a conflict with emphasis, but backslash escapes should overcome that (they didn't). This fixes a bug in the parser that escaped asterisks in URLs weren't recognized. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1778 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b63979f70..7a6c7bfda 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2682,6 +2682,9 @@ Two forms of URI are recognized: someone@somewhere.com Punctuation at the end of a URI is not considered part of the URI. +Backslashes may be used in URIs to escape markup characters, +specifically asterisks ("*") and underscores ("_") which are vaid URI +characters (see `Escaping Mechanism`_ above). .. [#URI] Uniform Resource Identifier. URIs are a general form of URLs (Uniform Resource Locators). For the syntax of URIs see -- cgit v1.2.1 From 37babfef0811bc5cfeaa92d5ec04d8c68904aafe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:18:55 +0000 Subject: updated URI schemes mapping & links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1779 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 7a6c7bfda..c8a2047a3 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2651,8 +2651,8 @@ Two forms of URI are recognized: The scheme is the name of the protocol, such as "http", "ftp", "mailto", or "telnet". The scheme consists of an initial letter, followed by letters, numbers, and/or "+", "-", ".". Recognition is - limited to known schemes, per the W3C's `Index of WWW Addressing - Schemes`_. + limited to known schemes, per the `Official IANA Registry of URI + Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_. The scheme-specific part of the resource identifier may be either hierarchical or opaque: @@ -2719,7 +2719,9 @@ Markup errors are handled according to the specification in `PEP .. _doctest module: http://www.python.org/doc/current/lib/module-doctest.html .. _Emacs table mode: http://table.sourceforge.net/ -.. _Index of WWW Addressing Schemes: +.. _Official IANA Registry of URI Schemes: + http://www.iana.org/assignments/uri-schemes +.. _Retired Index of WWW Addressing Schemes: http://www.w3.org/Addressing/schemes.html .. _World Wide Web Consortium: http://www.w3.org/ .. _HTML Techniques for Web Content Accessibility Guidelines: -- cgit v1.2.1 From 4e174f882eb88ad4fd1e41e785a5c21e347e0c53 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 24 Dec 2003 15:51:38 +0000 Subject: Made embedded-URIs' reference text omittable. Idea from Beni Cherniavsky. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1781 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 20 ++------------------ docs/ref/rst/restructuredtext.txt | 8 ++++++++ 2 files changed, 10 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3784fa46c..11708953a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -820,24 +820,8 @@ __ rst/alternatives.html#or-not-to-do parse nested inline markup somehow? See the `collected notes <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. -* Idea from Beni Cherniavsky:: - - I'm writing a README document linking to all other interesting - files in its directory. If these were full URLs I could just - write them in the text but these are relative links that can't - be auto-recognized. The shortest way to make such links that I - found was `file_name <file_name>`_. Perhaps a shortcut for such - usage could be added, e.g. `<file_name>`_ would take the target - as the link name? - - IOW these would be equivalent:: - - `<file_name>`_ - `file_name <file_name>`_ - - Another possibility is to drop the backticks. Should the angle - brackets be kept in the output or not? This syntax could be adopted - in addition to the one above:: +* Drop the backticks from embedded URIs? Should the angle brackets be + kept in the output or not? :: <file_name>_ diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index c8a2047a3..81c886e7a 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -2519,6 +2519,14 @@ For example, here is a reference to a title describing a tag:: See `HTML Element: \<a>`_ below. +The reference text may also be omitted, in which case the URI will be +duplicated for use as the reference text. This is useful for relative +URIs where the address or file name is also the desired reference +text:: + + See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__ + for details. + .. CAUTION:: This construct offers easy authoring and maintenance of hyperlinks -- cgit v1.2.1 From 04c04b5a28057ee8c6aabad94b77d27ec5c9d924 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 29 Dec 2003 20:07:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1782 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 81c886e7a..39e1168d4 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1565,15 +1565,15 @@ The standard Docutils system uses the following symbols for footnote marks [#]_: - asterisk/star ("*") -- dagger (HTML character entity "†") -- double dagger ("‡") -- section mark ("§") -- pilcrow or paragraph mark ("¶") +- dagger (HTML character entity "†", Unicode U+02020) +- double dagger ("‡"/U+02021) +- section mark ("§"/U+000A7) +- pilcrow or paragraph mark ("¶"/U+000B6) - number sign ("#") -- spade suit ("♠") -- heart suit ("♥") -- diamond suit ("♦") -- club suit ("♣") +- spade suit ("♠"/U+02660) +- heart suit ("♥"/U+02665) +- diamond suit ("♦"/U+02666) +- club suit ("♣"/U+02663) .. [#] This list was inspired by the list of symbols for "Note Reference Marks" in The Chicago Manual of Style, 14th edition, @@ -1584,6 +1584,11 @@ marks [#]_: If more than ten symbols are required, the same sequence will be reused, doubled and then tripled, and so on ("**" etc.). +.. Note:: When using auto-symbol footnotes, the choice of output + encoding is important. Many of the symbols used are not encodable + in certain common text encodings such as Latin-1 (ISO 8859-1). The + use of UTF-8 for the output encoding is recommended. + Mixed Manual and Auto-Numbered Footnotes ........................................ -- cgit v1.2.1 From 7e168dceedab63027fa670d76ab933cd8934f4b4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Dec 2003 04:01:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1783 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 39e1168d4..27dd7f52f 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1587,7 +1587,12 @@ reused, doubled and then tripled, and so on ("**" etc.). .. Note:: When using auto-symbol footnotes, the choice of output encoding is important. Many of the symbols used are not encodable in certain common text encodings such as Latin-1 (ISO 8859-1). The - use of UTF-8 for the output encoding is recommended. + use of UTF-8 for the output encoding is recommended. An + alternative for HTML and XML output is to use the + "xmlcharrefreplace" `output encoding error handler`__ (available in + Python 2.3 & later). + +__ http://docutils.sf.net/docs/config.html#output-encoding-error-handler Mixed Manual and Auto-Numbered Footnotes -- cgit v1.2.1 From 4641df8a891fbd052eba4f543e5cd87322bc3379 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 1 Jan 2004 02:12:47 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1785 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 11708953a..46b94b237 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -55,11 +55,6 @@ Bugs test/test_parsers/test_rst/test_directives/test_include.py (commented out, because the test fails). -* tools/buildhtml.py needs a mechanism to skip directories - (e.g. licenses, test). Perhaps a ".prune-buildhtml" file? A - command-line option wouldn't work because it would require user - action. Config file setting? - * Explicit targets are sometimes mis-located. In particular, placing a target before a section header puts the target at the end of the previous section instead of the start of the next section. The code @@ -820,11 +815,19 @@ __ rst/alternatives.html#or-not-to-do parse nested inline markup somehow? See the `collected notes <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. -* Drop the backticks from embedded URIs? Should the angle brackets be - kept in the output or not? :: +* 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"). + Directives `````````` -- cgit v1.2.1 From 5947725967d598c2dce014ce52b3f0f9985404aa Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 2 Jan 2004 23:18:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1788 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 46b94b237..c66fc80f3 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -828,6 +828,26 @@ __ rst/alternatives.html#or-not-to-do 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 markups). 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 + Directives `````````` -- cgit v1.2.1 From 10a6b744053a86b58f789caa23bfac62c1afa5fb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 4 Jan 2004 17:35:33 +0000 Subject: Added "target" option to "image" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1791 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 3eaaa9ef5..b794fa42c 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -215,6 +215,11 @@ The following options are recognized: text flow around it. The specific behavior depends upon the browser or rendering software used. +``target`` : text (URI or reference name) + Makes the image into a hyperlink reference ("clickable"). The + option argument may be a URI (relative or absolute), or a + reference name with underscore suffix (e.g. ``name_``). + ``class`` : text Set a "class" attribute value on the image element. See the class_ directive below. -- cgit v1.2.1 From eaab763e93ebde4bba8e04f6bbfad9e570417ea8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 4 Jan 2004 17:39:13 +0000 Subject: support for body-level reference nodes git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1792 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index dc58a9739..7add492f3 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -121,7 +121,7 @@ resolve to either an internal or external reference. | option_list | attention | caution | danger | error | hint | important | note | tip | warning | admonition - | target | substitution_definition | comment | pending + | reference | target | substitution_definition | comment | pending | system_message | raw %additional.body.elements; "> @@ -512,6 +512,7 @@ following caveats: <!ELEMENT literal (#PCDATA)> <!ATTLIST literal %basic.atts;> +<!-- Can also be a body element, when it contains an "image" element. --> <!ELEMENT reference %text.model;> <!ATTLIST reference %basic.atts; -- cgit v1.2.1 From 74bc7e3a7d5fe2ece9a48ffb4d368879e986b1bc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 12 Jan 2004 16:27:25 +0000 Subject: added "table" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1799 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c66fc80f3..159b3a204 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -120,7 +120,7 @@ General .. figure:: image.png :name: image's name - To name tables, we could use a "table" directive:: + Same for the "table" directive:: .. table:: optional title here :name: table's name @@ -868,7 +868,12 @@ when used in a document. - Add a "name" option to directives, to set an author-supplied identifier? - - _`images.image`: "border"? "link"? + - All directives that produce titled elements should grow implicit + reference names based on the titles. + + - @ _`body.table`: Document, add tests. + + - _`images.image`: "border"? Units of measure? (See docutils-users, 2003-03-02.) -- cgit v1.2.1 From 052145917ce39af4aea66142ad81df03003c87e0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Jan 2004 22:12:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1804 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 159b3a204..833f10152 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -39,7 +39,7 @@ Bugs Fixing this may be tricky, and isn't a high priority. Idea: two-pass hyperlink resolution, ignoring errors on the first - pass? + pass? Nah, too complicated. Perhaps the directive should do a bit more work up-front: create the "topic" and "title", and leave the "pending" node for contents. @@ -51,9 +51,10 @@ Bugs * In text inserted by the "include" directive, errors are often not reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need a "base_node" parameter. There's a test in - test/test_parsers/test_rst/test_directives/test_include.py - (commented out, because the test fails). + Reporter calls need "source" and "line" keyword arguments. + Elements' .line assignments should be checked. (Assign to .source + too? Add a set_info method? To what?) There's a test in + test/test_parsers/test_rst/test_directives/test_include.py. * Explicit targets are sometimes mis-located. In particular, placing a target before a section header puts the target at the end of the @@ -91,7 +92,9 @@ General permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?) -* Need a Unicode to HTML entities codec for HTML writer? +* Need a Unicode to HTML entities codec for HTML writer? No, the + "xmlcharrefreplace" output encoding error handler is sufficient. + Make it the default for HTML & XML writers? * Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? @@ -135,6 +138,9 @@ General 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: @@ -1596,14 +1602,22 @@ Index HTML Writer ----------- -* @@ Construct a _`templating system`, as in ht2html/yaptu, using - directives and substitutions for dynamic stuff. Or a specialized +* 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 a setting (or another writer) which produces just the contents - of the <body> element. What about the rest; it should be accessible - somehow, especially the docinfo fields. Part of the ht2html - implementation? Generic component output? + of the <body> element (_`HTML fragments`). What about the rest; it + should be accessible somehow, especially the docinfo fields. Part + of the ht2html implementation? Generic component output? I think a separate writer which inherits from html4css1.py would be a good start. An "inline" or body-only HTML writer has to omit some @@ -1624,6 +1638,9 @@ HTML Writer strings, or HTML snippets (they may contain markup), or both? There may be other issues to be worked out. + There's an example of such need in the recipe at + <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890>. + * Add more support for <link> elements, especially for navigation bars. -- cgit v1.2.1 From 15956c18451340052b543cd539571123abb2bd7f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Jan 2004 23:13:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1805 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 833f10152..e2c214e88 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -333,8 +333,8 @@ General * Merge doc/latex.txt info into tools.txt and config.txt. -* Add internationalization to footer boilerplate text (resulting from - "--generator", "--source-link", and "--date" etc.), allowing +* Add internationalization to _`footer boilerplate text` (resulting + from "--generator", "--source-link", and "--date" etc.), allowing translations. * Add an "--include file" command-line option (config setting too?), -- cgit v1.2.1 From dfcbde945755dd562f5008916333b28697452deb Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 20 Jan 2004 05:27:52 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1806 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e2c214e88..e554fe64d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -62,6 +62,9 @@ Bugs in docutils.transforms.misc.ClassAttribute could be used to fix this. (Reported by David Priest.) +* System messages shouldn't be filtered by the Writer, but by a + transform. See `Filtering System Messages`_. + General ------- @@ -1587,10 +1590,13 @@ Messages section). Filtering System Messages ````````````````````````` +@@@ Implement this. + Currently the Writer is responsible for filtering out system messages that are below the current threshold. Should the filtering be in a -separate transform? It would then happen regardless of the writer -used. Perhaps some writers don't want system messages filtered? +separate transform? [Yes.] It would then happen regardless of the +writer used. Perhaps some writers don't want system messages +filtered? [The user can adjust filtering levels.] Others -- cgit v1.2.1 From 7e511320b4d4525af31cc5ba4998647aa915dbbf Mon Sep 17 00:00:00 2001 From: fdrake <fdrake@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 22 Jan 2004 04:12:14 +0000 Subject: remove discrepency between example input and output (input comma not reflected in output; so removed from input) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1809 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e554fe64d..a956242ae 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -158,7 +158,7 @@ General - Parameterized substitutions? For example:: - See |figure (figure name)|, on |page (figure name)|. + See |figure (figure name)| on |page (figure name)|. .. |figure (name)| figure-ref:: (name) .. |page (name)| page-ref:: (name) -- cgit v1.2.1 From b24dd9aaa77085ba010d3d2aaa2a42dac8f73e16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Jan 2004 02:35:13 +0000 Subject: Added FilterMessages transform (removes system messages below the verbosity threshold) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1811 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/transforms.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index 4c5fe135a..fa866487c 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -71,7 +71,9 @@ universal.FinalChecks Transformer 840 universal.Messages Transformer 860 -universal.TestMessages DocutilsTestSupport 890 +universal.FilterMessages Transformer 870 + +universal.TestMessages DocutilsTestSupport 880 misc.CallBack n/a 990 ============================== ============================ ======== -- cgit v1.2.1 From 189c293b274e69419ed540d3dadcfbaf74b7df55 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Jan 2004 19:37:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1812 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 15 --------------- 1 file changed, 15 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a956242ae..faab08e8d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -62,9 +62,6 @@ Bugs in docutils.transforms.misc.ClassAttribute could be used to fix this. (Reported by David Priest.) -* System messages shouldn't be filtered by the Writer, but by a - transform. See `Filtering System Messages`_. - General ------- @@ -1587,18 +1584,6 @@ Messages transform ought to move all parse-time system messages Messages section). -Filtering System Messages -````````````````````````` - -@@@ Implement this. - -Currently the Writer is responsible for filtering out system messages -that are below the current threshold. Should the filtering be in a -separate transform? [Yes.] It would then happen regardless of the -writer used. Perhaps some writers don't want system messages -filtered? [The user can adjust filtering levels.] - - Others `````` -- cgit v1.2.1 From 9e5231402a34f7787d0202fdfdd83fa2157c89ec Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Jan 2004 16:11:29 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1819 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 19 +++++++++++++++++++ docs/ref/transforms.txt | 2 +- 2 files changed, 20 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index faab08e8d..4de246f84 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -854,6 +854,22 @@ __ rst/alternatives.html#or-not-to-do .. _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 + Directives `````````` @@ -869,6 +885,9 @@ when used in a document. * 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 diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index fa866487c..dd1d13ba3 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -61,7 +61,7 @@ parts.SectNum "sectnum" (d/p) 710 parts.Contents "contents" (d/p), 720 peps.Contents (t/p) -peps.PEPZero pep.Headers (t/p) 760 +peps.PEPZero peps.Headers (t/p) 760 components.Filter "meta" (d/p) 780 -- cgit v1.2.1 From 91581c29f399f5b5021327d94dfdb89564e6a3c8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Feb 2004 02:02:03 +0000 Subject: fixed link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1832 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index f89d89352..ce28aa5b7 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -208,7 +208,7 @@ >Escaping with Backslashes</a></h2> <p>(<a - href="../../spec/rst/reStructuredText.html#backslashes">details</a>) + href="../../spec/rst/reStructuredText.html#escaping-mechanism">details</a>) <p>reStructuredText uses backslashes ("\") to override the special meaning given to markup characters and get the literal characters -- cgit v1.2.1 From 2cc0da1d089e98ace23e27d5bfdcbe0bfc0e4efd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 24 Feb 2004 02:13:42 +0000 Subject: date git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1833 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index ce28aa5b7..6998e244c 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -18,7 +18,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-12-20</em> + <br align="right"><em>Updated 2004-02-23</em> <blockquote> <p>Copyright: This document has been placed in the public domain. -- cgit v1.2.1 From e6a675f2c54c52b8001d2c91ee957ba224384e65 Mon Sep 17 00:00:00 2001 From: aahz <aahz@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 20 Mar 2004 20:22:23 +0000 Subject: Suggest multi-line ``index`` directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1839 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4de246f84..5d6d62d47 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1152,7 +1152,12 @@ when used in a document. .. index:: syntax The explicit index directives above would refer to - this paragraph. + 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 -- cgit v1.2.1 From e17447558a38a56bdf0fc665dbd1bca765831bb7 Mon Sep 17 00:00:00 2001 From: aahz <aahz@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 21 Mar 2004 15:44:21 +0000 Subject: Update to make sections equivalent to documents, except sections must have title. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1842 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/docutils.dtd | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 7add492f3..5087d23d7 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -209,6 +209,11 @@ http://www.oasis-open.org/html/tm9901.htm). <!ELEMENT docinfo (%bibliographic.elements;)+> <!ATTLIST docinfo %basic.atts;> +<!-- Container for bibliographic elements. May not be empty. +Eventual replacement for docinfo? --> +<!ELEMENT info (%bibliographic.elements;)+> +<!ATTLIST info %basic.atts;> + <!ELEMENT author %text.model;> <!ATTLIST author %basic.atts;> @@ -262,7 +267,8 @@ http://www.oasis-open.org/html/tm9901.htm). ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> -<!ELEMENT section (title, %structure.model;)> +<!ELEMENT section + (title, subtitle?, info?, decoration?, %structure.model;)> <!ATTLIST section %basic.atts;> <!ELEMENT topic (title?, (%body.elements;)+)> -- cgit v1.2.1 From 2c868af6838d363ed0ca7fc5571b515622ecf3e2 Mon Sep 17 00:00:00 2001 From: reggie <reggie@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 22 Mar 2004 01:12:45 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1857 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5d6d62d47..6d63033a2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -26,23 +26,9 @@ you'd like to tackle, please do! Bugs ---- -* The "contents" directive now automatically names the "topic" - produced (using its title), so that it can be referred to by name. - However, this naming happens late in the game, after most references - have been resolved. So the following indirect target produces a - warning because the name "contents" is not available when resolved:: +Also see the `SourceForge Bug Tracker`__. - .. contents:: - - .. _alternate name for contents: contents_ - - Fixing this may be tricky, and isn't a high priority. - - Idea: two-pass hyperlink resolution, ignoring errors on the first - pass? Nah, too complicated. - - Perhaps the directive should do a bit more work up-front: create the - "topic" and "title", and leave the "pending" node for contents. +__ http://sourceforge.net/tracker/?group_id=38414&atid=422030 * The parser doesn't know anything about double-width characters such as Chinese hanza & Japanese kanji/kana. Also, it's dependent on -- cgit v1.2.1 From 82a7c91551ba17af1813fdfe69688c794ee2ce3e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 30 Mar 2004 21:59:00 +0000 Subject: allow additional text with RCS keywords git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1897 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 27dd7f52f..0e47be551 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -928,7 +928,7 @@ Processed, the "status" element's text will become simply "expansion text". The dollar sign delimiters and leading RCS keyword name are removed. -The RCS keyword processing only kicks in when all of these conditions +The RCS keyword processing only kicks in when both of these conditions hold: 1. The field list is in bibliographic context (first non-comment @@ -937,9 +937,6 @@ hold: 2. The field name is a recognized bibliographic field name. -3. The sole contents of the field is an expanded RCS keyword, of the - form "$Keyword: data $". - Option Lists ------------ -- cgit v1.2.1 From 32853fb8867cad20215e78497db1f39bf24416be Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 2 Apr 2004 02:31:30 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1903 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index df4f07765..370cf0d11 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -280,6 +280,12 @@ _`report_level` Default: warning (2). Options: ``--report, -r, --verbose, -v, --quiet, -q``. +_`sectnum_xform` + Enable or disable the section numbering transform + (docutils.transforms.parts.SectNum). + + Default: enabled (1). Options: ``--no-section-numbering``. + _`source_link` Include a "View document source" link in the document footer. URL will be relative to the destination. -- cgit v1.2.1 From fea4cfb1bfa0fc2034451420e204abf477384d6b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 11 Apr 2004 21:06:07 +0000 Subject: updated & added "Syntax for Line Blocks" section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1921 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 212 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 8e50f017d..e13834f03 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1989,6 +1989,15 @@ mailing list messages should be referred to for details. __ http://article.gmane.org/gmane.text.docutils.devel/795 +* Docutils-develop threads between David Abrahams, David Goodger, and + Mark Nodine (beginning 2004-01-16__ and 2004-01-19__) hashed out + many of the details of a potentially successful implementation, as + described below. David Abrahams checked in code to the "nesting" + branch of CVS, awaiting thorough review. + + __ http://thread.gmane.org/gmane.text.docutils.devel/1102 + __ http://thread.gmane.org/gmane.text.docutils.devel/1125 + It may be possible to accomplish nested inline markup in general with a more powerful inline markup parser. There may be some issues, but I'm not averse to the idea of nested inline markup in general. I just @@ -2012,6 +2021,209 @@ unambiguous:: IOW, the parser ought to be as permissive as possible. + +Syntax for Line Blocks +====================== + +* An early idea: How about a literal-block-like prefix, perhaps + "``;;``"? (It is, after all, a *semi-literal* literal block, no?) + Example:: + + Take it away, Eric the Orchestra Leader! ;; + + A one, two, a one two three four + + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? + + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + + Singing... + + Kinda lame. + +* Another idea: in an ordinary paragraph, if the first line ends with + a backslash (escaping the newline), interpret the entire paragraph + as a verse block? For example:: + + Add just one backslash\ + And this paragraph becomes + An awful haiku + + (Awful, and arguably invalid, since in Japanese the word "haiku" + contains three syllables not two.) + + This idea was superceded by the rules for escaped whitespace, useful + for `character-level inline markup`_. + +* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed + a "plain list" syntax (and also provided a patch):: + + | John Doe + | President, SuperDuper Corp. + | jdoe@example.org + + __ http://thread.gmane.org/gmane.text.docutils.devel/1187 + + This syntax is very natural. However, these "plain lists" seem very + similar to line blocks, and I see so little intrinsic "list-ness" + that I'm loathe to add a new object. I used the term "blurbs" to + remove the "list" connotation from the originally proposed name. + Perhaps line blocks could be refined to add the two properties they + currently lack: + + A) long lines wrap nicely + B) HTML output doesn't look like program code in non-CSS web + browsers + + (A) is an issue of all 3 aspects of Docutils: syntax (construct + behaviour), internal representation, and output. (B) is partly an + issue of internal representation but mostly of output. + +ReStructuredText will redefine line blocks with the "|"-quoting +syntax. The following is my current thinking. + + +Syntax +------ + +Perhaps line block syntax like this would do:: + + | M6: James Bond + | MIB: Mr. J. + | IMF: not decided yet, but probably one of the following: + | Ethan Hunt + | Jim Phelps + | Claire Phelps + | CIA: Felix Leiter + +Note that the "nested" list does not have nested syntax (the "|" are +not further indented); the leading whitespace would still be +significant somehow (more below). As for long lines in the input, +this could suffice:: + + | John Doe + | Founder, President, Chief Executive Officer, Cook, Bottle + Washer, and All-Round Great Guy + | SuperDuper Corp. + | jdoe@example.org + +The lack of "|" on the third line indicates that it's a continuation +of the second line, wrapped. + +I don't see much point in allowing arbitrary nested content. Multiple +paragraphs or bullet lists inside a "blurb" doesn't make sense to me. +Simple nested line blocks should suffice. + + +Internal Representation +----------------------- + +Line blocks are currently represented as text blobs as follows:: + + <!ELEMENT line_block %text.model;> + <!ATTLIST line_block + %basic.atts; + %fixedspace.att;> + +Instead, we could represent each line by a separate element:: + + <!ELEMENT line_block (line+)> + <!ATTLIST line_block %basic.atts;> + + <!ELEMENT line %text.model;> + <!ATTLIST line %basic.atts;> + +We'd keep the significance of the leading whitespace of each line +either by converting it to non-breaking spaces at output, or with a +per-line margin. Non-breaking spaces are simpler (for HTML, anyway) +but kludgey, and wouldn't support indented long lines that wrap. But +should inter-word whitespace (i.e., not leading whitespace) be +preserved? Currently it is preserved in line blocks. + +Representing a more complex line block may be tricky:: + + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + +Perhaps the representation could allow for nested line blocks:: + + <!ELEMENT line_block (line | line_block)+> + +With this model, leading whitespace would no longer be significant. +Instead, left margins are implied by the nesting. The example above +could be represented as follows:: + + <line_block> + <line> + But can a bee be said to be + <line_block> + <line> + or not to be an entire bee, + <line_block> + <line> + when half the bee is not a bee, + <line_block> + <line> + due to some ancient injury? + +I wasn't sure what to do about even more complex line blocks: + + | Indented + | Not indented + | Indented a bit + | A bit more + | Only one space + +How should that be parsed and nested? Should the first line have +the same nesting level (== indentation in the output) as the fourth +line, or the same as the last line? Mark Nodine suggested that such +line blocks be parsed similarly to complexly-nested block quotes, +which seems reasonable. In the example above, this would result in +the nesting of first line matching the last line's nesting. In +other words, the nesting would be relative to neighboring lines +only. + + +Output +------ + +In HTML, line blocks are currently output as "<pre>" blocks, which +gives us significant whitespace and line breaks, but doesn't allow +long lines to wrap and causes monospaced output without stylesheets. +Instead, we could output "<div>" elements parallelling the +representation above, where each nested <div class="line_block"> would +have an increased left margin (specified in the stylesheet). + +Jarno suggested the following HTML output:: + + <div class="line_block"> + <span class="line">First, top level line</span><br class="hidden"/> + <div class="line_block"><span class="hidden"> </span> + <span class="line">Second, once nested</span><br class="hidden"/> + <span class="line">Third, once nested</span><br class="hidden"/> + ... + </div> + ... + </div> + +The ``<br class="hidden" />`` and ``<span +class="hidden"> </span>`` are meant to support non-CSS and +non-graphical browsers. I understand the case for "br", but I'm not +so sure about hidden " ". I question how much effort should be +put toward supporting non-graphical and especially non-CSS browsers, +at least for html4css1.py output. + +Should the lines themselves be ``<span>`` or ``<div>``? I don't like +mixing inline and block-level elements. + .. Local Variables: -- cgit v1.2.1 From 8246856f69a27ec184f6096c1916a809c7c79470 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 11 Apr 2004 21:07:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1922 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 78 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 49 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6d63033a2..95203a675 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -48,6 +48,19 @@ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 in docutils.transforms.misc.ClassAttribute could be used to fix this. (Reported by David Priest.) +* Upon reviewing RFC 2396, I see that asterisks are valid URL + characters, sometimes actually used. Beni Cherniavsky found one in + mid-November and fixed it by modifying the text. There's a conflict + with emphasis, but backslash escapes should overcome that; they + don't though. I consider it a bug in the parser that escaped + asterisks in URLs aren't recognized. Here's the URL that broke:: + + http://cvs.sf.net/viewcvs.py/*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD + + We should be able to escape the first asterisk like this:: + + http://cvs.sf.net/viewcvs.py/\*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD + General ------- @@ -328,6 +341,17 @@ General 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. + Documentation ------------- @@ -650,36 +674,9 @@ __ rst/alternatives.html#or-not-to-do A section titled "3. Conclusion" could then be referred to by "``Conclusion_``" (i.e., without the "3."). -* Syntax for the "line-block" directive? How about a - literal-block-like prefix, perhaps "``;;``"? (It is, after all, a - *semi-literal* literal block, no?) Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? +* `Syntax for line blocks`__ (currently a directive)? - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - Another idea: in an ordinary paragraph, if the first line ends with - a backslash (escaping the newline), interpret the entire paragraph - as a verse block? For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (And arguably invalid, since in Japanese the word "haiku" contains - three syllables.) + __ rst/alternatives.html#syntax-for-line-blocks * Implement auto-enumerated lists? See `Auto-Enumerated Lists`__. @@ -856,6 +853,18 @@ __ rst/alternatives.html#or-not-to-do .. _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;))+ ) "> + Directives `````````` @@ -1241,6 +1250,17 @@ when used in a document. internal section structure, with adornment styles independent of the main document. + - _`body.list-table`: The idea came from Dylan Jay: + + ... to use a two level bulleted list with something to + indicate it should be rendered as a table ... + + It's an interesting idea. It could be implemented in as a + directive which transforms a uniform two-level bullet list into a + table. Using a directive would allow the author to explicitly set + the table's orientation (by column or by row), the presence of row + headers, etc. + - _`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" -- cgit v1.2.1 From 9a23cc3ee3b3e7bcedb9c3054dc7a19b7d61b45d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 11 Apr 2004 21:51:54 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1923 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 95203a675..06a2ecc2e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -342,7 +342,7 @@ General boilerplate, etc. * Parameterize the Reporter object or class? See the `2004-02-18 - "rest checking and source path"`__ thread. + "rest checking and source path"`_ thread. .. _2004-02-18 "rest checking and source path": http://thread.gmane.org/gmane.text.docutils.user/1112 @@ -350,7 +350,7 @@ General * 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. + source path"`_ thread. Documentation -- cgit v1.2.1 From 720d91776bccdd665e6fd05e067ef38bbaa7dde8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 11 Apr 2004 22:19:01 +0000 Subject: markup git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1924 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index e13834f03..9d72b296d 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -2174,7 +2174,7 @@ could be represented as follows:: <line> due to some ancient injury? -I wasn't sure what to do about even more complex line blocks: +I wasn't sure what to do about even more complex line blocks:: | Indented | Not indented -- cgit v1.2.1 From 73f74b9132a9b2351ee538827d89d6af80309b1e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 13 Apr 2004 20:25:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1927 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 80 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 65 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 370cf0d11..999b477f2 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -475,12 +475,16 @@ stylesheet __ `stylesheet [latex2e writer]`_ -_`stylesheet_path` +.. _stylesheet_path [html4css1 writer]: + +stylesheet_path Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL option (``--stylesheet``). Path is adjusted relative to the output HTML - file. + file. Also defined for the `LaTeX Writer`__. + + Default: None. Options: ``--stylesheet-path``. - Default: None. Options: ``--stylesheet``. + __ `stylesheet_path [latex2e writer]`_ .. _xml_declaration [html4css1 writer]: @@ -538,32 +542,35 @@ _`use_latex_toc` *Note:* LaTeX will number the sections, which might be a bug in this case. - Default: off. Options: ``--use-latex-toc``. + Default: off. Option: ``--use-latex-toc``. + +.. XXX Missing: use_latex_docinfo _`use_latex_footnotes` Use LaTeX-footnotes not a figure simulation. This might give no - Hyperrefs on /to footnotes, but should be able to handle an unlimited - number of footnotes. + Hyperrefs on /to footnotes, but should be able to handle an + unlimited number of footnotes. - Default: off. Options: ``--use-latex-footnotes``. + Default: off. Option: ``--use-latex-footnotes``. _`hyperlink_color` - Color of any hyperlinks embedded in text. Use "0" to disable coloring - of links. + Color of any hyperlinks embedded in text. Use "0" to disable + coloring of links. - Default: "blue", use "0" to disable. Options + Default: "blue", use "0" to disable. Option: + ``--hyperlink-color``. _`documentclass` Specify latex documentclass, *but* beaware that books have chapters articles not. - Default: "article". + Default: "article". Option: ``--documentclass``. _`documentoptions` Specify document options. Multiple options can be given, separated by commas. - Default is "10pt". + Default is "10pt". Option: ``--documentoptions``. .. _stylesheet [latex2e writer]: @@ -572,17 +579,30 @@ stylesheet the document header. If this is set to "" disables generation of input latex command. Also defined for the `HTML Writer`__. - Default: no stylesheet (""). + Default: no stylesheet (""). Option: ``--stylesheet``. __ `stylesheet [html4css1 writer]`_ +.. _stylesheet_path [latex2e writer]: + +stylesheet_path + Path to stylesheet [#pwd]_. Overrides "stylesheet" setting + (``--stylesheet``). XXX LaTeX semantics? Also defined for the + `HTML Writer`__. + + Default: None. Option: ``--stylesheet-path``. + + __ `stylesheet_path [html4css1 writer]`_ + +.. XXX Missing: embed_stylesheet + .. _footnote_references [latex2e writer]: footnote_references Format for footnote references: one of "superscript" or "brackets". Also defined for the `HTML Writer`__. - Default is "brackets". + Default is "brackets". Option: ``--footnote-references``. __ `footnote_references [html4css1 writer]`_ @@ -594,10 +614,40 @@ attribution "parentheses"/"parens" or "none". Also defined for the `HTML Writer`__. - Default: "dash". + Default: "dash". Option: ``--attribution``. __ `attribution [html4css1 writer]`_ +_`compound_enumerators` + Enable or disable compound enumerators for nested enumerated lists + (e.g. "1.2.a.ii"). + + Default: disabled (None). Options: ``--compound-enumerators``, + ``--no-compound-enumerators``. + +_`section_prefix_for_enumerators` + Enable or disable section ("." subsection ...) prefixes for + compound enumerators. This has no effect unless + `compound_enumerators`_ are enabled. + + Default: disabled (None). Options: + ``--section-prefix-for-enumerators``, + ``--no-section-prefix-for-enumerators``. + +_`section_enumerator_separator` + The separator between section number prefix and enumerator for + compound enumerated lists (see `compound_enumerators`_). + + Generally it isn't recommended to use both sub-sections and nested + enumerated lists with compound enumerators. This setting avoids + ambiguity in the situation where a section "1" has a list item + enumerated "1.1", and subsection "1.1" has list item "1". With a + separator of ".", these both would translate into a final compound + enumerator of "1.1.1". With a separator of "-", we get the + unambiguous "1-1.1" and "1.1-1". + + Default: "-". Option: ``--section-enumerator-separator``. + [pseudoxml writer] `````````````````` -- cgit v1.2.1 From e6f388c4ff48a6420a3246036fa98b1a25a6668d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 Apr 2004 13:05:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1931 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 75 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 66 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 06a2ecc2e..01a71fda8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -824,7 +824,7 @@ __ rst/alternatives.html#or-not-to-do <http://article.gmane.org/gmane.text.docutils.user/118>`__. Both a directive and an interpreted text role will be necessary (for - each markups). Directive example:: + each markup). Directive example:: .. itex:: \alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda) @@ -1348,10 +1348,13 @@ 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 be known by the Parser. -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. +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 @@ -1429,7 +1432,7 @@ elements. attributes? :: .. :api-ti: role:: api - :base: twisted.internet + :attributes: :base: twisted.internet To start the reactor, use the :api-ti:`reactor.run` method. To stop it, use :api-ti:`reactor.stop`. @@ -1680,6 +1683,17 @@ HTML Writer * 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 --------------- @@ -1787,8 +1801,7 @@ 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. Indent continuation lines - according to the Emacs python-mode standard. +* 4 spaces per indentation level. No tabs. * Use only ASCII, no 8-bit strings. See `Docutils Internationalization`_. @@ -1855,6 +1868,7 @@ 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 @@ -1890,7 +1904,7 @@ applicable), with particular emphasis as follows: `the sandbox`_ are the way to go. Docutils will pursue an open and trusting policy for as long as -possible, and deal with any abberations if (and hopefully not when) +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. @@ -1941,6 +1955,49 @@ It's easy to move code over to the main source tree once it's closer to completion. +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: + +* 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. + +* 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 + + Mailing Lists ------------- -- cgit v1.2.1 From ee454e58cbe80cfc90d30e12b525a9da3c211fe3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 15 Apr 2004 13:36:50 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1932 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 01a71fda8..ead44e113 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1964,20 +1964,6 @@ 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: -* 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. - * Update your ``PYTHONPATH`` environment variable so that Python picks up your local working copy of the code. This is the recommended method. @@ -1997,6 +1983,20 @@ meaning. There are two ways to keep the Docutils code accessible: 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 ------------- -- cgit v1.2.1 From 34a052d83eb5fd1c110498593cad7ecd23cbd284 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Apr 2004 15:11:41 +0000 Subject: begin phasing out tools/html.py git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1942 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index ee8277589..3b195e139 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -27,10 +27,10 @@ pattern:: toolname [options] [<source> [<destination]] -(The exceptions are buildhtml.py_ and pep2html.py_.) See html.py_ for -concrete examples. Each tool has a "``--help``" option which lists -the `command-line options`_ and arguments it supports. Processing can -also be customized with `configuration files`_. +(The exceptions are buildhtml.py_ and pep2html.py_.) See rst2html.py_ +for concrete examples. Each tool has a "``--help``" option which +lists the `command-line options`_ and arguments it supports. +Processing can also be customized with `configuration files`_. The two arguments, "source" and "destination", are optional. If only one argument (source) is specified, the standard output (stdout) is @@ -94,19 +94,19 @@ picked up automatically). Command-line options may be used to override config file settings or replace them altogether. -html.py -------- +rst2html.py +----------- :Reader: Standalone :Parser: reStructuredText :Writer: HTML -The ``html.py`` front end reads standalone reStructuredText source +The ``rst2html.py`` front end reads standalone reStructuredText source files and produces HTML 4 (XHTML 1) output compatible with modern browsers. For example, to process a reStructuredText file "``test.txt``" into HTML:: - html.py test.txt test.html + rst2html.py test.txt test.html In fact, there *is* a "``test.txt``" file in the "``tools``" directory. It contains "at least one example of each reStructuredText @@ -118,13 +118,13 @@ Now open the "``test.html``" file in your favorite browser to see the results. To get a footer with a link to the source file, date & time of processing, and links to the Docutils projects, add some options:: - html.py -stg test.txt test.html + rst2html.py -stg test.txt test.html Stylesheets ``````````` -``html.py`` inserts into the generated HTML a link to a cascading +``rst2html.py`` inserts into the generated HTML a link to a cascading stylesheet, defaulting to "``default.css``" (override with a "``--stylesheet``" or "``--stylesheet-path``" command-line option or with configuration file settings). The @@ -142,7 +142,7 @@ following:: Generate HTML with the following command:: - html.py -stg --stylesheet my.css test.txt test.html + rst2html.py -stg --stylesheet my.css test.txt test.html When viewed in a browser, the new "wrapper" stylesheet will change the typeface family of titles to "sans serif", typically Helvetica or -- cgit v1.2.1 From 22ea925181690c16c6574fcc8bea12caf65f5d71 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Apr 2004 18:44:13 +0000 Subject: Add problem with tilde in italian. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1952 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index de2b2eac4..1111bd5cd 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -203,6 +203,11 @@ Problems Open to be fixed or open to discussion. +Tilde in italian +---------------- + +Does not work, or only in verbatim or verb. + Tables ------ -- cgit v1.2.1 From 6a3188bfd186790c0601ac6f8a991878b54722f5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Apr 2004 17:38:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1955 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/i18n.txt | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt index 11a8d13bd..999fd7521 100644 --- a/docs/howto/i18n.txt +++ b/docs/howto/i18n.txt @@ -45,14 +45,18 @@ Language Module Names ===================== Language modules are named using a case-insensitive language -identifier as defined in `RFC 1766`_. A typical language identifier -consists of a 2-letter language code from `ISO 639`_ (3-letter codes -can be used if no 2-letter code exists; RFC 1766 is currently being -revised to allow 3-letter codes). The language identifier can have an -optional subtag, typically for variations based on country (from `ISO -3166`_ 2-letter country codes). If no language identifier is -specified, the default is "en" for English. Examples of module names -include ``en.py``, ``fr.py``, ``ja.py``, and ``pt-br.py``. +identifier as defined in `RFC 1766`_, converting hyphens to +underscores [#]_. A typical language identifier consists of a +2-letter language code from `ISO 639`_ (3-letter codes can be used if +no 2-letter code exists; RFC 1766 is currently being revised to allow +3-letter codes). The language identifier can have an optional subtag, +typically for variations based on country (from `ISO 3166`_ 2-letter +country codes). If no language identifier is specified, the default +is "en" for English. Examples of module names include ``en.py``, +``fr.py``, ``ja.py``, and ``pt_br.py``. + +.. [#] Subtags are separated from primary tags by underscores instead + of hyphens, to conform to Python naming rules. .. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html -- cgit v1.2.1 From 7f70385894d9c7b567f6a2caa5ef6d9f14fe0d9f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Apr 2004 18:16:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1957 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index 85a7b9a4b..a71e65fbb 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -175,18 +175,27 @@ directive function itself. Register the Directive ====================== -Register the new directive in -``docutils/parsers/rst/directives/__init__.py``, in the -``_directive_registry`` dictionary. This allows the reStructuredText -parser to find and use the directive. - -Add an entry to ``docutils/parsers/rst/languages/en.py`` for the -directive, mapping the English name to the canonical name (both -lowercase). Usually the English name and the canonical name are the -same. - -Please check for and update any other language modules for languages -in which you are proficient. +If the directive is a general-use addition to the Docutils core, it +must be registered with the parser and language mappings added: + +1. Register the new directive in + ``docutils/parsers/rst/directives/__init__.py``, in the + ``_directive_registry`` dictionary. This allows the + reStructuredText parser to find and use the directive. + +2. Add an entry to ``docutils/parsers/rst/languages/en.py`` for the + directive, mapping the English name to the canonical name (both + lowercase). Usually the English name and the canonical name are + the same. + +3. Please check for and update any other language modules for + languages in which you are proficient. + +If the directive is application-specific, use the +``register_directive`` function:: + + from docutils.parsers.rst import directives + directives.register_directive(directive_name, directive_function) Examples -- cgit v1.2.1 From 5de4bec88b62acfa5cd0da03753f96b67603799c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Apr 2004 22:50:37 +0000 Subject: added "role" directive git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1959 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 52 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b794fa42c..67948383d 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -961,6 +961,58 @@ The text above is parsed and transformed into this doctree fragment:: __ ../doctree.html#class +.. role:: + +Custom Interpreted Text Roles +============================= + +:Directive Type: "role" +:Doctree Element: None. +:Directive Arguments: One, required (role name). +:Directive Options: Possible. +:Directive Content: None. + +The "role" directive dynamically creates a custom interpreted text +role and registers it with the parser. This means that after +declaring a role like this:: + + .. role:: custom + +the document may use the "custom" role:: + + An example of using :custom:`interpreted text` + +This will be parsed into the following document tree fragment:: + + <paragraph> + An example of using + <inline class="custom"> + interpreted text + +The role must be declared in a document before it can be used. + +The ":class:" option can be used to set a "class" attribute that is +different from the role name. For example:: + + .. role:: custom + :class: special + + :custom:`interpreted text` + +This is the parsed result:: + + <paragraph> + <inline class="special"> + interpreted text + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the ``inline`` elements produced + when the custom interpreted text role is used. See the class_ + directive above. + + Restructuredtext-Test-Directive =============================== -- cgit v1.2.1 From 367d72fdb15af67679dc3ce11efb3699a08069bc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 17 Apr 2004 22:52:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1960 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index ead44e113..0b82f7642 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1419,14 +1419,24 @@ elements. element). The stylesheet would then pick up on the "class" attribute to do the actual formatting. (Allow other base elements?) + How do we pass in this "class" attribute (and other overrides)? + With an argument on role functions (``attributes={}``)? + The same thing could be done with a directive, albeit a bit more verbosely:: .. role:: rewrite :class: rewrite + Although as a convenience, the ":class:" option could be implicit:: + + .. role:: rewrite + The advantage of the new syntax would be flexibility. Uses other - than "class" may present themselves. + than "class" may present themselves. The disadvantage is + complexity: having to implement new syntax for a relatively + specialized operation, and having new semantics in existing + directives ("class::" would do something different). * Perhaps a "role" directive can modify existing roles with attributes? :: @@ -1437,6 +1447,10 @@ elements. To start the reactor, use the :api-ti:`reactor.run` method. To stop it, use :api-ti:`reactor.stop`. + The problem with this is that it allows arbitrary attributes. The + base role function must support those attributes, either passing + them on to the doc tree (DTD support) or processing them internally. + * Implement roles: - "acronym" and "abbreviation": Associate the full text with a short -- cgit v1.2.1 From 5ce1011f520060770e231a3924fd7017a1d20f82 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Apr 2004 00:28:38 +0000 Subject: oops git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1962 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 67948383d..4388fbe71 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -961,7 +961,7 @@ The text above is parsed and transformed into this doctree fragment:: __ ../doctree.html#class -.. role:: +.. _role: Custom Interpreted Text Roles ============================= -- cgit v1.2.1 From ee66a5ca1279d52bd40c431671905d3838f0f20f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Apr 2004 01:57:01 +0000 Subject: Added "Syntax for Interpreted Text Role Bindings" section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 9d72b296d..d859e83cf 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -265,6 +265,38 @@ desire *not* to use it unless absolutely necessary. It's a matter of finding the right balance. +Syntax for Interpreted Text Role Bindings +----------------------------------------- + +The following syntax (idea from Jeffrey C. Jacobs) could be used to +associate directives with roles. + + .. :rewrite: class:: rewrite + + `She wore ribbons in her hair and it lay with streaks of + grey`:rewrite: + +The syntax is similar to that of substitution declarations, and the +directive/role association may resolve implementation issues. The +semantics, ramifications, and implementation details would need to be +worked out. + +The example above would implement the "rewrite" role as adding a +``class="rewrite"`` attribute to the interpreted text ("inline" +element). The stylesheet would then pick up on the "class" attribute +to do the actual formatting. + +The advantage of the new syntax would be flexibility. Uses other than +"class" may present themselves. The disadvantage is complexity: +having to implement new syntax for a relatively specialized operation, +and having new semantics in existing directives ("class::" would do +something different). + +The `"role" directive`__ has been implemented. + +__ http://docutils.sf.net/spec/rst/directives.html#role + + Character Processing -------------------- -- cgit v1.2.1 From 3b2ef65a6ea197b95f47c7fa055c7d52868b022d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Apr 2004 01:59:04 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1964 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 77 +++++++++++++++++++------------------------------------ 1 file changed, 27 insertions(+), 50 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0b82f7642..cc5bf0f2d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -987,6 +987,33 @@ when used in a document. For a specific application, see the discussion of `character entity substitution definition files`_ above. + - _`misc.role`: + + - Allow other base roles? :: + + .. role:: custom + :base-role: abbreviation + + This might produce ``<abbreviation class="custom">``. + + How do we pass in this "class" attribute (and other overrides)? + With an argument on role functions (``attributes={}``)? + + - Perhaps the "role" directive can modify existing roles with + attributes? :: + + .. role:: api + :base-role: named-reference + :attributes: :base: twisted.internet + + To start the reactor, use the :api-ti:`reactor.run` method. + To stop it, use :api-ti:`reactor.stop`. + + The problem with this is that it allows arbitrary attributes. + The base role function must support those attributes, either + passing them on to the doc tree (DTD support) or processing them + internally. + * 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 @@ -1401,56 +1428,6 @@ elements. nested ``inline`` markup -* Add document-local _`role bindings`, associating directives with - roles? :: - - `She wore ribbons in her hair and it lay with streaks of - grey`:rewrite: - - .. :rewrite: class:: rewrite - - The syntax is similar to that of substitution declarations, and the - directive/role association may resolve implementation issues. The - semantics, ramifications, and implementation details do need to be - worked out though. Syntax idea from Jeffrey C. Jacobs. - - The example above would implement the "rewrite" role as adding a - ``class="rewrite"`` attribute to the interpreted text ("inline" - element). The stylesheet would then pick up on the "class" - attribute to do the actual formatting. (Allow other base elements?) - - How do we pass in this "class" attribute (and other overrides)? - With an argument on role functions (``attributes={}``)? - - The same thing could be done with a directive, albeit a bit more - verbosely:: - - .. role:: rewrite - :class: rewrite - - Although as a convenience, the ":class:" option could be implicit:: - - .. role:: rewrite - - The advantage of the new syntax would be flexibility. Uses other - than "class" may present themselves. The disadvantage is - complexity: having to implement new syntax for a relatively - specialized operation, and having new semantics in existing - directives ("class::" would do something different). - -* Perhaps a "role" directive can modify existing roles with - attributes? :: - - .. :api-ti: role:: api - :attributes: :base: twisted.internet - - To start the reactor, use the :api-ti:`reactor.run` method. To - stop it, use :api-ti:`reactor.stop`. - - The problem with this is that it allows arbitrary attributes. The - base role function must support those attributes, either passing - them on to the doc tree (DTD support) or processing them internally. - * Implement roles: - "acronym" and "abbreviation": Associate the full text with a short -- cgit v1.2.1 From 9215b0bae4953b8645160d755c099481cf81689f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Apr 2004 03:17:54 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1965 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index d859e83cf..b6d1236f4 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -269,12 +269,12 @@ Syntax for Interpreted Text Role Bindings ----------------------------------------- The following syntax (idea from Jeffrey C. Jacobs) could be used to -associate directives with roles. +associate directives with roles:: - .. :rewrite: class:: rewrite + .. :rewrite: class:: rewrite - `She wore ribbons in her hair and it lay with streaks of - grey`:rewrite: + `She wore ribbons in her hair and it lay with streaks of + grey`:rewrite: The syntax is similar to that of substitution declarations, and the directive/role association may resolve implementation issues. The -- cgit v1.2.1 From 806bf8f12b27e63511d79c989c7ef62350795e84 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 19 Apr 2004 01:20:08 +0000 Subject: howto for interpreted text roles git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1968 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-roles.txt | 139 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/howto/rst-roles.txt (limited to 'docs') diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt new file mode 100644 index 000000000..232e8bffb --- /dev/null +++ b/docs/howto/rst-roles.txt @@ -0,0 +1,139 @@ +================================================== + Creating reStructuredText Interpreted Text Roles +================================================== + +:Authors: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + +Interpreted text roles are an extension mechanism for inline markup in +reStructuredText. This document aims to make the creation of new +roles as easy and understandable as possible. + +Standard roles are described in `reStructuredText Interpreted Text +Roles`_. See the `Interpreted Text`_ section in the `reStructuredText +Markup Specification`_ for syntax details. + +.. _reStructuredText Interpreted Text Roles: ../rst/interpreted.html +.. _Interpreted Text: ../rst/reStructuredText.html#interpreted-text +.. _reStructuredText Markup Specification: ../rst/reStructuredText.html + + +.. contents:: + + +Define the Role Function +======================== + +The role function creates and returns inline elements (nodes) and does +any additional processing required. Its signature is as follows:: + + def role_fn(name, rawtext, text, lineno, inliner, attributes={}): + code... + +The role function parameters are as follows: + +* ``name``: The local name of the interpreted role, the role name + actually used in the document. + +* ``rawtext``: A string containing the enitre interpreted text input, + including the role and markup. This should be included as a literal + block in a system message if a problem is encountered. + +* ``text``: The interpreted text content. + +* ``lineno``: The line number where the interpreted text begins. + +* ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that + called role_fn. It contains the several attributes useful for error + reporting and document tree access. + +* ``attributes``: A dictionary of additional attributes for the + generated elements, used for customization. + +Role functions return a tuple of two values: + +* A list of nodes which will be inserted into the document tree at the + point where the interpreted role was encountered (can be an empty + list). + +* A list of system messages, which will be inserted into the document tree + immediately after the end of the current block (can also be empty). + + +Register the Role +================= + +If the role is a general-use addition to the Docutils core, it must be +registered with the parser and language mappings added: + +1. Register the new role using the canonical name:: + + from docutils.parsers.rst import roles + roles.register_canonical_role(name, role_function) + + This code is normally placed immediately after the definition of + the role funtion. + +2. Add an entry to the ``roles`` dictionary in + ``docutils/parsers/rst/languages/en.py`` for the role, mapping the + English name to the canonical name (both lowercase). Usually the + English name and the canonical name are the same. Abbreviations + and other aliases may also be added here. + +3. Update all the other language modules as well. For languages in + which you are proficient, please add translations. For other + languages, add the English role name plus "(translation required)". + +If the role is application-specific, use the ``register_local_role`` +function:: + + from docutils.parsers.rst import roles + roles.register_local_role(name, role_function) + + +Examples +======== + +For the most direct and accurate information, "Use the Source, Luke!". +All standard roles are documented in `reStructuredText Interpreted +Text Roles`_, and the source code implementing them is located in the +``docutils/parsers/rst/roles.py`` module. Several representative +roles are described below. + + +Generic Roles +------------- + +Many roles simply wrap a given element around the text. There's a +special helper function, ``register_generic_role``, which generates a +role function from the canonical role name and node class:: + + register_generic_role('emphasis', nodes.emphasis) + +For the implementation of ``register_generic_role``, see the +``docutils.parsers.rst.roles`` module. + + +RFC Reference Role +------------------ + +This role allows easy references to RFCs_ (Request For Comments +documents) by automatically providing the base URL, +http://www.faqs.org/rfcs/, and appending the RFC document itself +(rfcXXXX.html, where XXXX is the RFC number). For example:: + + See :RFC:`2822` for information about email headers. + +This is equivalent to:: + + See `RFC 2822`__ for information about email headers. + + __ http://www.faqs.org/rfcs/rfc2822.html + +As the implementation of this role is likely to be changed soon, a +description here will follow. + +.. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search -- cgit v1.2.1 From c943f9a4f5d0dc361ea77d81333532eff39811e1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 19 Apr 2004 01:22:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1969 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 ++++++++++------- docs/howto/rst-directives.txt | 16 +++++++++------- 2 files changed, 19 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index cc5bf0f2d..6c0a8db1d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -989,12 +989,20 @@ when used in a document. - _`misc.role`: - - Allow other base roles? :: + - Base the new role on other roles? :: .. role:: custom :base-role: abbreviation - This might produce ``<abbreviation class="custom">``. + This would make "custom" an alias for "abbreviation". With a + "base-role" option, the "class" would no longer be implied. It + would have to be explicitly specified:: + + .. role:: custom + :base-role: abbreviation + :class: special + + This might produce ``<abbreviation class="special">``. How do we pass in this "class" attribute (and other overrides)? With an argument on role functions (``attributes={}``)? @@ -1409,11 +1417,6 @@ elements. which contain interpreted text with no explicitly specified role (there will always be a default role, so this won't happen) -* Add a directive establishing a mapping of interpreted text role - aliases? A set of default roles (index, acronym, etc.) could exist, - and the directive could assign abbreviations (i, a, etc.) or other - alternatives. - * Add explicit interpreted text roles for the rest of the implicit inline markup constructs: named-reference, anonymous-reference, footnote-reference, citation-reference, substitution-reference, diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index a71e65fbb..6b612fced 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -178,18 +178,20 @@ Register the Directive If the directive is a general-use addition to the Docutils core, it must be registered with the parser and language mappings added: -1. Register the new directive in +1. Register the new directive using its canonical name in ``docutils/parsers/rst/directives/__init__.py``, in the ``_directive_registry`` dictionary. This allows the reStructuredText parser to find and use the directive. -2. Add an entry to ``docutils/parsers/rst/languages/en.py`` for the - directive, mapping the English name to the canonical name (both - lowercase). Usually the English name and the canonical name are - the same. +2. Add an entry to the ``directives`` dictionary in + ``docutils/parsers/rst/languages/en.py`` for the directive, mapping + the English name to the canonical name (both lowercase). Usually + the English name and the canonical name are the same. -3. Please check for and update any other language modules for - languages in which you are proficient. +3. Update all the other language modules as well. For languages in + which you are proficient, please add translations. For other + languages, add the English directive name plus "(translation + required)". If the directive is application-specific, use the ``register_directive`` function:: -- cgit v1.2.1 From fa486395e0412ae207135b7b9b1eceabbe2803e7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 19 Apr 2004 01:40:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1972 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4388fbe71..6dad0bfa4 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -1009,7 +1009,9 @@ The following option is recognized: ``class`` : text Set a "class" attribute value on the ``inline`` elements produced - when the custom interpreted text role is used. See the class_ + when the custom interpreted text role is used. If no directive + options are specified, a "class" option with the directive + argument (role name) as the value is implied. See the class_ directive above. -- cgit v1.2.1 From 0303d5d2084a675b6a49932bfd39a5f93491fb3d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 20 Apr 2004 23:53:43 +0000 Subject: improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1973 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index fb5ddeb89..78cace8b5 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -193,7 +193,8 @@ processing:: ``:title-reference:`` is the default interpreted text role in the standard reStructuredText parser. This means that no explicit role is required. Applications of reStructuredText may designate a different -default role, in which case the explicit role must be used. +default role, in which case the explicit ``:title-reference:`` role +must be used to obtain a ``title_reference`` element. .. _pseudo-XML: ../doctree.html#pseudo-xml -- cgit v1.2.1 From 132652882ac11a8ffb1f8a3981753cbf7b4232d0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 21 Apr 2004 01:09:39 +0000 Subject: improvements git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1974 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 0e47be551..356220634 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1850,8 +1850,9 @@ Directives Doctree elements: depend on the directive. Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new syntax. All -standard directives (those implemented and registered in the reference +adding support for new constructs without adding new primary syntax +(directives may support additional syntax locally). All standard +directives (those implemented and registered in the reference reStructuredText parser) are described in the `reStructuredText Directives`_ document, and are always available. Any other directives are domain-specific, and may require special action to make them @@ -1885,10 +1886,10 @@ these reasons: .. Danger: modify at your own risk! - If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), the entire - directive block (including the directive itself) will be treated as - a literal block, and a level-3 (error) system message generated. - Thus "::" is a natural choice. + directive (i.e., the directive-handler is not installed), a level-3 + (error) system message is generated, and the entire directive block + (including the directive itself) will be included as a literal + block. Thus "::" is a natural choice. The directive block is consists of any text on the first line of the directive after the directive marker, and any subsequent indented -- cgit v1.2.1 From 5a1d257aeb4f20b6f4b0d5a74dc5967208bc2ad9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Apr 2004 01:01:33 +0000 Subject: added "Reworking Explicit Markup (Round 2)" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1982 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 190 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index b6d1236f4..fd6922e1c 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -641,8 +641,8 @@ Markup`_ below) for the somewhat awkward ".. __:" syntax is "__":: __ http://anonymous -Reworking Explicit Markup -========================= +Reworking Explicit Markup (Round 1) +=================================== Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added to reStructuredText. Subsequently it was asserted that hyperlinks @@ -2256,6 +2256,192 @@ at least for html4css1.py output. Should the lines themselves be ``<span>`` or ``<div>``? I don't like mixing inline and block-level elements. + +Reworking Explicit Markup (Round 2) +=================================== + +See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion. + +In April 2004, a new thread becan on docutils-develop: `Inconsistency +in RST markup`__. Several arguments were made; the first argument +begat later arguments. Below, the arguments are paraphrased "in +quotes", with responses. + +__ http://thread.gmane.org/gmane.text.docutils.devel/1386 + +1. References and targets take this form:: + + targetname_ + + .. _targetname: stuff + + But footnotes, "which generate links just like targets do", are + written as:: + + [1]_ + + .. [1] stuff + + "Footnotes should be written as":: + + [1]_ + + .. _[1]: stuff + + But they're not the same type of animal. That's not a "footnote + target", it's a *footnote*. Being a target is not a footnote's + primary purpose (an arguable point). It just happens to grow a + target automatically, for convenience. Just as a section title:: + + Title + ===== + + isn't a "title target", it's a *title*, which happens to grow a + target automatically. The consistency is there, it's just deeper + than at first glance. + + Also, ".. [1]" was chosen for footnote syntax because it closely + resembles one form of actual footnote rendering. ".. _[1]:" is too + verbose; excessive punctuation is required to get the job done. + + For more of the reasoning behind the syntax, see `Problems With + StructuredText (Hyperlinks) + <http://docutils.sf.net/spec/rst/problems.html#hyperlinks>`__ and + `Reworking Footnotes`_. + +2. "I expect directives to also look like ``.. this:`` [one colon] + because that also closely parallels the link and footnote target + markup." + + There are good reasons for the two-colon syntax: + + Two colons are used after the directive type for these reasons: + + - Two colons are distinctive, and unlikely to be used in common + text. + + - Two colons avoids clashes with common comment text like:: + + .. Danger: modify at your own risk! + + - If an implementation of reStructuredText does not recognize a + directive (i.e., the directive-handler is not installed), a + level-3 (error) system message is generated, and the entire + directive block (including the directive itself) will be + included as a literal block. Thus "::" is a natural choice. + + -- http://docutils.sf.net/spec/rst/reStructuredText.html#directives + + The last reason is not particularly compelling; it's more of a + convenient coincidence or mnemonic. + +3. "Comments always seemed too easy. I almost never write comments. + I'd have no problem writing '.. comment:' in front of my comments. + In fact, it would probably be more readable, as comments *should* + be set off strongly, because they are very different from normal + text." + + Many people do use comments though, and some applications of + reStructuredText require it. For example, all reStructuredText + PEPs (and this document!) have an Emacs stanza at the bottom, in a + comment. Having to write ".. comment::" would be very obtrusive. + + Comments *should* be dirt-easy to do. It should be easy to + "comment out" a block of text. Comments in programming languages + and other markup languages are invariably easy. + + Any author is welcome to preface their comments with "Comment:" or + "Do Not Print" or "Note to Editor" or anything they like. A + "comment" directive could easily be implemented. It might be + confused with admonition directives, like "note" and "caution" + though. In unrelated (and unpublished and unfinished) work, adding + a "comment" directive as a true document element was considered:: + + If structure is necessary, we could use a "comment" directive + (to avoid nonsensical DTD changes, the "comment" directive + could produce an untitled topic element). + +4. "One of the goals of reStructuredText is to be *readable* by people + who don't know it. This construction violates that: it is not at + all obvious to the uninitiated that text marked by '..' is a + comment. On the other hand, '.. comment:' would be totally + transparent." + + Totally transparent, perhaps, but also very obtrusive. Another of + `reStructuredText's goals`_ is to be unobtrusive, and + ".. comment::" would violate that. The goals of reStructuredText + are many, and they conflict. Determining the right set of goals + and finding solutions that best fit is done on a case-by-case + basis. + + Even readability is has two aspects. Being readable without any + prior knowledge is one. Being as easily read in raw form as in + processed form is the other. ".." may not contribute to the former + aspect, but ".. comment::" would certainly detract from the latter. + + .. _author's note: + .. _reStructuredText's goals: + http://docutils.sf.net/spec/rst/introduction.html#goals + +5. "Recently I sent someone an rst document, and they got confused; I + had to explain to them that '..' marks comments, *unless* it's a + directive, etc..." + + The explanation of directives *is* roundabout, defining comments in + terms of not being other things. That's definitely a wart. + +6. "Under the current system, a mistyped directive (with ':' instead + of '::') will be silently ignored. This is an error that could + easily go unnoticed." + + A parser option/setting like "--comments-on-stderr" would help. + +7. "I'd prefer to see double-dot-space / command / double-colon as the + standard Docutils markup-marker. It's unusual enough to avoid + being accidently used. Everything that starts with a double-dot + should end with a double-colon." + + That would increase the punctuation verbosity of some constructs + considerably. + +8. Edward Loper proposed the following plan for backwards + compatibility: + + 1. ".. foo" will generate a deprecation warning to stderr, and + nothing in the output (no system messages). + 2. ".. foo: bar" will be treated as a directive foo. If there + is no foo directive, then do the normal error output. + 3. ".. foo:: bar" will generate a deprecation warning to + stderr, and be treated as a directive. Or leave it valid? + + So some existing documents might start printing deprecation + warnings, but the only existing documents that would *break* + would be ones that say something like:: + + .. warning: this should be a comment + + instead of:: + + .. warning:: this should be a comment + + Here, we're trading fairly common a silent error (directive + falsely treated as a comment) for a fairly uncommon explicitly + flagged error (comment falsely treated as directive). To make + things even easier, we could add a sentence to the + unknown-directive error. Something like "If you intended to + create a comment, please use '.. comment:' instead". + +On one hand, I understand and sympathize with the points raised. On +the other hand, I think the current syntax strikes the right balance +(but I acknowledge a possible lack of objectivity). On the gripping +hand, the comment and directive syntax has become well established, so +even if it's a wart, it may be a wart we have to live with. + +Making any of these changes would cause a lot of breakage or at least +deprecation warnings. I'm not sure the benefit is worth the cost. + +For now, we'll treat this as an unresolved legacy issue. + .. Local Variables: -- cgit v1.2.1 From dab6f305aada5a0b627c870c4b76db70e593c9bf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Apr 2004 01:06:20 +0000 Subject: fixed links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1983 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index fd6922e1c..f53d6048b 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -633,8 +633,8 @@ those up with anonymous targets. Keeping to a simple consistent ordering (as with auto-numbered footnotes) seems simplest. reStructuredText will use the explicit double-underscore syntax for -anonymous hyperlinks. An alternative (see `Reworking Explicit -Markup`_ below) for the somewhat awkward ".. __:" syntax is "__":: +anonymous hyperlinks. An alternative (see `Reworking Explicit Markup +(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__":: An anonymous__ reference. @@ -1134,9 +1134,9 @@ long way to go to add one word! Reworking Footnotes =================== -As a further wrinkle (see `Reworking Explicit Markup`_ above), in the -wee hours of 2002-02-28 I posted several ideas for changes to footnote -syntax: +As a further wrinkle (see `Reworking Explicit Markup (Round 1)`_ +above), in the wee hours of 2002-02-28 I posted several ideas for +changes to footnote syntax: - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... - Differentiate (with new DTD elements) author-date "citations" -- cgit v1.2.1 From c451f671b402bff1161ea643113493c3fa40343b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Apr 2004 13:28:27 +0000 Subject: update; text from Edward Loper git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1985 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 09bec5d88..c76920995 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -840,6 +840,11 @@ variable, ``__docformat__``, may appear at the top level of a module before any function or class definitions. Over time or through decree, a standard format or set of formats should emerge. +A module's ``__docformat__`` variable only applies to the objects +defined in the module's file. In particular, the ``__docformat__`` +variable in a package's ``__init__.py`` file does not apply to objects +defined in subpackages and submodules. + The ``__docformat__`` variable is a string containing the name of the format being used, a case-insensitive string matching the input parser's module or package name (i.e., the same name as required to -- cgit v1.2.1 From 79d178d4cc3c7ea624cd16b8e78f7127520bf4d8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 23 Apr 2004 14:01:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1987 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 356220634..8227432ad 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1881,7 +1881,9 @@ words (alphanumerics plus internal hyphens, underscores, and periods; no whitespace). Two colons are used after the directive type for these reasons: -- To avoid clashes with common comment text like:: +- Two colons are distinctive, and unlikely to be used in common text. + +- Two colons avoids clashes with common comment text like:: .. Danger: modify at your own risk! -- cgit v1.2.1 From a793f9125dbb4c4cb7c64f45480ffb2dceb0a70c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Apr 2004 15:36:44 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@1991 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6c0a8db1d..0bf8b59a9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -61,6 +61,8 @@ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 http://cvs.sf.net/viewcvs.py/\*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD +* Document title should grow an implicit target. + General ------- @@ -1569,10 +1571,11 @@ will have to be adjusted. (HTML only? Initially, yes. Eventually, anything should be splittable.) -Idea: insert a "split here" attribute into the root element of each +Idea: insert a "destination" attribute into the root element of each split-out document, containing the path/filename. The Output object -will recognize this attribute and split out the files accordingly. -Must allow for common headers & footers, prev/next, breadcrumbs, etc. +or Writer will recognize this attribute and split out the files +accordingly. Must allow for common headers & footers, prev/next, +breadcrumbs, etc. Navigation -- cgit v1.2.1 From 2e594eab0b980f2357c83ab560bc07c0d5779117 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Apr 2004 19:53:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2002 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 ++++++++-- docs/howto/rst-directives.txt | 6 +-- docs/howto/rst-roles.txt | 97 +++++++++++++++++++++++++++++++++++++++---- docs/ref/rst/directives.txt | 62 ++++++++++++++++++++------- docs/ref/rst/roles.txt | 58 ++++++++++++++++++++++++-- 5 files changed, 210 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0bf8b59a9..5aadb44dc 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -354,6 +354,12 @@ General 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. + Documentation ------------- @@ -2022,9 +2028,9 @@ 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 their own subdirectory (suggested name: SourceForge ID, -nickname, or given name + family initial). It's OK to make a mess! -But please, play nice. +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. @@ -2034,7 +2040,9 @@ out new, experimental components, the following sandbox directory structure is recommended:: sandbox/ - userid/ + 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. @@ -2110,6 +2118,7 @@ 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 @@ -2117,6 +2126,10 @@ 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``. diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index 6b612fced..f44dbc07c 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -90,8 +90,8 @@ Tree`_ and the ``docutils.nodes`` module. Specify Directive Arguments, Options, and Content ================================================= -Function attributes are interpreted by the directive parser (the -``docutils.parsers.rst.states.Body.parse_directive()`` method). If +Function attributes are interpreted by the directive parser (from the +``docutils.parsers.rst.states.Body.run_directive()`` method). If unspecified, directive function attributes are assumed to have the value ``None``. Three directive function attributes are recognized: @@ -168,7 +168,7 @@ value ``None``. Three directive function attributes are recognized: functions must handle the case where content is required but not present in the input text (an empty content list will be supplied). -The final step of the ``parse_directive()`` method is to call the +The final step of the ``run_directive()`` method is to call the directive function itself. diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt index 232e8bffb..9f13f2937 100644 --- a/docs/howto/rst-roles.txt +++ b/docs/howto/rst-roles.txt @@ -30,17 +30,23 @@ Define the Role Function The role function creates and returns inline elements (nodes) and does any additional processing required. Its signature is as follows:: - def role_fn(name, rawtext, text, lineno, inliner, attributes={}): + def role_fn(name, rawtext, text, lineno, inliner, + options={}, content=[]): code... -The role function parameters are as follows: + # Set function attributes for customization: + role_fn.options = ... + role_fn.content = ... + +Function attributes are described below (see `Specify Role Function +Options and Content`_). The role function parameters are as follows: * ``name``: The local name of the interpreted role, the role name actually used in the document. * ``rawtext``: A string containing the enitre interpreted text input, - including the role and markup. This should be included as a literal - block in a system message if a problem is encountered. + including the role and markup. Return it as a ``problematic`` node + linked to a system message if a problem is encountered. * ``text``: The interpreted text content. @@ -50,8 +56,13 @@ The role function parameters are as follows: called role_fn. It contains the several attributes useful for error reporting and document tree access. -* ``attributes``: A dictionary of additional attributes for the - generated elements, used for customization. +* ``options``: A dictionary of directive options for customization, to + be interpreted by the role function. Used for additional attributes + for the generated elements and other functionality. + +* ``content``: A list of strings, the directive content for + customization ("role" directive). To be interpreted by the role + function. Role functions return a tuple of two values: @@ -63,6 +74,42 @@ Role functions return a tuple of two values: immediately after the end of the current block (can also be empty). +Specify Role Function Options and Content +========================================= + +Function attributes are for customization, and are interpreted by the +`"role" directive`_. If unspecified, role function attributes are +assumed to have the value ``None``. Two function attributes are +recognized: + +- ``options``: The option specification. All role functions + implicitly support the "class" option, unless disabled with an + explicit ``{'class': None}``. + + An option specification must be defined detailing the options + available to the "role" directive. An option spec is a mapping of + option name to conversion function; conversion functions are applied + to each option value to check validity and convert them to the + expected type. Python's built-in conversion functions are often + usable for this, such as ``int``, ``float``, and ``bool`` (included + in Python from version 2.2.1). Other useful conversion functions + are included in the ``docutils.parsers.rst.directives`` package. + For further details, see `Creating reStructuredText Directives`_. + +- ``content``: A boolean; true if "role" directive content is allowed. + Role functions must handle the case where content is required but + not supplied (an empty content list will be supplied). + + As of this writing, no roles accept directive content. + +Note that unlike directives, the "arguments" function attribute is not +supported for role customization. Directive arguments are handled by +the "role" directive itself. + +.. _Creating reStructuredText Directives: + rst-directives.html#specify-directive-arguments-options-and-content + + Register the Role ================= @@ -133,7 +180,41 @@ This is equivalent to:: __ http://www.faqs.org/rfcs/rfc2822.html -As the implementation of this role is likely to be changed soon, a -description here will follow. +Here is the implementation of the role:: + + def rfc_reference_role(role, rawtext, text, lineno, inliner, + options={}, content=[]): + try: + rfcnum = int(text) + if rfcnum <= 0: + raise ValueError + except ValueError: + msg = inliner.reporter.error( + 'RFC number must be a number greater than or equal to 1; ' + '"%s" is invalid.' % text, line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + # Base URL mainly used by inliner.rfc_reference, so this is correct: + ref = inliner.rfc_url % rfcnum + node = nodes.reference(rawtext, 'RFC ' + text, refuri=ref, **options) + return [node], [] + + register_canonical_role('rfc-reference', rfc_reference_role) + +Noteworthy in the code above are: + +1. The interpreted text itself should contain the RFC number. The + ``try`` clause verifies by converting it to an integer. If the + conversion fails, the ``except`` clause is executed: a system + message is generated, the entire interpreted text construct (in + ``rawtext``) is wrapped in a ``problematic`` node (linked to the + system message), and the two are returned. + +2. The RFC reference itself is constructed from a stock URI, set as + the "refuri" attribute of a "reference" element. + +3. The ``options`` function parameter, a dictionary, may contain a + "class" customization attribute; it is passed through to the + "reference" element node constructor. .. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 6dad0bfa4..f21b9afcc 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -33,12 +33,14 @@ Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to individual directives. For details on the hierarchy of elements, please see `The Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. +type definition. For directive implementation details, see `Creating +reStructuredText Directives`_. -.. _Directives: ./reStructuredText.html#directives -.. _reStructuredText Markup Specification: ./reStructuredText.html +.. _Directives: reStructuredText.html#directives +.. _reStructuredText Markup Specification: reStructuredText.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd +.. _Creating reStructuredText Directives: ../howto/rst-directives.html ------------- @@ -967,10 +969,11 @@ Custom Interpreted Text Roles ============================= :Directive Type: "role" -:Doctree Element: None. -:Directive Arguments: One, required (role name). -:Directive Options: Possible. -:Directive Content: None. +:Doctree Element: None; affects subsequent parsing. +:Directive Arguments: Two; one required (role name), one optional + (base role name, in parentheses). +:Directive Options: Possible (depends on base role). +:Directive Content: depends on base role. The "role" directive dynamically creates a custom interpreted text role and registers it with the parser. This means that after @@ -978,7 +981,7 @@ declaring a role like this:: .. role:: custom -the document may use the "custom" role:: +the document may use the new "custom" role:: An example of using :custom:`interpreted text` @@ -991,8 +994,26 @@ This will be parsed into the following document tree fragment:: The role must be declared in a document before it can be used. -The ":class:" option can be used to set a "class" attribute that is -different from the role name. For example:: +The new role may be based on an existing role, specified as a second +argument in parentheses (whitespace optional):: + + .. role:: custom(emphasis) + + :custom:`text` + +The parsed result is as follows:: + + <paragraph> + <emphasis class="custom"> + text + +If no base role is explicitly specified, a generic custom role is +automatically used. Subsequent interpreted text will produce an +"inline" element with a "class" attribute, as in the first example +above. + +With most roles, the ":class:" option can be used to set a "class" +attribute that is different from the role name. For example:: .. role:: custom :class: special @@ -1005,14 +1026,23 @@ This is the parsed result:: <inline class="special"> interpreted text -The following option is recognized: +.. _role class: + +The following option is recognized by the "role" directive for most +base roles: ``class`` : text - Set a "class" attribute value on the ``inline`` elements produced - when the custom interpreted text role is used. If no directive - options are specified, a "class" option with the directive - argument (role name) as the value is implied. See the class_ - directive above. + Set a "class" attribute value on the element produced (``inline``, + or element associated with a base class) when the custom + interpreted text role is used. If no directive options are + specified, a "class" option with the directive argument (role + name) as the value is implied. See the class_ directive above. + +Specific roles may support other options and/or directive content. +See the `reStructuredText Interpreted Text Roles`_ document for +details. + +.. _reStructuredText Interpreted Text Roles: interpreted.html Restructuredtext-Test-Directive diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index 78cace8b5..d93a2bf9d 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -23,20 +23,51 @@ is used if no explicit ``:role:`` prefix or suffix is given. The "default default role" is `:title-reference:`_. See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. +Specification`_ for syntax details. For details on the hierarchy of +elements, please see `The Docutils Document Tree`_ and the `Docutils +Generic DTD`_ XML document type definition. For interpreted text role +implementation details, see `Creating reStructuredText Interpreted +Text Roles`_. -.. _Interpreted Text: ./reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: ./reStructuredText.html +.. _"role" directive: directives.html#role +.. _Interpreted Text: reStructuredText.html#interpreted-text +.. _reStructuredText Markup Specification: reStructuredText.html +.. _The Docutils Document Tree: ../doctree.html +.. _Docutils Generic DTD: ../docutils.dtd +.. _Creating reStructuredText Interpreted Text Roles: ../howto/rst-roles.html .. contents:: +--------------- + Customization +--------------- + +Custom interpreted text roles may be defined in a document with the +`"role" directive`_. Customization details are listed with each role. + +.. _class: + +The ``class`` option is recognized by the "role" directive for most +interpreted text roles. A description__ is provided by `"role" +directive`_ documentation. + +__ directives.html#role-class + + +--------------------------------- + Standard Interpreted Text Roles +--------------------------------- + ``:emphasis:`` ============== :Aliases: None :DTD Element: emphasis +:Customization: + :Options: class_. + :Content: None. Implements emphasis. These are equivalent:: @@ -49,6 +80,9 @@ Implements emphasis. These are equivalent:: :Aliases: None :DTD Element: literal +:Customization: + :Options: class_. + :Content: None. Implements inline literal text. These are equivalent:: @@ -71,6 +105,9 @@ spaces. :Aliases: ``:PEP:`` :DTD Element: reference +:Customization: + :Options: class_. + :Content: None. The ``:pep-reference:`` role is used to create an HTTP reference to a PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually @@ -90,6 +127,9 @@ This is equivalent to:: :Aliases: ``:RFC:`` :DTD Element: reference +:Customization: + :Options: class_. + :Content: None. The ``:rfc-reference:`` role is used to create an HTTP reference to an RFC (Internet Request for Comments). The ``:RFC:`` alias is usually @@ -109,6 +149,9 @@ This is equivalent to:: :Aliases: None :DTD Element: strong +:Customization: + :Options: class_. + :Content: None. Implements strong emphasis. These are equivalent:: @@ -121,6 +164,9 @@ Implements strong emphasis. These are equivalent:: :Aliases: ``:sub:`` :DTD Element: subscript +:Customization: + :Options: class_. + :Content: None. Implements subscripts. @@ -154,6 +200,9 @@ Implements subscripts. :Aliases: ``:sup:`` :DTD Element: superscript +:Customization: + :Options: class_. + :Content: None. Implements superscripts. See the tip in `:subscript:`_ above. @@ -163,6 +212,9 @@ Implements superscripts. See the tip in `:subscript:`_ above. :Aliases: ``:title:``, ``:t:``. :DTD Element: title_reference +:Customization: + :Options: class_. + :Content: None. The ``:title-reference:`` role is used to describe the titles of books, periodicals, and other materials. It is the equivalent of the -- cgit v1.2.1 From 60368779e38cb87ae9d828cc542e4589817af655 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Apr 2004 20:20:59 +0000 Subject: link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2004 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-roles.txt | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt index 9f13f2937..634dbcc68 100644 --- a/docs/howto/rst-roles.txt +++ b/docs/howto/rst-roles.txt @@ -56,13 +56,14 @@ Options and Content`_). The role function parameters are as follows: called role_fn. It contains the several attributes useful for error reporting and document tree access. -* ``options``: A dictionary of directive options for customization, to - be interpreted by the role function. Used for additional attributes - for the generated elements and other functionality. +* ``options``: A dictionary of directive options for customization + (from the `"role" directive`_), to be interpreted by the role + function. Used for additional attributes for the generated elements + and other functionality. * ``content``: A list of strings, the directive content for - customization ("role" directive). To be interpreted by the role - function. + customization (from the `"role" directive`_). To be interpreted by + the role function. Role functions return a tuple of two values: @@ -106,6 +107,7 @@ Note that unlike directives, the "arguments" function attribute is not supported for role customization. Directive arguments are handled by the "role" directive itself. +.. _"role" directive: directives.html#role .. _Creating reStructuredText Directives: rst-directives.html#specify-directive-arguments-options-and-content -- cgit v1.2.1 From a24203dececda64399584198118d239cf687a354 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Apr 2004 15:20:30 +0000 Subject: Comments on underscore. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2008 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 1111bd5cd..d14496d50 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -236,13 +236,19 @@ Tables maybe use ltxtable instead of tabularx (Longtable combined with tabularx). but ltxtable disables longtable's multicolumn. * Table cells with multirow and multicolumn -* Tables have borders, and the border is missing in empty cells. - Miscellaneous ------------- -* recongize LaTeX (or even LaTeX) and replace by ``\LaTeX``. +* The underscore ``_`` does not work in literal-blocks, has different width. + I tried + + - Escape it ``{\_}`` to narrow + - Underline a blank ``\underline{ }`` to low, as in windows-xp. + - Subscript a hyphen ``$_{\tt-}$ too wide and thin + - ``$_{-}$`` the same. + +* recongize LaTeX and replace by ``\LaTeX``. * Support embed-stylesheet. * the ^-sign is problematic: using mathmode wedge is usually the wrong font. * Sidebar handling. -- cgit v1.2.1 From 7623e44c5694907f0c3e55b872203404ff8e1915 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Apr 2004 21:09:03 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2009 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index d14496d50..f72b26015 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -245,7 +245,7 @@ Miscellaneous - Escape it ``{\_}`` to narrow - Underline a blank ``\underline{ }`` to low, as in windows-xp. - - Subscript a hyphen ``$_{\tt-}$ too wide and thin + - Subscript a hyphen ``$_{\tt-}$`` too wide and thin - ``$_{-}$`` the same. * recongize LaTeX and replace by ``\LaTeX``. -- cgit v1.2.1 From b54987eb76da2804dc79906888d67d8b35da4755 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Apr 2004 21:49:53 +0000 Subject: Added --initial-header-level option. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2010 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 999b477f2..3e225dfbe 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -370,7 +370,7 @@ _`doctitle_xform` to document title (and subsequent section title to document subtitle promotion; docutils.transforms.frontmatter.DocTitle). - Default: enabled (). Options: ``--no-doc-title``. + Default: enabled (1). Options: ``--no-doc-title``. [pep reader] @@ -464,6 +464,12 @@ footnote_references __ `footnote_references [latex2e writer]`_ +_`initial_header_level` + The initial level for header elements. This does not affect the + document title & subtitle; see doctitle_xform_. + + Default: 1 (for "<h1>"). Option: ``--initial-header-level``. + .. _stylesheet [html4css1 writer]: stylesheet -- cgit v1.2.1 From dde9522359e52fa40a2a2652cece35bdc363ac32 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 28 Apr 2004 21:52:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2012 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 29 ----------------------------- 1 file changed, 29 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5aadb44dc..bf160b7b0 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1641,33 +1641,6 @@ HTML Writer a templating system to apply to their reStructuredText documents as best serves their interests. -* Add a setting (or another writer) which produces just the contents - of the <body> element (_`HTML fragments`). What about the rest; it - should be accessible somehow, especially the docinfo fields. Part - of the ht2html implementation? Generic component output? - - I think a separate writer which inherits from html4css1.py would be - a good start. An "inline" or body-only HTML writer has to omit some - of the information given by the full HTML writer. Some applications - won't need this information, but others will; they'll want to deal - with it in different ways. I envision such a writer returning a set - of values: body html, and everything else (metadata). Perhaps a - tuple of this form:: - - (body_html, {'title': value, - 'subtitle': value, - 'docinfo': (tuple of (name, value) pairs), - etc.}) - - By having a separate writer, a different return data structure is - possible. We may need to add support to all of docutils to allow - for this variant output. Should the metadata values be simple text - strings, or HTML snippets (they may contain markup), or both? There - may be other issues to be worked out. - - There's an example of such need in the recipe at - <http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/193890>. - * Add more support for <link> elements, especially for navigation bars. @@ -1675,8 +1648,6 @@ HTML Writer * Make the "class" attributes optional? Implies no stylesheet? -* Add a setting to customize the header tag levels, i.e. <h1>. - * Base list compaction on the spacing of source list? Would require parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.) -- cgit v1.2.1 From 1576e5c45f0b3c071ebe4e9e198976c72fed00c8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 Apr 2004 12:57:29 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2015 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index bf160b7b0..053ab79f5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -903,7 +903,10 @@ when used in a document. - _`images.image`: "border"? - Units of measure? (See docutils-users, 2003-03-02.) + _`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? -- cgit v1.2.1 From 7a9701ccbe135621562c1f1ad1e29a2d264af92a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 30 Apr 2004 21:31:56 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2016 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 38 ++++---------------------------------- 1 file changed, 4 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 053ab79f5..577cb9280 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -963,6 +963,8 @@ when used in a document. - _`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? @@ -998,40 +1000,8 @@ when used in a document. For a specific application, see the discussion of `character entity substitution definition files`_ above. - - _`misc.role`: - - - Base the new role on other roles? :: - - .. role:: custom - :base-role: abbreviation - - This would make "custom" an alias for "abbreviation". With a - "base-role" option, the "class" would no longer be implied. It - would have to be explicitly specified:: - - .. role:: custom - :base-role: abbreviation - :class: special - - This might produce ``<abbreviation class="special">``. - - How do we pass in this "class" attribute (and other overrides)? - With an argument on role functions (``attributes={}``)? - - - Perhaps the "role" directive can modify existing roles with - attributes? :: - - .. role:: api - :base-role: named-reference - :attributes: :base: twisted.internet - - To start the reactor, use the :api-ti:`reactor.run` method. - To stop it, use :api-ti:`reactor.stop`. - - The problem with this is that it allows arbitrary attributes. - The base role function must support those attributes, either - passing them on to the doc tree (DTD support) or processing them - internally. + - _`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 -- cgit v1.2.1 From 66ca9616a3b98b7fa4f9c27164911255887f4f31 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 4 May 2004 00:44:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2023 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 577cb9280..b13118cc0 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -63,6 +63,16 @@ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 * Document title should grow an implicit target. +* David Abrahams pointed out that doubly-indirect substitutions have a + bug, but only when there's multiple references:: + + |substitute| my coke for gin + |substitute| you for my mum + at least I'll get my washing done + + .. |substitute| replace:: |replace| + .. |replace| replace:: swap + General ------- @@ -1634,7 +1644,7 @@ HTML Writer 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 ... -- cgit v1.2.1 From 634c665bb1f1ec6c26974a3f3ed23868ec49f6f4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 4 May 2004 00:58:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2024 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 8227432ad..52d30033d 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1703,8 +1703,8 @@ indirect. .. _archive: .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ - An inline form of internal hyperlink target is available; see - `Inline Internal Targets`_. + An inline form of internal hyperlink target is available; see + `Inline Internal Targets`_. 2. _`External hyperlink targets` have an absolute or relative URI or email address in their link blocks. For example, take the -- cgit v1.2.1 From 6bd8903fccd5d0950e8d3b130d08884e1c6d3a6c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 02:04:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2032 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f21b9afcc..cbd70a0ae 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -205,7 +205,8 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. + symbol is required or allowed). "100" means full-size. PIL_ + [#PIL]_ may be required. ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ``<img>`` tag's @@ -272,9 +273,9 @@ options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL_ [#]_). If the - image file is not found or the required software is unavailable, - this option is ignored. + included image's actual width is used (requires PIL_ [#PIL]_). If + the image file is not found or the required software is + unavailable, this option is ignored. Sets the "width" attribute of the "figure" doctree element. @@ -300,7 +301,7 @@ options are recognized: Set a "class" attribute value on the figure element. See the class_ directive below. -.. [#] `Python Imaging Library`_. +.. [#PIL] `Python Imaging Library`_. .. _PIL: .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -- cgit v1.2.1 From efc28aa7196aa0b8a4e6305b44f99cd383453e13 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 02:09:47 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2033 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cbd70a0ae..f5dedbbd7 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -205,7 +205,7 @@ The following options are recognized: ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. PIL_ + symbol is required or allowed). "100" means full-size. PIL [#PIL]_ may be required. ``align`` : "top", "middle", "bottom", "left", "center", or "right" @@ -273,7 +273,7 @@ options are recognized: ``figwidth`` : integer or "image" The width of the figure in pixels, to limit the horizontal space used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL_ [#PIL]_). If + included image's actual width is used (requires PIL [#PIL]_). If the image file is not found or the required software is unavailable, this option is ignored. @@ -303,7 +303,6 @@ options are recognized: .. [#PIL] `Python Imaging Library`_. -.. _PIL: .. _Python Imaging Library: http://www.pythonware.com/products/pil/ -- cgit v1.2.1 From 50235a374afca458e319256c9bfe8c466dfc567c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 7 May 2004 16:25:23 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2046 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index f5dedbbd7..cc2657b1b 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -196,17 +196,24 @@ The following options are recognized: for visually impaired users. ``height`` : integer - The height of the image in pixels, used to reserve space or scale - the image vertically. + The desired height of the image in pixels, used to reserve space + or scale the image vertically. When the "scale" option is also + specified, they are combined. For example, a height of 200 and a + scale of 50 is equivalent to a height of 100 with no scale. ``width`` : integer The width of the image in pixels, used to reserve space or scale - the image horizontally. + the image horizontally. As with "height" above, when the "scale" + option is also specified, they are combined. ``scale`` : integer The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. PIL - [#PIL]_ may be required. + symbol is required or allowed). "100" means full-size, and is + equivalent to omitting a "scale" option. + + If no "height" or "width" options are specified, PIL [#PIL]_ may + be used to determine them, if PIL is installed and the image file + is available. ``align`` : "top", "middle", "bottom", "left", "center", or "right" The alignment of the image, equivalent to the HTML ``<img>`` tag's @@ -988,7 +995,7 @@ the document may use the new "custom" role:: This will be parsed into the following document tree fragment:: <paragraph> - An example of using + An example of using <inline class="custom"> interpreted text -- cgit v1.2.1 From d6f10b154951bef4e580c46ad7a624252a1e3268 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 9 May 2004 13:45:44 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2062 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 +++++++++++++++++++++ docs/ref/doctree.txt | 4 ++++ 2 files changed, 25 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b13118cc0..eb79a9e6e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -73,6 +73,27 @@ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 .. |substitute| replace:: |replace| .. |replace| replace:: swap + This is tricky. Substitutions have to propagate back completely. + +* Another bug from David Abrahams (run with ``rst2html.py --traceback``):: + + .. [#crtp] See |runtime| + + foo [#tag_dispatching]_ + + .. [#tag_dispatching] See |runtime| + + .. |runtime| replace:: 7__ + __ runtime.html + + __ reference/__main.html + + Change the references.Substitutions tranform's priority from 220 to + 680, so it happens after reference resolution? Then we have to deal + with multiple IDs. Perhaps the Substitution transform should remove + all IDs from definitions after the first substitution reference is + processed. + General ------- diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f4b96608d..f72f8f140 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -2302,6 +2302,10 @@ setting has been supplied:: ``generated`` ============= +Docutils wraps ``generated`` elements around text that is inserted +(generated) by Docutils; i.e., text that was not in the document, like +section numbers inserted by the "sectnum" directive. + `To be completed`_. -- cgit v1.2.1 From c8f41b54f589f441a15e6a1a22d6b0675eab1778 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 9 May 2004 15:49:30 +0000 Subject: Fix typos and add remark on pslatex bold typewriter font. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2064 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index f72b26015..112bc2bc3 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -105,14 +105,15 @@ Font selection When generating pdf-files from LaTeX, use the pdflatex command, the files are a lot smaller if postscript fonts are used. To do so put -``\usepackage{times}`` into the styleshee +``\usepackage{times}`` into the stylesheet. It is said that the typewriter font in computer modern font, the default LaTeX font package, is too heavy compared to the others. There is a package or some commands too fix this, which i currently cannot find. Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ```\usepackage{pslatex}``. +package to fix this is ``\usepackage{pslatex}``. +pslatex in contrast to the standard LaTeX fonts has a bold typewriter font. Table of figures ---------------- -- cgit v1.2.1 From 8e1ef586e288f75636ee061e1480eab77129ba84 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 10 May 2004 21:26:20 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2079 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index d936147b0..c156b0b33 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -248,7 +248,7 @@ __ quickref.html#section-structure To break longer text up into sections, you use **section headers**. These are a single line of text (one or more words) with adornment: an -underline alone, or an overline and an overline together, in dashes +underline alone, or an underline and an overline together, in dashes "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you feel comfortable with. An underline-only adornment is distinct from -- cgit v1.2.1 From 916a35a5389008156c49bc15a666d9aad2db9f02 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 11 May 2004 21:13:45 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2083 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index f53d6048b..0906fa930 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -2257,6 +2257,14 @@ Should the lines themselves be ``<span>`` or ``<div>``? I don't like mixing inline and block-level elements. +Implementation Plan +------------------- + +We'll leave the old implementation in place (via the "line-block" +directive only) until all Writers have been updated to support the new +syntax & implementation. + + Reworking Explicit Markup (Round 2) =================================== -- cgit v1.2.1 From 7368e7764782c50cbb58122dfa2ea59313393900 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 12 May 2004 19:22:58 +0000 Subject: Add option --table-style=(standard|booktabs|nolines). Move most table handling into class Table. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2085 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 112bc2bc3..9d7ca4f8d 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -237,6 +237,7 @@ Tables maybe use ltxtable instead of tabularx (Longtable combined with tabularx). but ltxtable disables longtable's multicolumn. * Table cells with multirow and multicolumn +* table-style booktabs: booktabs.sty 1.00 does not work with longtable. Miscellaneous ------------- @@ -244,8 +245,9 @@ Miscellaneous * The underscore ``_`` does not work in literal-blocks, has different width. I tried - - Escape it ``{\_}`` to narrow - Underline a blank ``\underline{ }`` to low, as in windows-xp. + And elsewhere use this. + - Escape it ``{\_}`` to narrow - Subscript a hyphen ``$_{\tt-}$`` too wide and thin - ``$_{-}$`` the same. @@ -284,7 +286,7 @@ Miscellaneous * For additional docinfo items: the field_body is inserted as text, i.e. no markup is done. * Multiple author entries in docinfo (same thing as in html). -* pslatex has not textbackslash ind bold ? +* pslatex has not textbackslash in bold ? * make use (but test against pslatex) :: \textbackslash \backslash \ -- cgit v1.2.1 From 64df5d1a68561bf8e162a2d1f09f8c41b6c3bc79 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 12 May 2004 19:35:52 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2087 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index eb79a9e6e..7d42a87e2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -77,11 +77,11 @@ __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 * Another bug from David Abrahams (run with ``rst2html.py --traceback``):: - .. [#crtp] See |runtime| + .. [#crtp] See |runtime| foo [#tag_dispatching]_ - .. [#tag_dispatching] See |runtime| + .. [#tag_dispatching] See |runtime| .. |runtime| replace:: 7__ __ runtime.html @@ -904,6 +904,12 @@ __ rst/alternatives.html#or-not-to-do (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. + Directives `````````` @@ -1432,7 +1438,7 @@ elements. * 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-riference (& synonyms). + target, uri-reference (& synonyms). * Add directives for each role as well? This would allow indirect nested markup:: -- cgit v1.2.1 From 8c9ebc0f72e684a55b46f71b17daca2652244c2a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 13 May 2004 00:00:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 3e225dfbe..dba5475cc 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -205,8 +205,7 @@ _`error_encoding` _`error_encoding_error_handler` The encoding error handler for unencodable characters in error - output. Acceptable values are the same as for the "error" - parameter of Python's ``encode`` string method. + output. See output_encoding_error_handler_ for acceptable values. Default: "backslashreplace" for Python 2.3 and later; "replace" otherwise. Options: ``--error-encoding-error-handler, @@ -267,8 +266,25 @@ _`output_encoding` _`output_encoding_error_handler` The encoding error handler for unencodable characters in output. + Acceptable values include: + + strict + Raise an exception in case of an encoding error. + replace + Replace malformed data with a suitable replacement marker, + such as "?". + ignore + Ignore malformed data and continue without further notice. + xmlcharrefreplace + (Python 2.3+) Replace with the appropriate XML character + reference, such as "``†``". + backslashreplace + (Python 2.3+) Replace with backslashed escape sequences, such + as "``\u2020``". + Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method. + Python's ``encode`` string method; other values may be defined in + applications or in future versions of Python. Default: "strict". Options: ``--output-encoding-error-handler, --output-encoding, -o``. -- cgit v1.2.1 From e63e9e1f758249afebcf545af3e4d73c208e8d29 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 13 May 2004 00:09:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2093 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index dba5475cc..bc93350e4 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -204,8 +204,8 @@ _`error_encoding` Default: "ascii". Options: ``--error-encoding, -e``. _`error_encoding_error_handler` - The encoding error handler for unencodable characters in error - output. See output_encoding_error_handler_ for acceptable values. + The error handler for unencodable characters in error output. See + output_encoding_error_handler_ for acceptable values. Default: "backslashreplace" for Python 2.3 and later; "replace" otherwise. Options: ``--error-encoding-error-handler, @@ -265,7 +265,7 @@ _`output_encoding` Default: "UTF-8". Options: ``--output-encoding, -o``. _`output_encoding_error_handler` - The encoding error handler for unencodable characters in output. + The error handler for unencodable characters in the output. Acceptable values include: strict -- cgit v1.2.1 From 746d5bbb99e3b17e745c17787930012cef382333 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 13 May 2004 03:28:15 +0000 Subject: Document table_style. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2094 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index bc93350e4..150978728 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -670,6 +670,13 @@ _`section_enumerator_separator` Default: "-". Option: ``--section-enumerator-separator``. +table_style + Specify the drawing of separation lines. + + - "standard" lines around and between cells. + - "booktabs" a line above and below the table and one after the + head. + - "nolines". [pseudoxml writer] `````````````````` -- cgit v1.2.1 From 8c35b5542cccd17f1f6df892cfd71d42d0b95614 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 14 May 2004 03:22:07 +0000 Subject: organized topics into a cohesive structure git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2096 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 2956 +++++++++++++++++++++-------------------- 1 file changed, 1486 insertions(+), 1470 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 0906fa930..7e60cc025 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -23,1114 +23,1212 @@ for full details of the established syntax. .. contents:: +------------- + Implemented +------------- -... Or Not To Do? -================= +Field Lists +=========== -This is the realm of the possible but questionably probable. These -ideas are kept here as a record of what has been proposed, for -posterity and in case any of them prove to be useful. +Prior to the syntax for field lists being finalized, several +alternatives were proposed. +1. Unadorned RFC822_ everywhere:: -Compound Enumerated Lists -------------------------- + Author: Me + Version: 1 -Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to -allow for nested enumerated lists without indentation? + Advantages: clean, precedent (RFC822-compliant). Disadvantage: + ambiguous (these paragraphs are a prime example). + Conclusion: rejected. -Sloppy Indentation of List Items --------------------------------- +2. Special case: use unadorned RFC822_ for the very first or very last + text block of a document:: -Perhaps the indentation shouldn't be so strict. Currently, this is -required:: + """ + Author: Me + Version: 1 - 1. First line, - second line. + The rest of the document... + """ -Anything wrong with this? :: + Advantages: clean, precedent (RFC822-compliant). Disadvantages: + special case, flat (unnested) field lists only, still ambiguous:: - 1. First line, - second line. + """ + Usage: cmdname [options] arg1 arg2 ... -Problem? :: + We obviously *don't* want the like above to be interpreted as a + field list item. Or do we? + """ - 1. First para. + Conclusion: rejected for the general case, accepted for specific + contexts (PEPs, email). - Block quote. (no good: requires some indent relative to first - para) +3. Use a directive:: - Second Para. + .. fields:: - 2. Have to carefully define where the literal block ends:: + Author: Me + Version: 1 - Literal block + Advantages: explicit and unambiguous, RFC822-compliant. + Disadvantage: cumbersome. - Literal block? + Conclusion: rejected for the general case (but such a directive + could certainly be written). -Hmm... Non-strict indentation isn't such a good idea. +4. Use Javadoc-style:: + @Author: Me + @Version: 1 + @param a: integer -Lazy Indentation of List Items ------------------------------- + Advantages: unambiguous, precedent, flexible. Disadvantages: + non-intuitive, ugly, not RFC822-compliant. -Another approach: Going back to the first draft of reStructuredText -(2000-11-27 post to Doc-SIG):: + Conclusion: rejected. - - This is the fourth item of the main list (no blank line above). - The second line of this item is not indented relative to the - bullet, which precludes it from having a second paragraph. +5. Use leading colons:: -Change that to *require* a blank line above and below, to reduce -ambiguity. This "loosening" may be added later, once the parser's -been nailed down. However, a serious drawback of this approach is to -limit the content of each list item to a single paragraph. + :Author: Me + :Version: 1 + Advantages: unambiguous, obvious (*almost* RFC822-compliant), + flexible, perhaps even elegant. Disadvantages: no precedent, not + quite RFC822-compliant. -David's Idea for Lazy Indentation -````````````````````````````````` + Conclusion: accepted! -Consider a paragraph in a word processor. It is a single logical line -of text which ends with a newline, soft-wrapped arbitrarily at the -right edge of the page or screen. We can think of a plaintext -paragraph in the same way, as a single logical line of text, ending -with two newlines (a blank line) instead of one, and which may contain -arbitrary line breaks (newlines) where it was accidentally -hard-wrapped by an application. We can compensate for the accidental -hard-wrapping by "unwrapping" every unindented second and subsequent -line. The indentation of the first line of a paragraph or list item -would determine the indentation for the entire element. Blank lines -would be required between list items when using lazy indentation. +6. Use double colons:: -The following example shows the lazy indentation of multiple body -elements:: + Author:: Me + Version:: 1 - - This is the first paragraph - of the first list item. + Advantages: unambiguous, obvious? (*almost* RFC822-compliant), + flexible, similar to syntax already used for literal blocks and + directives. Disadvantages: no precedent, not quite + RFC822-compliant, similar to syntax already used for literal blocks + and directives. - Here is the second paragraph - of the first list item. + Conclusion: rejected because of the syntax similarity & conflicts. - - This is the first paragraph - of the second list item. +Why is RFC822 compliance important? It's a universal Internet +standard, and super obvious. Also, I'd like to support the PEP format +(ulterior motive: get PEPs to use reStructuredText as their standard). +But it *would* be easy to get used to an alternative (easy even to +convert PEPs; probably harder to convert python-deviants ;-). - Here is the second paragraph - of the second list item. +Unfortunately, without well-defined context (such as in email headers: +RFC822 only applies before any blank lines), the RFC822 format is +ambiguous. It is very common in ordinary text. To implement field +lists unambiguously, we need explicit syntax. -A more complex example shows the limitations of lazy indentation:: +The following question was posed in a footnote: - - This is the first paragraph - of the first list item. + Should "bibliographic field lists" be defined at the parser level, + or at the DPS transformation level? In other words, are they + reStructuredText-specific, or would they also be applicable to + another (many/every other?) syntax? - Next is a definition list item: +The answer is that bibliographic fields are a +reStructuredText-specific markup convention. Other syntaxes may +implement the bibliographic elements explicitly. For example, there +would be no need for such a transformation for an XML-based markup +syntax. - Term - Definition. The indentation of the term is - required, as is the indentation of the definition's - first line. +.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt - When the definition extends to more than - one line, lazy indentation may occur. (This is the second - paragraph of the definition.) - - This is the first paragraph - of the second list item. +Interpreted Text "Roles" +======================== - - Here is the first paragraph of - the first item of a nested list. +The original purpose of interpreted text was as a mechanism for +descriptive markup, to describe the nature or role of a word or +phrase. For example, in XML we could say "<function>len</function>" +to mark up "len" as a function. It is envisaged that within Python +docstrings (inline documentation in Python module source files, the +primary market for reStructuredText) the role of a piece of +interpreted text can be inferred implicitly from the context of the +docstring within the program source. For other applications, however, +the role may have to be indicated explicitly. - So this paragraph would be outside of the nested list, - but inside the second list item of the outer list. +Interpreted text is enclosed in single backquotes (`). - But this paragraph is not part of the list at all. +1. Initially, it was proposed that an explicit role could be indicated + as a word or phrase within the enclosing backquotes: -And the ambiguity remains:: + - As a prefix, separated by a colon and whitespace:: - - Look at the hyphen at the beginning of the next line - - is it a second list item marker, or a dash in the text? + `role: interpreted text` - Similarly, we may want to refer to numbers inside enumerated - lists: + - As a suffix, separated by whitespace and a colon:: - 1. How many socks in a pair? There are - 2. How many pants in a pair? Exactly - 1. Go figure. + `interpreted text :role` -Literal blocks and block quotes would still require consistent -indentation for all their lines. For block quotes, we might be able -to get away with only requiring that the first line of each contained -element be indented. For example:: + There are problems with the initial approach: - Here's a paragraph. + - There could be ambiguity with interpreted text containing colons. + For example, an index entry of "Mission: Impossible" would + require a backslash-escaped colon. - This is a paragraph inside a block quote. - Second and subsequent lines need not be indented at all. + - The explicit role is descriptive markup, not content, and will + not be visible in the processed output. Putting it inside the + backquotes doesn't feel right; the *role* isn't being quoted. - - A bullet list inside - the block quote. +2. Tony Ibbs suggested that the role be placed outside the + backquotes:: - Second paragraph of the - bullet list inside the block quote. + role:`prefix` or `suffix`:role -Although feasible, this form of lazy indentation has problems. The -document structure and hierarchy is not obvious from the indentation, -making the source plaintext difficult to read. This will also make -keeping track of the indentation while writing difficult and -error-prone. However, these problems may be acceptable for Wikis and -email mode, where we may be able to rely on less complex structure -(few nested lists, for example). + This removes the embedded-colons ambiguity, but limits the role + identifier to be a single word (whitespace would be illegal). + Since roles are not meant to be visible after processing, the lack + of whitespace support is not important. + The suggested syntax remains ambiguous with respect to ratios and + some writing styles. For example, suppose there is a "signal" + identifier, and we write:: -Multiple Roles in Interpreted Text ----------------------------------- + ...calculate the `signal`:noise ratio. -In reStructuredText, inline markup cannot be nested (yet; `see -below`__). This also applies to interpreted text. In order to -simultaneously combine multiple roles for a single piece of text, a -syntax extension would be necessary. Ideas: + "noise" looks like a role. -1. Initial idea:: +3. As an improvement on #2, we can bracket the role with colons:: - `interpreted text`:role1,role2: + :role:`prefix` or `suffix`:role: -2. Suggested by Jason Diamond:: + This syntax is similar to that of field lists, which is fine since + both are doing similar things: describing. - `interpreted text`:role1:role2: + This is the syntax chosen for reStructuredText. -If a document is so complex as to require nested inline markup, -perhaps another markup system should be considered. By design, -reStructuredText does not have the flexibility of XML. +4. Another alternative is two colons instead of one:: -__ `Nested Inline Markup`_ + role::`prefix` or `suffix`::role + But this is used for analogies ("A:B::C:D": "A is to B as C is to + D"). -Parameterized Interpreted Text ------------------------------- + Both alternative #2 and #4 lack delimiters on both sides of the + role, making it difficult to parse (by the reader). -In some cases it may be expedient to pass parameters to interpreted -text, analogous to function calls. Ideas: +5. Some kind of bracketing could be used: -1. Parameterize the interpreted text role itself (suggested by Jason - Diamond):: + - Parentheses:: - `interpreted text`:role1(foo=bar): + (role)`prefix` or `suffix`(role) - Positional parameters could also be supported:: + - Braces:: - `CSS`:acronym(Cascading Style Sheets): is used for HTML, and - `CSS`:acronym(Content Scrambling System): is used for DVDs. + {role}`prefix` or `suffix`{role} - Technical problem: current interpreted text syntax does not - recognize roles containing whitespace. Design problem: this smells - like programming language syntax, but reStructuredText is not a - programming language. + - Square brackets:: -2. Put the parameters inside the interpreted text:: + [role]`prefix` or `suffix`[role] - `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and - `CSS (Content Scrambling System)`:acronym: is used for DVDs. + - Angle brackets:: - Although this could be defined on an individual basis (per role), - we ought to have a standard. Hyperlinks with embedded URIs already - use angle brackets; perhaps they could be used here too:: + <role>`prefix` or `suffix`<role> - `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and - `CSS <Content Scrambling System>`:acronym: is used for DVDs. + (The overlap of \*ML tags with angle brackets would be too + confusing and precludes their use.) - Do angle brackets connote URLs too much for this to be acceptable? - How about the "tag" connotation -- does it save them or doom them? +Syntax #3 was chosen for reStructuredText. -Does this push inline markup too far? Readability becomes a serious -issue. Substitutions may provide a better alternative (at the expense -of verbosity and duplication) by pulling the details out of the text -flow:: - |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. +Comments +======== - .. |CSS| acronym:: Cascading Style Sheets - .. |CSS-DVD| acronym:: Content Scrambling System - :text: CSS +A problem with comments (actually, with all indented constructs) is +that they cannot be followed by an indented block -- a block quote -- +without swallowing it up. ----------------------------------------------------------------------- +I thought that perhaps comments should be one-liners only. But would +this mean that footnotes, hyperlink targets, and directives must then +also be one-liners? Not a good solution. -This whole idea may be going beyond the scope of reStructuredText. -Documents requiring this functionality may be better off using XML or -another markup system. +Tony Ibbs suggested a "comment" directive. I added that we could +limit a comment to a single text block, and that a "multi-block +comment" could use "comment-start" and "comment-end" directives. This +would remove the indentation incompatibility. A "comment" directive +automatically suggests "footnote" and (hyperlink) "target" directives +as well. This could go on forever! Bad choice. -This argument comes up regularly when pushing the envelope of -reStructuredText syntax. I think it's a useful argument in that it -provides a check on creeping featurism. In many cases, the resulting -verbosity produces such unreadable plaintext that there's a natural -desire *not* to use it unless absolutely necessary. It's a matter of -finding the right balance. +Garth Kidd suggested that an "empty comment", a ".." explicit markup +start with nothing on the first line (except possibly whitespace) and +a blank line immediately following, could serve as an "unindent". An +empty comment does **not** swallow up indented blocks following it, +so block quotes are safe. "A tiny but practical wart." Accepted. -Syntax for Interpreted Text Role Bindings ------------------------------------------ +Anonymous Hyperlinks +==================== -The following syntax (idea from Jeffrey C. Jacobs) could be used to -associate directives with roles:: +Alan Jaffray came up with this idea, along with the following syntax:: - .. :rewrite: class:: rewrite + Search the `Python DOC-SIG mailing list archives`{}_. - `She wore ribbons in her hair and it lay with streaks of - grey`:rewrite: + .. _: http://mail.python.org/pipermail/doc-sig/ -The syntax is similar to that of substitution declarations, and the -directive/role association may resolve implementation issues. The -semantics, ramifications, and implementation details would need to be -worked out. +The idea is sound and useful. I suggested a "double underscore" +syntax:: -The example above would implement the "rewrite" role as adding a -``class="rewrite"`` attribute to the interpreted text ("inline" -element). The stylesheet would then pick up on the "class" attribute -to do the actual formatting. + Search the `Python DOC-SIG mailing list archives`__. -The advantage of the new syntax would be flexibility. Uses other than -"class" may present themselves. The disadvantage is complexity: -having to implement new syntax for a relatively specialized operation, -and having new semantics in existing directives ("class::" would do -something different). + .. __: http://mail.python.org/pipermail/doc-sig/ -The `"role" directive`__ has been implemented. +But perhaps single underscores are okay? The syntax looks better, but +the hyperlink itself doesn't explicitly say "anonymous":: -__ http://docutils.sf.net/spec/rst/directives.html#role + Search the `Python DOC-SIG mailing list archives`_. + .. _: http://mail.python.org/pipermail/doc-sig/ -Character Processing --------------------- +Mixing anonymous and named hyperlinks becomes confusing. The order of +targets is not significant for named hyperlinks, but it is for +anonymous hyperlinks:: -Several people have suggested adding some form of character processing -to reStructuredText: + Hyperlinks: anonymous_, named_, and another anonymous_. -* Some sort of automated replacement of ASCII sequences: + .. _named: named + .. _: anonymous1 + .. _: anonymous2 - - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). - - Convert quotes to curly quote entities. (Essentially impossible - for HTML? Unnecessary for TeX.) - - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to  . Problem with line-wrapping though: it could - end up escaping the newline. - - Escaped newlines to <BR>. - - Escaped period or quote or dash as a disappearing catalyst to - allow character-level inline markup? +Without the extra syntax of double underscores, determining which +hyperlink references are anonymous may be difficult. We'd have to +check which references don't have corresponding targets, and match +those up with anonymous targets. Keeping to a simple consistent +ordering (as with auto-numbered footnotes) seems simplest. -* XML-style character entities, such as "©" for the copyright - symbol. +reStructuredText will use the explicit double-underscore syntax for +anonymous hyperlinks. An alternative (see `Reworking Explicit Markup +(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__":: -Docutils has no need of a character entity subsystem. Supporting -Unicode and text encodings, character entities should be directly -represented in the text: a copyright symbol should be represented by -the copyright symbol character. If this is not possible in an -authoring environment, a pre-processing stage can be added, or a table -of substitution definitions can be devised. + An anonymous__ reference. -A "unicode" directive has been implemented to allow direct -specification of esoteric characters. In combination with the -substitution construct, "include" files defining common sets of -character entities can be defined and used. `A set of character -entity set definition files have been defined`__ (`tarball`__). -There's also `a description and instructions for use`__. + __ http://anonymous -__ http://docutils.sf.net/tmp/charents/ -__ http://docutils.sf.net/tmp/charents.tgz -__ http://docutils.sf.net/tmp/charents/README.html -To allow for `character-level inline markup`_, a limited form of -character processing has been added to the spec and parser: escaped -whitespace characters are removed from the processed document. Any -further character processing will be of this functional type, rather -than of the character-encoding type. +Reworking Explicit Markup (Round 1) +=================================== -.. _character-level inline markup: - reStructuredText.html#character-level-inline-markup +Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added +to reStructuredText. Subsequently it was asserted that hyperlinks +(especially anonymous hyperlinks) would play an increasingly important +role in reStructuredText documents, and therefore they require a +simpler and more concise syntax. This prompted a review of the +current and proposed explicit markup syntaxes with regards to +improving usability. -* Directive idea:: +1. Original syntax:: - .. text-replace:: "pattern" "replacement" + .. _blah: internal hyperlink target + .. _blah: http://somewhere external hyperlink target + .. _blah: blahblah_ indirect hyperlink target + .. __: anonymous internal target + .. __: http://somewhere anonymous external target + .. __: blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment - - Support Unicode "U+XXXX" codes. - - Support regexps, perhaps with alternative "regexp-replace" - directive. - - Flags for regexps; ":flags:" option, or individuals. - - Specifically, should the default be case-sensistive or - -insensitive? + .. Note:: + The comment text was intentionally made to look like a hyperlink + target. -Field Lists -=========== + Origins: -Prior to the syntax for field lists being finalized, several -alternatives were proposed. + * Except for the colon (a delimiter necessary to allow for + phrase-links), hyperlink target ``.. _blah:`` comes from Setext. + * Comment syntax from Setext. + * Footnote syntax from StructuredText ("named links"). + * Directives and anonymous hyperlinks original to reStructuredText. -1. Unadorned RFC822_ everywhere:: + Advantages: - Author: Me - Version: 1 + + Consistent explicit markup indicator: "..". + + Consistent hyperlink syntax: ".. _" & ":". - Advantages: clean, precedent (RFC822-compliant). Disadvantage: - ambiguous (these paragraphs are a prime example). + Disadvantages: - Conclusion: rejected. + - Anonymous target markup is awkward: ".. __:". + - The explicit markup indicator ("..") is excessively overloaded? + - Comment text is limited (can't look like a footnote, hyperlink, + or directive). But this is probably not important. -2. Special case: use unadorned RFC822_ for the very first or very last - text block of a document:: +2. Alan Jaffray's proposed syntax #1:: - """ - Author: Me - Version: 1 + __ _blah internal hyperlink target + __ blah: http://somewhere external hyperlink target + __ blah: blahblah_ indirect hyperlink target + __ anonymous internal target + __ http://somewhere anonymous external target + __ blahblah_ anonymous indirect target + __ [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment - The rest of the document... - """ + The hyperlink-connoted underscores have become first-level syntax. - Advantages: clean, precedent (RFC822-compliant). Disadvantages: - special case, flat (unnested) field lists only, still ambiguous:: + Advantages: - """ - Usage: cmdname [options] arg1 arg2 ... + + Anonymous targets are simpler. + + All hyperlink targets are one character shorter. - We obviously *don't* want the like above to be interpreted as a - field list item. Or do we? - """ + Disadvantages: - Conclusion: rejected for the general case, accepted for specific - contexts (PEPs, email). + - Inconsistent internal hyperlink targets. Unlike all other named + hyperlink targets, there's no colon. There's an extra leading + underscore, but we can't drop it because without it, "blah" looks + like a relative URI. Unless we restore the colon:: -3. Use a directive:: + __ blah: internal hyperlink target - .. fields:: + - Obtrusive markup? - Author: Me - Version: 1 +3. Alan Jaffray's proposed syntax #2:: - Advantages: explicit and unambiguous, RFC822-compliant. - Disadvantage: cumbersome. + .. _blah internal hyperlink target + .. blah: http://somewhere external hyperlink target + .. blah: blahblah_ indirect hyperlink target + .. anonymous internal target + .. http://somewhere anonymous external target + .. blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + !! blah: http://somewhere directive + ## blah: http://somewhere comment - Conclusion: rejected for the general case (but such a directive - could certainly be written). + Leading underscores have been (almost) replaced by "..", while + comments and directives have gained their own syntax. -4. Use Javadoc-style:: + Advantages: - @Author: Me - @Version: 1 - @param a: integer - - Advantages: unambiguous, precedent, flexible. Disadvantages: - non-intuitive, ugly, not RFC822-compliant. + + Anonymous hyperlinks are simpler. + + Unique syntax for comments. Connotation of "comment" from + some programming languages (including our favorite). + + Unique syntax for directives. Connotation of "action!". - Conclusion: rejected. + Disadvantages: -5. Use leading colons:: + - Inconsistent internal hyperlink targets. Again, unlike all other + named hyperlink targets, there's no colon. There's a leading + underscore, matching the trailing underscores of references, + which no other hyperlink targets have. We can't drop that one + leading underscore though: without it, "blah" looks like a + relative URI. Again, unless we restore the colon:: - :Author: Me - :Version: 1 + .. blah: internal hyperlink target - Advantages: unambiguous, obvious (*almost* RFC822-compliant), - flexible, perhaps even elegant. Disadvantages: no precedent, not - quite RFC822-compliant. + - All (except for internal) hyperlink targets lack their leading + underscores, losing the "hyperlink" connotation. - Conclusion: accepted! + - Obtrusive syntax for comments. Alternatives:: -6. Use double colons:: + ;; blah: http://somewhere + (also comment syntax in Lisp & others) + ,, blah: http://somewhere + ("comma comma": sounds like "comment"!) - Author:: Me - Version:: 1 + - Iffy syntax for directives. Alternatives? - Advantages: unambiguous, obvious? (*almost* RFC822-compliant), - flexible, similar to syntax already used for literal blocks and - directives. Disadvantages: no precedent, not quite - RFC822-compliant, similar to syntax already used for literal blocks - and directives. +4. Tony Ibbs' proposed syntax:: - Conclusion: rejected because of the syntax similarity & conflicts. + .. _blah: internal hyperlink target + .. _blah: http://somewhere external hyperlink target + .. _blah: blahblah_ indirect hyperlink target + .. anonymous internal target + .. http://somewhere anonymous external target + .. blahblah_ anonymous indirect target + .. [blah] http://somewhere footnote + .. blah:: http://somewhere directive + .. blah: http://somewhere comment -Why is RFC822 compliance important? It's a universal Internet -standard, and super obvious. Also, I'd like to support the PEP format -(ulterior motive: get PEPs to use reStructuredText as their standard). -But it *would* be easy to get used to an alternative (easy even to -convert PEPs; probably harder to convert python-deviants ;-). + This is the same as the current syntax, except for anonymous + targets which drop their "__: ". -Unfortunately, without well-defined context (such as in email headers: -RFC822 only applies before any blank lines), the RFC822 format is -ambiguous. It is very common in ordinary text. To implement field -lists unambiguously, we need explicit syntax. + Advantage: -The following question was posed in a footnote: + + Anonymous targets are simpler. - Should "bibliographic field lists" be defined at the parser level, - or at the DPS transformation level? In other words, are they - reStructuredText-specific, or would they also be applicable to - another (many/every other?) syntax? + Disadvantages: -The answer is that bibliographic fields are a -reStructuredText-specific markup convention. Other syntaxes may -implement the bibliographic elements explicitly. For example, there -would be no need for such a transformation for an XML-based markup -syntax. + - Anonymous targets lack their leading underscores, losing the + "hyperlink" connotation. + - Anonymous targets are almost indistinguishable from comments. + (Better to know "up front".) -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt +5. David Goodger's proposed syntax: Perhaps going back to one of + Alan's earlier suggestions might be the best solution. How about + simply adding "__ " as a synonym for ".. __: " in the original + syntax? These would become equivalent:: + .. __: anonymous internal target + .. __: http://somewhere anonymous external target + .. __: blahblah_ anonymous indirect target -Interpreted Text "Roles" -======================== + __ anonymous internal target + __ http://somewhere anonymous external target + __ blahblah_ anonymous indirect target -The original purpose of interpreted text was as a mechanism for -descriptive markup, to describe the nature or role of a word or -phrase. For example, in XML we could say "<function>len</function>" -to mark up "len" as a function. It is envisaged that within Python -docstrings (inline documentation in Python module source files, the -primary market for reStructuredText) the role of a piece of -interpreted text can be inferred implicitly from the context of the -docstring within the program source. For other applications, however, -the role may have to be indicated explicitly. +Alternative 5 has been adopted. -Interpreted text is enclosed in single backquotes (`). -1. Initially, it was proposed that an explicit role could be indicated - as a word or phrase within the enclosing backquotes: +Backquotes in Phrase-Links +========================== - - As a prefix, separated by a colon and whitespace:: +[From a 2001-06-05 Doc-SIG post in reply to questions from Doug +Hellmann.] - `role: interpreted text` +The first draft of the spec, posted to the Doc-SIG in November 2000, +used square brackets for phrase-links. I changed my mind because: - - As a suffix, separated by whitespace and a colon:: +1. In the first draft, I had already decided on single-backquotes for + inline literal text. - `interpreted text :role` +2. However, I wanted to minimize the necessity for backslash escapes, + for example when quoting Python repr-equivalent syntax that uses + backquotes. - There are problems with the initial approach: +3. The processing of identifiers (function/method/attribute/module + etc. names) into hyperlinks is a useful feature. PyDoc recognizes + identifiers heuristically, but it doesn't take much imagination to + come up with counter-examples where PyDoc's heuristics would result + in embarassing failure. I wanted to do it deterministically, and + that called for syntax. I called this construct "interpreted + text". - - There could be ambiguity with interpreted text containing colons. - For example, an index entry of "Mission: Impossible" would - require a backslash-escaped colon. +4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the + idea of using double-backquotes as syntax. - - The explicit role is descriptive markup, not content, and will - not be visible in the processed output. Putting it inside the - backquotes doesn't feel right; the *role* isn't being quoted. +5. I worked out some rules for inline markup recognition. -2. Tony Ibbs suggested that the role be placed outside the - backquotes:: +6. In combination with #5, double backquotes lent themselves to inline + literals, neatly satisfying #2, minimizing backslash escapes. In + fact, the spec says that no interpretation of any kind is done + within double-backquote inline literal text; backslashes do *no* + escaping within literal text. - role:`prefix` or `suffix`:role +7. Single backquotes are then freed up for interpreted text. - This removes the embedded-colons ambiguity, but limits the role - identifier to be a single word (whitespace would be illegal). - Since roles are not meant to be visible after processing, the lack - of whitespace support is not important. +8. I already had square brackets required for footnote references. - The suggested syntax remains ambiguous with respect to ratios and - some writing styles. For example, suppose there is a "signal" - identifier, and we write:: +9. Since interpreted text will typically turn into hyperlinks, it was + a natural fit to use backquotes as the phrase-quoting syntax for + trailing-underscore hyperlinks. - ...calculate the `signal`:noise ratio. +The original inspiration for the trailing underscore hyperlink syntax +was Setext. But for phrases Setext used a very cumbersome +``underscores_between_words_like_this_`` syntax. - "noise" looks like a role. +The underscores can be viewed as if they were right-pointing arrows: +``-->``. So ``hyperlink_`` points away from the reference, and +``.. _hyperlink:`` points toward the target. -3. As an improvement on #2, we can bracket the role with colons:: - :role:`prefix` or `suffix`:role: +Substitution Mechanism +====================== - This syntax is similar to that of field lists, which is fine since - both are doing similar things: describing. +Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by +Alan Jaffray, "reStructuredText inline markup". It reminded me of a +missing piece of the reStructuredText puzzle, first referred to in my +contribution to "Documentation markup & processing / PEPs" (Doc-SIG +2001-06-21). - This is the syntax chosen for reStructuredText. +Substitutions allow the power and flexibility of directives to be +shared by inline text. They are a way to allow arbitrarily complex +inline objects, while keeping the details out of the flow of text. +They are the equivalent of SGML/XML's named entities. For example, an +inline image (using reference syntax alternative 4d (vertical bars) +and definition alternative 3, the alternatives chosen for inclusion in +the spec):: -4. Another alternative is two colons instead of one:: + The |biohazard| symbol must be used on containers used to dispose + of medical waste. - role::`prefix` or `suffix`::role + .. |biohazard| image:: biohazard.png + [height=20 width=20] - But this is used for analogies ("A:B::C:D": "A is to B as C is to - D"). +The ``|biohazard|`` substitution reference will be replaced in-line by +whatever the ``.. |biohazard|`` substitution definition generates (in +this case, an image). A substitution definition contains the +substitution text bracketed with vertical bars, followed by a an +embedded inline-compatible directive, such as "image". A transform is +required to complete the substitution. - Both alternative #2 and #4 lack delimiters on both sides of the - role, making it difficult to parse (by the reader). +Syntax alternatives for the reference: -5. Some kind of bracketing could be used: +1. Use the existing interpreted text syntax, with a predefined role + such as "sub":: - - Parentheses:: + The `biohazard`:sub: symbol... - (role)`prefix` or `suffix`(role) + Advantages: existing syntax, explicit. Disadvantages: verbose, + obtrusive. - - Braces:: +2. Use a variant of the interpreted text syntax, with a new suffix + akin to the underscore in phrase-link references:: - {role}`prefix` or `suffix`{role} + (a) `name`@ + (b) `name`# + (c) `name`& + (d) `name`/ + (e) `name`< + (f) `name`:: + (g) `name`: - - Square brackets:: - [role]`prefix` or `suffix`[role] + Due to incompatibility with other constructs and ordinary text + usage, (f) and (g) are not possible. - - Angle brackets:: +3. Use interpreted text syntax with a fixed internal format:: - <role>`prefix` or `suffix`<role> + (a) `:name:` + (b) `name:` + (c) `name::` + (d) `::name::` + (e) `%name%` + (f) `#name#` + (g) `/name/` + (h) `&name&` + (i) `|name|` + (j) `[name]` + (k) `<name>` + (l) `&name;` + (m) `'name'` - (The overlap of \*ML tags with angle brackets would be too - confusing and precludes their use.) + To avoid ML confusion (k) and (l) are definitely out. Square + brackets (j) won't work in the target (the substitution definition + would be indistinguishable from a footnote). -Syntax #3 was chosen for reStructuredText. + The ```/name/``` syntax (g) is reminiscent of "s/find/sub" + substitution syntax in ed-like languages. However, it may have a + misleading association with regexps, and looks like an absolute + POSIX path. (i) is visually equivalent and lacking the + connotations. + A disadvantage of all of these is that they limit interpreted text, + albeit only slightly. -Comments -======== +4. Use specialized syntax, something new:: -A problem with comments (actually, with all indented constructs) is -that they cannot be followed by an indented block -- a block quote -- -without swallowing it up. + (a) #name# + (b) @name@ + (c) /name/ + (d) |name| + (e) <<name>> + (f) //name// + (g) ||name|| + (h) ^name^ + (i) [[name]] + (j) ~name~ + (k) !name! + (l) =name= + (m) ?name? + (n) >name< -I thought that perhaps comments should be one-liners only. But would -this mean that footnotes, hyperlink targets, and directives must then -also be one-liners? Not a good solution. + "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes + looks just like a POSIX path; it is likely for such usage to appear + in text. -Tony Ibbs suggested a "comment" directive. I added that we could -limit a comment to a single text block, and that a "multi-block -comment" could use "comment-start" and "comment-end" directives. This -would remove the indentation incompatibility. A "comment" directive -automatically suggests "footnote" and (hyperlink) "target" directives -as well. This could go on forever! Bad choice. + "|" (d) and "^" (h) are feasible. -Garth Kidd suggested that an "empty comment", a ".." explicit markup -start with nothing on the first line (except possibly whitespace) and -a blank line immediately following, could serve as an "unindent". An -empty comment does **not** swallow up indented blocks following it, -so block quotes are safe. "A tiny but practical wart." Accepted. +5. Redefine the trailing underscore syntax. See definition syntax + alternative 4, below. +Syntax alternatives for the definition: -Anonymous Hyperlinks -==================== +1. Use the existing directive syntax, with a predefined directive such + as "sub". It contains a further embedded directive resolving to an + inline-compatible object:: -Alan Jaffray came up with this idea, along with the following syntax:: + .. sub:: biohazard + .. image:: biohazard.png + [height=20 width=20] - Search the `Python DOC-SIG mailing list archives`{}_. + .. sub:: parrot + That bird wouldn't *voom* if you put 10,000,000 volts + through it! - .. _: http://mail.python.org/pipermail/doc-sig/ + The advantages and disadvantages are the same as in inline + alternative 1. -The idea is sound and useful. I suggested a "double underscore" -syntax:: +2. Use syntax as in #1, but with an embedded directivecompressed:: - Search the `Python DOC-SIG mailing list archives`__. + .. sub:: biohazard image:: biohazard.png + [height=20 width=20] - .. __: http://mail.python.org/pipermail/doc-sig/ + This is a bit better than alternative 1, but still too much. -But perhaps single underscores are okay? The syntax looks better, but -the hyperlink itself doesn't explicitly say "anonymous":: +3. Use a variant of directive syntax, incorporating the substitution + text, obviating the need for a special "sub" directive name. If we + assume reference alternative 4d (vertical bars), the matching + definition would look like this:: - Search the `Python DOC-SIG mailing list archives`_. + .. |biohazard| image:: biohazard.png + [height=20 width=20] - .. _: http://mail.python.org/pipermail/doc-sig/ +4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) -Mixing anonymous and named hyperlinks becomes confusing. The order of -targets is not significant for named hyperlinks, but it is for -anonymous hyperlinks:: + Instead of adding new syntax, redefine the trailing underscore + syntax to mean "substitution reference" instead of "hyperlink + reference". Alan's example:: - Hyperlinks: anonymous_, named_, and another anonymous_. + I had lunch with Jonathan_ today. We talked about Zope_. - .. _named: named - .. _: anonymous1 - .. _: anonymous2 + .. _Jonathan: lj [user=jhl] + .. _Zope: http://www.zope.org/ -Without the extra syntax of double underscores, determining which -hyperlink references are anonymous may be difficult. We'd have to -check which references don't have corresponding targets, and match -those up with anonymous targets. Keeping to a simple consistent -ordering (as with auto-numbered footnotes) seems simplest. + A problem with the proposed syntax is that URIs which look like + simple reference names (alphanum plus ".", "-", "_") would be + indistinguishable from substitution directive names. A more + consistent syntax would be:: -reStructuredText will use the explicit double-underscore syntax for -anonymous hyperlinks. An alternative (see `Reworking Explicit Markup -(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__":: + I had lunch with Jonathan_ today. We talked about Zope_. - An anonymous__ reference. + .. _Jonathan: lj:: user=jhl + .. _Zope: http://www.zope.org/ - __ http://anonymous + (``::`` after ``.. _Jonathan: lj``.) + The "Zope" target is a simple external hyperlink, but the + "Jonathan" target contains a directive. Alan proposed is that the + reference text be replaced by whatever the referenced directive + (the "directive target") produces. A directive reference becomes a + hyperlink reference if the contents of the directive target resolve + to a hyperlink. If the directive target resolves to an icon, the + reference is replaced by an inline icon. If the directive target + resolves to a hyperlink, the directive reference becomes a + hyperlink reference. -Reworking Explicit Markup (Round 1) -=================================== + This seems too indirect and complicated for easy comprehension. -Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added -to reStructuredText. Subsequently it was asserted that hyperlinks -(especially anonymous hyperlinks) would play an increasingly important -role in reStructuredText documents, and therefore they require a -simpler and more concise syntax. This prompted a review of the -current and proposed explicit markup syntaxes with regards to -improving usability. + The reference in the text will sometimes become a link, sometimes + not. Sometimes the reference text will remain, sometimes not. We + don't know *at the reference*:: -1. Original syntax:: + This is a `hyperlink reference`_; its text will remain. + This is an `inline icon`_; its text will disappear. - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment + That's a problem. - .. Note:: +The syntax that has been incorporated into the spec and parser is +reference alternative 4d with definition alternative 3:: - The comment text was intentionally made to look like a hyperlink - target. + The |biohazard| symbol... - Origins: + .. |biohazard| image:: biohazard.png + [height=20 width=20] - * Except for the colon (a delimiter necessary to allow for - phrase-links), hyperlink target ``.. _blah:`` comes from Setext. - * Comment syntax from Setext. - * Footnote syntax from StructuredText ("named links"). - * Directives and anonymous hyperlinks original to reStructuredText. +We can also combine substitution references with hyperlink references, +by appending a "_" (named hyperlink reference) or "__" (anonymous +hyperlink reference) suffix to the substitution reference. This +allows us to click on an image-link:: - Advantages: + The |biohazard|_ symbol... - + Consistent explicit markup indicator: "..". - + Consistent hyperlink syntax: ".. _" & ":". + .. |biohazard| image:: biohazard.png + [height=20 width=20] + .. _biohazard: http://www.cdc.gov/ - Disadvantages: +There have been several suggestions for the naming of these +constructs, originally called "substitution references" and +"substitutions". - - Anonymous target markup is awkward: ".. __:". - - The explicit markup indicator ("..") is excessively overloaded? - - Comment text is limited (can't look like a footnote, hyperlink, - or directive). But this is probably not important. +1. Candidate names for the reference construct: -2. Alan Jaffray's proposed syntax #1:: + (a) substitution reference + (b) tagging reference + (c) inline directive reference + (d) directive reference + (e) indirect inline directive reference + (f) inline directive placeholder + (g) inline directive insertion reference + (h) directive insertion reference + (i) insertion reference + (j) directive macro reference + (k) macro reference + (l) substitution directive reference - __ _blah internal hyperlink target - __ blah: http://somewhere external hyperlink target - __ blah: blahblah_ indirect hyperlink target - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - __ [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment +2. Candidate names for the definition construct: - The hyperlink-connoted underscores have become first-level syntax. + (a) substitution + (b) substitution directive + (c) tag + (d) tagged directive + (e) directive target + (f) inline directive + (g) inline directive definition + (h) referenced directive + (i) indirect directive + (j) indirect directive definition + (k) directive definition + (l) indirect inline directive + (m) named directive definition + (n) inline directive insertion definition + (o) directive insertion definition + (p) insertion definition + (q) insertion directive + (r) substitution definition + (s) directive macro definition + (t) macro definition + (u) substitution directive definition + (v) substitution definition - Advantages: +"Inline directive reference" (1c) seems to be an appropriate term at +first, but the term "inline" is redundant in the case of the +reference. Its counterpart "inline directive definition" (2g) is +awkward, because the directive definition itself is not inline. - + Anonymous targets are simpler. - + All hyperlink targets are one character shorter. +"Directive reference" (1d) and "directive definition" (2k) are too +vague. "Directive definition" could be used to refer to any +directive, not just those used for inline substitutions. - Disadvantages: +One meaning of the term "macro" (1k, 2s, 2t) is too +programming-language-specific. Also, macros are typically simple text +substitution mechanisms: the text is substituted first and evaluated +later. reStructuredText substitution definitions are evaluated in +place at parse time and substituted afterwards. - - Inconsistent internal hyperlink targets. Unlike all other named - hyperlink targets, there's no colon. There's an extra leading - underscore, but we can't drop it because without it, "blah" looks - like a relative URI. Unless we restore the colon:: +"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that +something new is getting added rather than one construct being +replaced by another. - __ blah: internal hyperlink target +Which brings us back to "substitution". The overall best names are +"substitution reference" (1a) and "substitution definition" (2v). A +long way to go to add one word! - - Obtrusive markup? -3. Alan Jaffray's proposed syntax #2:: +Inline External Targets +======================= - .. _blah internal hyperlink target - .. blah: http://somewhere external hyperlink target - .. blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - !! blah: http://somewhere directive - ## blah: http://somewhere comment +Currently reStructuredText has two hyperlink syntax variations: - Leading underscores have been (almost) replaced by "..", while - comments and directives have gained their own syntax. +* Named hyperlinks:: - Advantages: + This is a named reference_ of one word ("reference"). Here is + a `phrase reference`_. Phrase references may even cross `line + boundaries`_. - + Anonymous hyperlinks are simpler. - + Unique syntax for comments. Connotation of "comment" from - some programming languages (including our favorite). - + Unique syntax for directives. Connotation of "action!". + .. _reference: http://www.example.org/reference/ + .. _phrase reference: http://www.example.org/phrase_reference/ + .. _line boundaries: http://www.example.org/line_boundaries/ - Disadvantages: + + Advantages: - - Inconsistent internal hyperlink targets. Again, unlike all other - named hyperlink targets, there's no colon. There's a leading - underscore, matching the trailing underscores of references, - which no other hyperlink targets have. We can't drop that one - leading underscore though: without it, "blah" looks like a - relative URI. Again, unless we restore the colon:: + - The plaintext is readable. + - Each target may be reused multiple times (e.g., just write + ``"reference_"`` again). + - No syncronized ordering of references and targets is necessary. - .. blah: internal hyperlink target + + Disadvantages: - - All (except for internal) hyperlink targets lack their leading - underscores, losing the "hyperlink" connotation. + - The reference text must be repeated as target names; could lead + to mistakes. + - The target URLs may be located far from the references, and hard + to find in the plaintext. - - Obtrusive syntax for comments. Alternatives:: +* Anonymous hyperlinks (in current reStructuredText):: - ;; blah: http://somewhere - (also comment syntax in Lisp & others) - ,, blah: http://somewhere - ("comma comma": sounds like "comment"!) + This is an anonymous reference__. Here is an anonymous + `phrase reference`__. Phrase references may even cross `line + boundaries`__. - - Iffy syntax for directives. Alternatives? + __ http://www.example.org/reference/ + __ http://www.example.org/phrase_reference/ + __ http://www.example.org/line_boundaries/ -4. Tony Ibbs' proposed syntax:: + + Advantages: - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment + - The plaintext is readable. + - The reference text does not have to be repeated. - This is the same as the current syntax, except for anonymous - targets which drop their "__: ". + + Disadvantages: - Advantage: + - References and targets must be kept in sync. + - Targets cannot be reused. + - The target URLs may be located far from the references. - + Anonymous targets are simpler. +For comparison and historical background, StructuredText also has two +syntaxes for hyperlinks: - Disadvantages: +* First, ``"reference text":URL``:: - - Anonymous targets lack their leading underscores, losing the - "hyperlink" connotation. - - Anonymous targets are almost indistinguishable from comments. - (Better to know "up front".) + This is a "reference":http://www.example.org/reference/ + of one word ("reference"). Here is a "phrase + reference":http://www.example.org/phrase_reference/. -5. David Goodger's proposed syntax: Perhaps going back to one of - Alan's earlier suggestions might be the best solution. How about - simply adding "__ " as a synonym for ".. __: " in the original - syntax? These would become equivalent:: +* Second, ``"reference text", http://example.com/absolute_URL``:: - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target + This is a "reference", http://www.example.org/reference/ + of one word ("reference"). Here is a "phrase reference", + http://www.example.org/phrase_reference/. - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target +Both syntaxes share advantages and disadvantages: -Alternative 5 has been adopted. ++ Advantages: + - The target is specified immediately adjacent to the reference. -Backquotes in Phrase-Links -========================== ++ Disadvantages: -[From a 2001-06-05 Doc-SIG post in reply to questions from Doug -Hellmann.] + - Poor plaintext readability. + - Targets cannot be reused. + - Both syntaxes use double quotes, common in ordinary text. + - In the first syntax, the URL and the last word are stuck + together, exacerbating the line wrap problem. + - The second syntax is too magical; text could easily be written + that way by accident (although only absolute URLs are recognized + here, perhaps because of the potential for ambiguity). -The first draft of the spec, posted to the Doc-SIG in November 2000, -used square brackets for phrase-links. I changed my mind because: +A new type of "inline external hyperlink" has been proposed. -1. In the first draft, I had already decided on single-backquotes for - inline literal text. +1. On 2002-06-28, Simon Budig proposed__ a new syntax for + reStructuredText hyperlinks:: -2. However, I wanted to minimize the necessity for backslash escapes, - for example when quoting Python repr-equivalent syntax that uses - backquotes. + This is a reference_(http://www.example.org/reference/) of one + word ("reference"). Here is a `phrase + reference`_(http://www.example.org/phrase_reference/). Are + these examples, (single-underscore), named? If so, `anonymous + references`__(http://www.example.org/anonymous/) using two + underscores would probably be preferable. -3. The processing of identifiers (function/method/attribute/module - etc. names) into hyperlinks is a useful feature. PyDoc recognizes - identifiers heuristically, but it doesn't take much imagination to - come up with counter-examples where PyDoc's heuristics would result - in embarassing failure. I wanted to do it deterministically, and - that called for syntax. I called this construct "interpreted - text". + __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html -4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the - idea of using double-backquotes as syntax. + The syntax, advantages, and disadvantages are similar to those of + StructuredText. -5. I worked out some rules for inline markup recognition. + + Advantages: -6. In combination with #5, double backquotes lent themselves to inline - literals, neatly satisfying #2, minimizing backslash escapes. In - fact, the spec says that no interpretation of any kind is done - within double-backquote inline literal text; backslashes do *no* - escaping within literal text. + - The target is specified immediately adjacent to the reference. -7. Single backquotes are then freed up for interpreted text. + + Disadvantages: -8. I already had square brackets required for footnote references. + - Poor plaintext readability. + - Targets cannot be reused (unless named, but the semantics are + unclear). -9. Since interpreted text will typically turn into hyperlinks, it was - a natural fit to use backquotes as the phrase-quoting syntax for - trailing-underscore hyperlinks. + + Problems: -The original inspiration for the trailing underscore hyperlink syntax -was Setext. But for phrases Setext used a very cumbersome -``underscores_between_words_like_this_`` syntax. + - The ``"`ref`_(URL)"`` syntax forces the last word of the + reference text to be joined to the URL, making a potentially + very long word that can't be wrapped (URLs can be very long). + The reference and the URL should be separate. This is a + symptom of the following point: -The underscores can be viewed as if they were right-pointing arrows: -``-->``. So ``hyperlink_`` points away from the reference, and -``.. _hyperlink:`` points toward the target. + - The syntax produces a single compound construct made up of two + equally important parts, *with syntax in the middle*, *between* + the reference and the target. This is unprecedented in + reStructuredText. + - The "inline hyperlink" text is *not* a named reference (there's + no lookup by name), so it shouldn't look like one. -Substitution Mechanism -====================== + - According to the IETF standards RFC 2396 and RFC 2732, + parentheses are legal URI characters and curly braces are legal + email characters, making their use prohibitively difficult. -Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by -Alan Jaffray, "reStructuredText inline markup". It reminded me of a -missing piece of the reStructuredText puzzle, first referred to in my -contribution to "Documentation markup & processing / PEPs" (Doc-SIG -2001-06-21). + - The named/anonymous semantics are unclear. -Substitutions allow the power and flexibility of directives to be -shared by inline text. They are a way to allow arbitrarily complex -inline objects, while keeping the details out of the flow of text. -They are the equivalent of SGML/XML's named entities. For example, an -inline image (using reference syntax alternative 4d (vertical bars) -and definition alternative 3, the alternatives chosen for inclusion in -the spec):: +2. After an analysis__ of the syntax of (1) above, we came up with the + following compromise syntax:: - The |biohazard| symbol must be used on containers used to dispose - of medical waste. + This is an anonymous reference__ + __<http://www.example.org/reference/> of one word + ("reference"). Here is a `phrase reference`__ + __<http://www.example.org/phrase_reference/>. `Named + references`_ _<http://www.example.org/anonymous/> use single + underscores. - .. |biohazard| image:: biohazard.png - [height=20 width=20] + __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html -The ``|biohazard|`` substitution reference will be replaced in-line by -whatever the ``.. |biohazard|`` substitution definition generates (in -this case, an image). A substitution definition contains the -substitution text bracketed with vertical bars, followed by a an -embedded inline-compatible directive, such as "image". A transform is -required to complete the substitution. + The syntax builds on that of the existing "inline internal + targets": ``an _`inline internal target`.`` -Syntax alternatives for the reference: + + Advantages: -1. Use the existing interpreted text syntax, with a predefined role - such as "sub":: + - The target is specified immediately adjacent to the reference, + improving maintainability: - The `biohazard`:sub: symbol... + - References and targets are easily kept in sync. + - The reference text does not have to be repeated. - Advantages: existing syntax, explicit. Disadvantages: verbose, - obtrusive. + - The construct is executed in two parts: references identical to + existing references, and targets that are new but not too big a + stretch from current syntax. -2. Use a variant of the interpreted text syntax, with a new suffix - akin to the underscore in phrase-link references:: + - There's overwhelming precedent for quoting URLs with angle + brackets [#]_. - (a) `name`@ - (b) `name`# - (c) `name`& - (d) `name`/ - (e) `name`< - (f) `name`:: - (g) `name`: + + Disadvantages: + - Poor plaintext readability. + - Lots of "line noise". + - Targets cannot be reused (unless named; see below). - Due to incompatibility with other constructs and ordinary text - usage, (f) and (g) are not possible. + To alleviate the readability issue slightly, we could allow the + target to appear later, such as after the end of the sentence:: -3. Use interpreted text syntax with a fixed internal format:: + This is a named reference__ of one word ("reference"). + __<http://www.example.org/reference/> Here is a `phrase + reference`__. __<http://www.example.org/phrase_reference/> - (a) `:name:` - (b) `name:` - (c) `name::` - (d) `::name::` - (e) `%name%` - (f) `#name#` - (g) `/name/` - (h) `&name&` - (i) `|name|` - (j) `[name]` - (k) `<name>` - (l) `&name;` - (m) `'name'` + Problem: this could only work for one reference at a time + (reference/target pairs must be proximate [refA trgA refB trgB], + not interleaved [refA refB trgA trgB] or nested [refA refB trgB + trgA]). This variation is too problematic; references and inline + external targets will have to be kept imediately adjacent (see (3) + below). - To avoid ML confusion (k) and (l) are definitely out. Square - brackets (j) won't work in the target (the substitution definition - would be indistinguishable from a footnote). + The ``"reference__ __<target>"`` syntax is actually for "anonymous + inline external targets", emphasized by the double underscores. It + follows that single trailing and leading underscores would lead to + *implicitly named* inline external targets. This would allow the + reuse of targets by name. So after ``"reference_ _<target>"``, + another ``"reference_"`` would point to the same target. - The ```/name/``` syntax (g) is reminiscent of "s/find/sub" - substitution syntax in ed-like languages. However, it may have a - misleading association with regexps, and looks like an absolute - POSIX path. (i) is visually equivalent and lacking the - connotations. + .. [#] + From RFC 2396 (URI syntax): - A disadvantage of all of these is that they limit interpreted text, - albeit only slightly. + The angle-bracket "<" and ">" and double-quote (") + characters are excluded [from URIs] because they are often + used as the delimiters around URI in text documents and + protocol fields. -4. Use specialized syntax, something new:: + Using <> angle brackets around each URI is especially + recommended as a delimiting style for URI that contain + whitespace. - (a) #name# - (b) @name@ - (c) /name/ - (d) |name| - (e) <<name>> - (f) //name// - (g) ||name|| - (h) ^name^ - (i) [[name]] - (j) ~name~ - (k) !name! - (l) =name= - (m) ?name? - (n) >name< + From RFC 822 (email headers): - "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes - looks just like a POSIX path; it is likely for such usage to appear - in text. + Angle brackets ("<" and ">") are generally used to indicate + the presence of a one machine-usable reference (e.g., + delimiting mailboxes), possibly including source-routing to + the machine. - "|" (d) and "^" (h) are feasible. +3. If it is best for references and inline external targets to be + immediately adjacent, then they might as well be integrated. + Here's an alternative syntax embedding the target URL in the + reference:: -5. Redefine the trailing underscore syntax. See definition syntax - alternative 4, below. + This is an anonymous `reference <http://www.example.org + /reference/>`__ of one word ("reference"). Here is a `phrase + reference <http://www.example.org/phrase_reference/>`__. -Syntax alternatives for the definition: + Advantages and disadvantages are similar to those in (2). + Readability is still an issue, but the syntax is a bit less + heavyweight (reduced line noise). Backquotes are required, even + for one-word references; the target URL is included within the + reference text, forcing a phrase context. -1. Use the existing directive syntax, with a predefined directive such - as "sub". It contains a further embedded directive resolving to an - inline-compatible object:: + We'll call this variant "embedded URIs". - .. sub:: biohazard - .. image:: biohazard.png - [height=20 width=20] + Problem: how to refer to a title like "HTML Anchors: <a>" (which + ends with an HTML/SGML/XML tag)? We could either require more + syntax on the target (like ``"`reference text + __<http://example.com/>`__"``), or require the odd conflicting + title to be escaped (like ``"`HTML Anchors: \<a>`__"``). The + latter seems preferable, and not too onerous. - .. sub:: parrot - That bird wouldn't *voom* if you put 10,000,000 volts - through it! + Similarly to (2) above, a single trailing underscore would convert + the reference & inline external target from anonymous to implicitly + named, allowing reuse of targets by name. - The advantages and disadvantages are the same as in inline - alternative 1. + I think this is the least objectionable of the syntax alternatives. -2. Use syntax as in #1, but with an embedded directivecompressed:: +Other syntax variations have been proposed (by Brett Cannon and Benja +Fallenstein):: - .. sub:: biohazard image:: biohazard.png - [height=20 width=20] + `phrase reference`->http://www.example.com - This is a bit better than alternative 1, but still too much. + `phrase reference`@http://www.example.com -3. Use a variant of directive syntax, incorporating the substitution - text, obviating the need for a special "sub" directive name. If we - assume reference alternative 4d (vertical bars), the matching - definition would look like this:: + `phrase reference`__ ->http://www.example.com - .. |biohazard| image:: biohazard.png - [height=20 width=20] + `phrase reference` [-> http://www.example.com] -4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) + `phrase reference`__ [-> http://www.example.com] - Instead of adding new syntax, redefine the trailing underscore - syntax to mean "substitution reference" instead of "hyperlink - reference". Alan's example:: + `phrase reference` <http://www.example.com>_ - I had lunch with Jonathan_ today. We talked about Zope_. +None of these variations are clearly superior to #3 above. Some have +problems that exclude their use. - .. _Jonathan: lj [user=jhl] - .. _Zope: http://www.zope.org/ +With any kind of inline external target syntax it comes down to the +conflict between maintainability and plaintext readability. I don't +see a major problem with reStructuredText's maintainability, and I +don't want to sacrifice plaintext readability to "improve" it. - A problem with the proposed syntax is that URIs which look like - simple reference names (alphanum plus ".", "-", "_") would be - indistinguishable from substitution directive names. A more - consistent syntax would be:: +The proponents of inline external targets want them for easily +maintainable web pages. The arguments go something like this: - I had lunch with Jonathan_ today. We talked about Zope_. +- Named hyperlinks are difficult to maintain because the reference + text is duplicated as the target name. - .. _Jonathan: lj:: user=jhl - .. _Zope: http://www.zope.org/ + To which I said, "So use anonymous hyperlinks." - (``::`` after ``.. _Jonathan: lj``.) +- Anonymous hyperlinks are difficult to maintain becuase the + references and targets have to be kept in sync. - The "Zope" target is a simple external hyperlink, but the - "Jonathan" target contains a directive. Alan proposed is that the - reference text be replaced by whatever the referenced directive - (the "directive target") produces. A directive reference becomes a - hyperlink reference if the contents of the directive target resolve - to a hyperlink. If the directive target resolves to an icon, the - reference is replaced by an inline icon. If the directive target - resolves to a hyperlink, the directive reference becomes a - hyperlink reference. + "So keep the targets close to the references, grouped after each + paragraph. Maintenance is trivial." - This seems too indirect and complicated for easy comprehension. +- But targets grouped after paragraphs break the flow of text. - The reference in the text will sometimes become a link, sometimes - not. Sometimes the reference text will remain, sometimes not. We - don't know *at the reference*:: + "Surely less than URLs embedded in the text! And if the intent is + to produce web pages, not readable plaintext, then who cares about + the flow of text?" - This is a `hyperlink reference`_; its text will remain. - This is an `inline icon`_; its text will disappear. +Many participants have voiced their objections to the proposed syntax: - That's a problem. + Garth Kidd: "I strongly prefer the current way of doing it. + Inline is spectactularly messy, IMHO." -The syntax that has been incorporated into the spec and parser is -reference alternative 4d with definition alternative 3:: + Tony Ibbs: "I vehemently agree... that the inline alternatives + being suggested look messy - there are/were good reasons they've + been taken out... I don't believe I would gain from the new + syntaxes." - The |biohazard| symbol... + Paul Moore: "I agree as well. The proposed syntax is far too + punctuation-heavy, and any of the alternatives discussed are + ambiguous or too subtle." - .. |biohazard| image:: biohazard.png - [height=20 width=20] +Others have voiced their support: -We can also combine substitution references with hyperlink references, -by appending a "_" (named hyperlink reference) or "__" (anonymous -hyperlink reference) suffix to the substitution reference. This -allows us to click on an image-link:: + fantasai: "I agree with Simon. In many cases, though certainly + not in all, I find parenthesizing the url in plain text flows + better than relegating it to a footnote." - The |biohazard|_ symbol... + Ken Manheimer: "I'd like to weigh in requesting some kind of easy, + direct inline reference link." - .. |biohazard| image:: biohazard.png - [height=20 width=20] - .. _biohazard: http://www.cdc.gov/ +(Interesting that those *against* the proposal have been using +reStructuredText for a while, and those *for* the proposal are either +new to the list ["fantasai", background unknown] or longtime +StructuredText users [Ken Manheimer].) -There have been several suggestions for the naming of these -constructs, originally called "substitution references" and -"substitutions". +I was initially ambivalent/against the proposed "inline external +targets". I value reStructuredText's readability very highly, and +although the proposed syntax offers convenience, I don't know if the +convenience is worth the cost in ugliness. Does the proposed syntax +compromise readability too much, or should the choice be left up to +the author? Perhaps if the syntax is *allowed* but its use strongly +*discouraged*, for aesthetic/readability reasons? -1. Candidate names for the reference construct: +After a great deal of thought and much input from users, I've decided +that there are reasonable use cases for this construct. The +documentation should strongly caution against its use in most +situations, recommending independent block-level targets instead. +Syntax #3 above ("embedded URIs") will be used. - (a) substitution reference - (b) tagging reference - (c) inline directive reference - (d) directive reference - (e) indirect inline directive reference - (f) inline directive placeholder - (g) inline directive insertion reference - (h) directive insertion reference - (i) insertion reference - (j) directive macro reference - (k) macro reference - (l) substitution directive reference -2. Candidate names for the definition construct: +Doctree Representation of Transitions +===================================== - (a) substitution - (b) substitution directive - (c) tag - (d) tagged directive - (e) directive target - (f) inline directive - (g) inline directive definition - (h) referenced directive - (i) indirect directive - (j) indirect directive definition - (k) directive definition - (l) indirect inline directive - (m) named directive definition - (n) inline directive insertion definition - (o) directive insertion definition - (p) insertion definition - (q) insertion directive - (r) substitution definition - (s) directive macro definition - (t) macro definition - (u) substitution directive definition - (v) substitution definition +(Although not reStructuredText-specific, this section fits best in +this document.) -"Inline directive reference" (1c) seems to be an appropriate term at -first, but the term "inline" is redundant in the case of the -reference. Its counterpart "inline directive definition" (2g) is -awkward, because the directive definition itself is not inline. +Having added the "horizontal rule" construct to the `reStructuredText +Markup Specification`_, a decision had to be made as to how to reflect +the construct in the implementation of the document tree. Given this +source:: -"Directive reference" (1d) and "directive definition" (2k) are too -vague. "Directive definition" could be used to refer to any -directive, not just those used for inline substitutions. + Document + ======== -One meaning of the term "macro" (1k, 2s, 2t) is too -programming-language-specific. Also, macros are typically simple text -substitution mechanisms: the text is substituted first and evaluated -later. reStructuredText substitution definitions are evaluated in -place at parse time and substituted afterwards. + Paragraph 1 -"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that -something new is getting added rather than one construct being -replaced by another. + -------- -Which brings us back to "substitution". The overall best names are -"substitution reference" (1a) and "substitution definition" (2v). A -long way to go to add one word! + Paragraph 2 + +The horizontal rule indicates a "transition" (in prose terms) or the +start of a new "division". Before implementation, the parsed document +tree would be:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + -------- <--- error here + <paragraph> + Paragraph 2 + +There are several possibilities for the implementation: + +1. Implement horizontal rules as "divisions" or segments. A + "division" is a title-less, non-hierarchical section. The first + try at an implementation looked like this:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + <division> + <paragraph> + Paragraph 2 + + But the two paragraphs are really at the same level; they shouldn't + appear to be at different levels. There's really an invisible + "first division". The horizontal rule splits the document body + into two segments, which should be treated uniformly. + +2. Treating "divisions" uniformly brings us to the second + possibility:: + + <document> + <section name="document"> + <title> + Document + <division> + <paragraph> + Paragraph 1 + <division> + <paragraph> + Paragraph 2 + + With this change, documents and sections will directly contain + divisions and sections, but not body elements. Only divisions will + directly contain body elements. Even without a horizontal rule + anywhere, the body elements of a document or section would be + contained within a division element. This makes the document tree + deeper. This is similar to the way HTML_ treats document contents: + grouped within a ``<body>`` element. + +3. Implement them as "transitions", empty elements:: + + <document> + <section name="document"> + <title> + Document + <paragraph> + Paragraph 1 + <transition> + <paragraph> + Paragraph 2 + + A transition would be a "point element", not containing anything, + only identifying a point within the document structure. This keeps + the document tree flatter, but the idea of a "point element" like + "transition" smells bad. A transition isn't a thing itself, it's + the space between two divisions. However, transitions are a + practical solution. + +Solution 3 was chosen for incorporation into the document tree model. + +.. _HTML: http://www.w3.org/MarkUp/ +----------------- + Not Implemented +----------------- + Reworking Footnotes =================== @@ -1257,673 +1355,443 @@ Syntax proposals: Without the ".. " marker, subsequent lines would either have to align as in one of the above, or we'd have to allow loose - alignment (I'd rather not):: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - -I proposed adopting the "minimal" syntax for footnotes and footnote -references, and adding citations and citation references to -reStructuredText's repertoire. The current footnote syntax for -citations is better than the alternatives given. - -From a reply by Tony Ibbs on 2002-03-01: - - However, I think easier with examples, so let's create one:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - .. [1] That is, little bits of referenced text at the - bottom of the page. - .. [2] Because Terry himself does, of course [3]_. - .. [3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - .. [4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - and look at it with the second syntax proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - _[1] That is, little bits of referenced text at the - bottom of the page. - _[2] Because Terry himself does, of course [3]_. - _[3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _[4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - (I note here that if I have gotten the indentation of the - footnotes themselves correct, this is clearly not as nice. And if - the indentation should be to the left margin instead, I like that - even less). - - and the third (new) proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes 1_ in their own writings than other people - 2_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style 4_, particularly in emails (not a medium that - lends itself to footnotes). - - _1. That is, little bits of referenced text at the - bottom of the page. - _2. Because Terry himself does, of course 3_. - _3. Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _4. Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - I think I don't, in practice, mind the targets too much (the use - of a dot after the number helps a lot here), but I do have a - problem with the body text, in that I don't naturally separate out - the footnotes as different than the rest of the text - instead I - keep wondering why there are numbers interspered in the text. The - use of brackets around the numbers ([ and ]) made me somehow parse - the footnote references as "odd" - i.e., not part of the body text - - and thus both easier to skip, and also (paradoxically) easier to - pick out so that I could follow them. - - Thus, for the moment (and as always susceptable to argument), I'd - say -1 on the new form of footnote reference (i.e., I much prefer - the existing ``[1]_`` over the proposed ``1_``), and ambivalent - over the proposed target change. - - That leaves David's problem of wanting to distinguish footnotes - and citations - and the only thing I can propose there is that - footnotes are numeric or # and citations are not (which, as a - human being, I can probably cope with!). - -From a reply by Paul Moore on 2002-03-01: - - I think the current footnote syntax ``[1]_`` is *exactly* the - right balance of distinctness vs unobtrusiveness. I very - definitely don't think this should change. - - On the target change, it doesn't matter much to me. - -From a further reply by Tony Ibbs on 2002-03-01, referring to the -"[1]" form and actual usage in email: - - Clearly this is a form people are used to, and thus we should - consider it strongly (in the same way that the usage of ``*..*`` - to mean emphasis was taken partly from email practise). - - Equally clearly, there is something "magical" for people in the - use of a similar form (i.e., ``[1]``) for both footnote reference - and footnote target - it seems natural to keep them similar. - - ... - - I think that this established plaintext usage leads me to strongly - believe we should retain square brackets at both ends of a - footnote. The markup of the reference end (a single trailing - underscore) seems about as minimal as we can get away with. The - markup of the target end depends on how one envisages the thing - - if ".." means "I am a target" (as I tend to see it), then that's - good, but one can also argue that the "_[1]" syntax has a neat - symmetry with the footnote reference itself, if one wishes (in - which case ".." presumably means "hidden/special" as David seems - to think, which is why one needs a ".." *and* a leading underline - for hyperlink targets. - -Given the persuading arguments voiced, we'll leave footnote & footnote -reference syntax alone. Except that these discussions gave rise to -the "auto-symbol footnote" concept, which has been added. Citations -and citation references have also been added. - - -Auto-Enumerated Lists -===================== - -The advantage of auto-numbered enumerated lists would be similar to -that of auto-numbered footnotes: lists could be written and rearranged -without having to manually renumber them. The disadvantages are also -the same: input and output wouldn't match exactly; the markup may be -ugly or confusing (depending on which alternative is chosen). - -1. Use the "#" symbol. Example:: - - #. Item 1. - #. Item 2. - #. Item 3. - - Advantages: simple, explicit. Disadvantage: enumeration sequence - cannot be specified (limited to arabic numerals); ugly. - -2. As a variation on #1, first initialize the enumeration sequence? - For example:: - - a) Item a. - #) Item b. - #) Item c. - - Advantages: simple, explicit, any enumeration sequence possible. - Disadvantages: ugly; perhaps confusing with mixed concrete/abstract - enumerators. - -3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: - - 1. Item 1. - 1. Item 2. - 1. Item 3. - - Advantages: enumeration sequence is explicit (could be multiple - "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise - erroneous input (e.g., a duplicate item "1.") would pass silently, - either causing a problem later in the list (if no blank lines - between items) or creating two lists (with blanks). - - Take this input for example:: - - 1. Item 1. - - 1. Unintentional duplicate of item 1. - - 2. Item 2. - - Currently the parser will produce two list, "1" and "1,2" (no - warnings, because of the presence of blank lines). Using Fred's - notation, the current behavior is "1,1,2 -> 1 1,2" (without blank - lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What - should the behavior be with auto-numbering? - - Fred has produced a patch__, whose initial behavior is as follows:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2,3 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2,3 [WARNING] 3 - 1,1,2 -> 1,2 [WARNING] 2 - - (After the "[WARNING]", the "3" would begin a new list.) - - I have mixed feelings about adding this functionality to the spec & - parser. It would certainly be useful to some users (myself - included; I often have to renumber lists). Perhaps it's too - clever, asking the parser to guess too much. What if you *do* want - three one-item lists in a row, each beginning with "1."? You'd - have to use empty comments to force breaks. Also, I question - whether "1,2,2 -> 1,2,3" is optimal behavior. - - In response, Fred came up with "a stricter and more explicit rule - [which] would be to only auto-number silently if *all* the - enumerators of a list were identical". In that case:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2 [WARNING] 2 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2 [WARNING] 2,3 - 1,1,2 -> 1,2 [WARNING] 2 - - Should any start-value be allowed ("3,3,3"), or should - auto-numbered lists be limited to begin with ordinal-1 ("1", "A", - "a", "I", or "i")? - - __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 - &group_id=38414&atid=422032 - -4. Alternative proposed by Tony Ibbs:: - - #1. First item. - #3. Aha - I edited this in later. - #2. Second item. - - The initial proposal required unique enumerators within a list, but - this limits the convenience of a feature of already limited - applicability and convenience. Not a useful requirement; dropped. - - Instead, simply prepend a "#" to a standard list enumerator to - indicate auto-enumeration. The numbers (or letters) of the - enumerators themselves are not significant, except: - - - as a sequence indicator (arabic, roman, alphabetic; upper/lower), - - - and perhaps as a start value (first list item). - - Advantages: explicit, any enumeration sequence possible. - Disadvantages: a bit ugly. - - -Inline External Targets -======================= - -Currently reStructuredText has two hyperlink syntax variations: - -* Named hyperlinks:: - - This is a named reference_ of one word ("reference"). Here is - a `phrase reference`_. Phrase references may even cross `line - boundaries`_. + alignment (I'd rather not):: - .. _reference: http://www.example.org/reference/ - .. _phrase reference: http://www.example.org/phrase_reference/ - .. _line boundaries: http://www.example.org/line_boundaries/ + _[GVR2001] Python Documentation; van Rossum, Drake, et al.; + http://www.python.org/doc/ - + Advantages: +I proposed adopting the "minimal" syntax for footnotes and footnote +references, and adding citations and citation references to +reStructuredText's repertoire. The current footnote syntax for +citations is better than the alternatives given. - - The plaintext is readable. - - Each target may be reused multiple times (e.g., just write - ``"reference_"`` again). - - No syncronized ordering of references and targets is necessary. +From a reply by Tony Ibbs on 2002-03-01: - + Disadvantages: + However, I think easier with examples, so let's create one:: - - The reference text must be repeated as target names; could lead - to mistakes. - - The target URLs may be located far from the references, and hard - to find in the plaintext. + Fans of Terry Pratchett are perhaps more likely to use + footnotes [1]_ in their own writings than other people + [2]_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style [4]_, particularly in emails (not a medium that + lends itself to footnotes). -* Anonymous hyperlinks (in current reStructuredText):: + .. [1] That is, little bits of referenced text at the + bottom of the page. + .. [2] Because Terry himself does, of course [3]_. + .. [3] Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + .. [4] Presumably because it detracts from linear + reading of the text - this is, of course, the point. - This is an anonymous reference__. Here is an anonymous - `phrase reference`__. Phrase references may even cross `line - boundaries`__. + and look at it with the second syntax proposal:: - __ http://www.example.org/reference/ - __ http://www.example.org/phrase_reference/ - __ http://www.example.org/line_boundaries/ + Fans of Terry Pratchett are perhaps more likely to use + footnotes [1]_ in their own writings than other people + [2]_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style [4]_, particularly in emails (not a medium that + lends itself to footnotes). - + Advantages: + _[1] That is, little bits of referenced text at the + bottom of the page. + _[2] Because Terry himself does, of course [3]_. + _[3] Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + _[4] Presumably because it detracts from linear + reading of the text - this is, of course, the point. - - The plaintext is readable. - - The reference text does not have to be repeated. + (I note here that if I have gotten the indentation of the + footnotes themselves correct, this is clearly not as nice. And if + the indentation should be to the left margin instead, I like that + even less). - + Disadvantages: + and the third (new) proposal:: - - References and targets must be kept in sync. - - Targets cannot be reused. - - The target URLs may be located far from the references. + Fans of Terry Pratchett are perhaps more likely to use + footnotes 1_ in their own writings than other people + 2_. Of course, in *general*, one only sees footnotes + in academic or technical writing - it's use in fiction + and letter writing is not normally considered good + style 4_, particularly in emails (not a medium that + lends itself to footnotes). -For comparison and historical background, StructuredText also has two -syntaxes for hyperlinks: + _1. That is, little bits of referenced text at the + bottom of the page. + _2. Because Terry himself does, of course 3_. + _3. Although he has the distinction of being + *funny* when he does it, and his fans don't always + achieve that aim. + _4. Presumably because it detracts from linear + reading of the text - this is, of course, the point. -* First, ``"reference text":URL``:: + I think I don't, in practice, mind the targets too much (the use + of a dot after the number helps a lot here), but I do have a + problem with the body text, in that I don't naturally separate out + the footnotes as different than the rest of the text - instead I + keep wondering why there are numbers interspered in the text. The + use of brackets around the numbers ([ and ]) made me somehow parse + the footnote references as "odd" - i.e., not part of the body text + - and thus both easier to skip, and also (paradoxically) easier to + pick out so that I could follow them. - This is a "reference":http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase - reference":http://www.example.org/phrase_reference/. + Thus, for the moment (and as always susceptable to argument), I'd + say -1 on the new form of footnote reference (i.e., I much prefer + the existing ``[1]_`` over the proposed ``1_``), and ambivalent + over the proposed target change. -* Second, ``"reference text", http://example.com/absolute_URL``:: + That leaves David's problem of wanting to distinguish footnotes + and citations - and the only thing I can propose there is that + footnotes are numeric or # and citations are not (which, as a + human being, I can probably cope with!). - This is a "reference", http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase reference", - http://www.example.org/phrase_reference/. +From a reply by Paul Moore on 2002-03-01: -Both syntaxes share advantages and disadvantages: + I think the current footnote syntax ``[1]_`` is *exactly* the + right balance of distinctness vs unobtrusiveness. I very + definitely don't think this should change. -+ Advantages: + On the target change, it doesn't matter much to me. - - The target is specified immediately adjacent to the reference. +From a further reply by Tony Ibbs on 2002-03-01, referring to the +"[1]" form and actual usage in email: -+ Disadvantages: + Clearly this is a form people are used to, and thus we should + consider it strongly (in the same way that the usage of ``*..*`` + to mean emphasis was taken partly from email practise). - - Poor plaintext readability. - - Targets cannot be reused. - - Both syntaxes use double quotes, common in ordinary text. - - In the first syntax, the URL and the last word are stuck - together, exacerbating the line wrap problem. - - The second syntax is too magical; text could easily be written - that way by accident (although only absolute URLs are recognized - here, perhaps because of the potential for ambiguity). + Equally clearly, there is something "magical" for people in the + use of a similar form (i.e., ``[1]``) for both footnote reference + and footnote target - it seems natural to keep them similar. -A new type of "inline external hyperlink" has been proposed. + ... -1. On 2002-06-28, Simon Budig proposed__ a new syntax for - reStructuredText hyperlinks:: + I think that this established plaintext usage leads me to strongly + believe we should retain square brackets at both ends of a + footnote. The markup of the reference end (a single trailing + underscore) seems about as minimal as we can get away with. The + markup of the target end depends on how one envisages the thing - + if ".." means "I am a target" (as I tend to see it), then that's + good, but one can also argue that the "_[1]" syntax has a neat + symmetry with the footnote reference itself, if one wishes (in + which case ".." presumably means "hidden/special" as David seems + to think, which is why one needs a ".." *and* a leading underline + for hyperlink targets. - This is a reference_(http://www.example.org/reference/) of one - word ("reference"). Here is a `phrase - reference`_(http://www.example.org/phrase_reference/). Are - these examples, (single-underscore), named? If so, `anonymous - references`__(http://www.example.org/anonymous/) using two - underscores would probably be preferable. +Given the persuading arguments voiced, we'll leave footnote & footnote +reference syntax alone. Except that these discussions gave rise to +the "auto-symbol footnote" concept, which has been added. Citations +and citation references have also been added. - __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html - The syntax, advantages, and disadvantages are similar to those of - StructuredText. +-------- + Tabled +-------- - + Advantages: +Reworking Explicit Markup (Round 2) +=================================== - - The target is specified immediately adjacent to the reference. +See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion. - + Disadvantages: +In April 2004, a new thread becan on docutils-develop: `Inconsistency +in RST markup`__. Several arguments were made; the first argument +begat later arguments. Below, the arguments are paraphrased "in +quotes", with responses. - - Poor plaintext readability. - - Targets cannot be reused (unless named, but the semantics are - unclear). +__ http://thread.gmane.org/gmane.text.docutils.devel/1386 - + Problems: +1. References and targets take this form:: - - The ``"`ref`_(URL)"`` syntax forces the last word of the - reference text to be joined to the URL, making a potentially - very long word that can't be wrapped (URLs can be very long). - The reference and the URL should be separate. This is a - symptom of the following point: + targetname_ - - The syntax produces a single compound construct made up of two - equally important parts, *with syntax in the middle*, *between* - the reference and the target. This is unprecedented in - reStructuredText. + .. _targetname: stuff - - The "inline hyperlink" text is *not* a named reference (there's - no lookup by name), so it shouldn't look like one. + But footnotes, "which generate links just like targets do", are + written as:: - - According to the IETF standards RFC 2396 and RFC 2732, - parentheses are legal URI characters and curly braces are legal - email characters, making their use prohibitively difficult. + [1]_ - - The named/anonymous semantics are unclear. + .. [1] stuff -2. After an analysis__ of the syntax of (1) above, we came up with the - following compromise syntax:: + "Footnotes should be written as":: - This is an anonymous reference__ - __<http://www.example.org/reference/> of one word - ("reference"). Here is a `phrase reference`__ - __<http://www.example.org/phrase_reference/>. `Named - references`_ _<http://www.example.org/anonymous/> use single - underscores. + [1]_ - __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html + .. _[1]: stuff - The syntax builds on that of the existing "inline internal - targets": ``an _`inline internal target`.`` + But they're not the same type of animal. That's not a "footnote + target", it's a *footnote*. Being a target is not a footnote's + primary purpose (an arguable point). It just happens to grow a + target automatically, for convenience. Just as a section title:: - + Advantages: + Title + ===== - - The target is specified immediately adjacent to the reference, - improving maintainability: + isn't a "title target", it's a *title*, which happens to grow a + target automatically. The consistency is there, it's just deeper + than at first glance. - - References and targets are easily kept in sync. - - The reference text does not have to be repeated. + Also, ".. [1]" was chosen for footnote syntax because it closely + resembles one form of actual footnote rendering. ".. _[1]:" is too + verbose; excessive punctuation is required to get the job done. - - The construct is executed in two parts: references identical to - existing references, and targets that are new but not too big a - stretch from current syntax. + For more of the reasoning behind the syntax, see `Problems With + StructuredText (Hyperlinks) + <http://docutils.sf.net/spec/rst/problems.html#hyperlinks>`__ and + `Reworking Footnotes`_. - - There's overwhelming precedent for quoting URLs with angle - brackets [#]_. +2. "I expect directives to also look like ``.. this:`` [one colon] + because that also closely parallels the link and footnote target + markup." - + Disadvantages: + There are good reasons for the two-colon syntax: - - Poor plaintext readability. - - Lots of "line noise". - - Targets cannot be reused (unless named; see below). + Two colons are used after the directive type for these reasons: - To alleviate the readability issue slightly, we could allow the - target to appear later, such as after the end of the sentence:: + - Two colons are distinctive, and unlikely to be used in common + text. - This is a named reference__ of one word ("reference"). - __<http://www.example.org/reference/> Here is a `phrase - reference`__. __<http://www.example.org/phrase_reference/> + - Two colons avoids clashes with common comment text like:: - Problem: this could only work for one reference at a time - (reference/target pairs must be proximate [refA trgA refB trgB], - not interleaved [refA refB trgA trgB] or nested [refA refB trgB - trgA]). This variation is too problematic; references and inline - external targets will have to be kept imediately adjacent (see (3) - below). + .. Danger: modify at your own risk! - The ``"reference__ __<target>"`` syntax is actually for "anonymous - inline external targets", emphasized by the double underscores. It - follows that single trailing and leading underscores would lead to - *implicitly named* inline external targets. This would allow the - reuse of targets by name. So after ``"reference_ _<target>"``, - another ``"reference_"`` would point to the same target. + - If an implementation of reStructuredText does not recognize a + directive (i.e., the directive-handler is not installed), a + level-3 (error) system message is generated, and the entire + directive block (including the directive itself) will be + included as a literal block. Thus "::" is a natural choice. - .. [#] - From RFC 2396 (URI syntax): + -- http://docutils.sf.net/spec/rst/reStructuredText.html#directives - The angle-bracket "<" and ">" and double-quote (") - characters are excluded [from URIs] because they are often - used as the delimiters around URI in text documents and - protocol fields. + The last reason is not particularly compelling; it's more of a + convenient coincidence or mnemonic. - Using <> angle brackets around each URI is especially - recommended as a delimiting style for URI that contain - whitespace. +3. "Comments always seemed too easy. I almost never write comments. + I'd have no problem writing '.. comment:' in front of my comments. + In fact, it would probably be more readable, as comments *should* + be set off strongly, because they are very different from normal + text." - From RFC 822 (email headers): + Many people do use comments though, and some applications of + reStructuredText require it. For example, all reStructuredText + PEPs (and this document!) have an Emacs stanza at the bottom, in a + comment. Having to write ".. comment::" would be very obtrusive. - Angle brackets ("<" and ">") are generally used to indicate - the presence of a one machine-usable reference (e.g., - delimiting mailboxes), possibly including source-routing to - the machine. + Comments *should* be dirt-easy to do. It should be easy to + "comment out" a block of text. Comments in programming languages + and other markup languages are invariably easy. -3. If it is best for references and inline external targets to be - immediately adjacent, then they might as well be integrated. - Here's an alternative syntax embedding the target URL in the - reference:: + Any author is welcome to preface their comments with "Comment:" or + "Do Not Print" or "Note to Editor" or anything they like. A + "comment" directive could easily be implemented. It might be + confused with admonition directives, like "note" and "caution" + though. In unrelated (and unpublished and unfinished) work, adding + a "comment" directive as a true document element was considered:: - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a `phrase - reference <http://www.example.org/phrase_reference/>`__. + If structure is necessary, we could use a "comment" directive + (to avoid nonsensical DTD changes, the "comment" directive + could produce an untitled topic element). - Advantages and disadvantages are similar to those in (2). - Readability is still an issue, but the syntax is a bit less - heavyweight (reduced line noise). Backquotes are required, even - for one-word references; the target URL is included within the - reference text, forcing a phrase context. +4. "One of the goals of reStructuredText is to be *readable* by people + who don't know it. This construction violates that: it is not at + all obvious to the uninitiated that text marked by '..' is a + comment. On the other hand, '.. comment:' would be totally + transparent." - We'll call this variant "embedded URIs". + Totally transparent, perhaps, but also very obtrusive. Another of + `reStructuredText's goals`_ is to be unobtrusive, and + ".. comment::" would violate that. The goals of reStructuredText + are many, and they conflict. Determining the right set of goals + and finding solutions that best fit is done on a case-by-case + basis. - Problem: how to refer to a title like "HTML Anchors: <a>" (which - ends with an HTML/SGML/XML tag)? We could either require more - syntax on the target (like ``"`reference text - __<http://example.com/>`__"``), or require the odd conflicting - title to be escaped (like ``"`HTML Anchors: \<a>`__"``). The - latter seems preferable, and not too onerous. + Even readability is has two aspects. Being readable without any + prior knowledge is one. Being as easily read in raw form as in + processed form is the other. ".." may not contribute to the former + aspect, but ".. comment::" would certainly detract from the latter. - Similarly to (2) above, a single trailing underscore would convert - the reference & inline external target from anonymous to implicitly - named, allowing reuse of targets by name. + .. _author's note: + .. _reStructuredText's goals: + http://docutils.sf.net/spec/rst/introduction.html#goals - I think this is the least objectionable of the syntax alternatives. +5. "Recently I sent someone an rst document, and they got confused; I + had to explain to them that '..' marks comments, *unless* it's a + directive, etc..." -Other syntax variations have been proposed (by Brett Cannon and Benja -Fallenstein):: + The explanation of directives *is* roundabout, defining comments in + terms of not being other things. That's definitely a wart. - `phrase reference`->http://www.example.com +6. "Under the current system, a mistyped directive (with ':' instead + of '::') will be silently ignored. This is an error that could + easily go unnoticed." - `phrase reference`@http://www.example.com + A parser option/setting like "--comments-on-stderr" would help. - `phrase reference`__ ->http://www.example.com +7. "I'd prefer to see double-dot-space / command / double-colon as the + standard Docutils markup-marker. It's unusual enough to avoid + being accidently used. Everything that starts with a double-dot + should end with a double-colon." - `phrase reference` [-> http://www.example.com] + That would increase the punctuation verbosity of some constructs + considerably. - `phrase reference`__ [-> http://www.example.com] +8. Edward Loper proposed the following plan for backwards + compatibility: - `phrase reference` <http://www.example.com>_ + 1. ".. foo" will generate a deprecation warning to stderr, and + nothing in the output (no system messages). + 2. ".. foo: bar" will be treated as a directive foo. If there + is no foo directive, then do the normal error output. + 3. ".. foo:: bar" will generate a deprecation warning to + stderr, and be treated as a directive. Or leave it valid? -None of these variations are clearly superior to #3 above. Some have -problems that exclude their use. + So some existing documents might start printing deprecation + warnings, but the only existing documents that would *break* + would be ones that say something like:: -With any kind of inline external target syntax it comes down to the -conflict between maintainability and plaintext readability. I don't -see a major problem with reStructuredText's maintainability, and I -don't want to sacrifice plaintext readability to "improve" it. + .. warning: this should be a comment -The proponents of inline external targets want them for easily -maintainable web pages. The arguments go something like this: + instead of:: -- Named hyperlinks are difficult to maintain because the reference - text is duplicated as the target name. + .. warning:: this should be a comment - To which I said, "So use anonymous hyperlinks." + Here, we're trading fairly common a silent error (directive + falsely treated as a comment) for a fairly uncommon explicitly + flagged error (comment falsely treated as directive). To make + things even easier, we could add a sentence to the + unknown-directive error. Something like "If you intended to + create a comment, please use '.. comment:' instead". -- Anonymous hyperlinks are difficult to maintain becuase the - references and targets have to be kept in sync. +On one hand, I understand and sympathize with the points raised. On +the other hand, I think the current syntax strikes the right balance +(but I acknowledge a possible lack of objectivity). On the gripping +hand, the comment and directive syntax has become well established, so +even if it's a wart, it may be a wart we have to live with. - "So keep the targets close to the references, grouped after each - paragraph. Maintenance is trivial." +Making any of these changes would cause a lot of breakage or at least +deprecation warnings. I'm not sure the benefit is worth the cost. -- But targets grouped after paragraphs break the flow of text. +For now, we'll treat this as an unresolved legacy issue. - "Surely less than URLs embedded in the text! And if the intent is - to produce web pages, not readable plaintext, then who cares about - the flow of text?" -Many participants have voiced their objections to the proposed syntax: +------- + To Do +------- - Garth Kidd: "I strongly prefer the current way of doing it. - Inline is spectactularly messy, IMHO." +Auto-Enumerated Lists +===================== - Tony Ibbs: "I vehemently agree... that the inline alternatives - being suggested look messy - there are/were good reasons they've - been taken out... I don't believe I would gain from the new - syntaxes." +The advantage of auto-numbered enumerated lists would be similar to +that of auto-numbered footnotes: lists could be written and rearranged +without having to manually renumber them. The disadvantages are also +the same: input and output wouldn't match exactly; the markup may be +ugly or confusing (depending on which alternative is chosen). - Paul Moore: "I agree as well. The proposed syntax is far too - punctuation-heavy, and any of the alternatives discussed are - ambiguous or too subtle." +1. Use the "#" symbol. Example:: -Others have voiced their support: + #. Item 1. + #. Item 2. + #. Item 3. - fantasai: "I agree with Simon. In many cases, though certainly - not in all, I find parenthesizing the url in plain text flows - better than relegating it to a footnote." + Advantages: simple, explicit. Disadvantage: enumeration sequence + cannot be specified (limited to arabic numerals); ugly. - Ken Manheimer: "I'd like to weigh in requesting some kind of easy, - direct inline reference link." +2. As a variation on #1, first initialize the enumeration sequence? + For example:: -(Interesting that those *against* the proposal have been using -reStructuredText for a while, and those *for* the proposal are either -new to the list ["fantasai", background unknown] or longtime -StructuredText users [Ken Manheimer].) + a) Item a. + #) Item b. + #) Item c. -I was initially ambivalent/against the proposed "inline external -targets". I value reStructuredText's readability very highly, and -although the proposed syntax offers convenience, I don't know if the -convenience is worth the cost in ugliness. Does the proposed syntax -compromise readability too much, or should the choice be left up to -the author? Perhaps if the syntax is *allowed* but its use strongly -*discouraged*, for aesthetic/readability reasons? + Advantages: simple, explicit, any enumeration sequence possible. + Disadvantages: ugly; perhaps confusing with mixed concrete/abstract + enumerators. -After a great deal of thought and much input from users, I've decided -that there are reasonable use cases for this construct. The -documentation should strongly caution against its use in most -situations, recommending independent block-level targets instead. -Syntax #3 above ("embedded URIs") will be used. +3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: + 1. Item 1. + 1. Item 2. + 1. Item 3. -Doctree Representation of Transitions -===================================== + Advantages: enumeration sequence is explicit (could be multiple + "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise + erroneous input (e.g., a duplicate item "1.") would pass silently, + either causing a problem later in the list (if no blank lines + between items) or creating two lists (with blanks). -(Although not reStructuredText-specific, this section fits best in -this document.) + Take this input for example:: -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: + 1. Item 1. - Document - ======== + 1. Unintentional duplicate of item 1. - Paragraph 1 + 2. Item 2. - -------- + Currently the parser will produce two list, "1" and "1,2" (no + warnings, because of the presence of blank lines). Using Fred's + notation, the current behavior is "1,1,2 -> 1 1,2" (without blank + lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What + should the behavior be with auto-numbering? - Paragraph 2 + Fred has produced a patch__, whose initial behavior is as follows:: -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: + 1,1,1 -> 1,2,3 + 1,2,2 -> 1,2,3 + 3,3,3 -> 3,4,5 + 1,2,2,3 -> 1,2,3 [WARNING] 3 + 1,1,2 -> 1,2 [WARNING] 2 - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 + (After the "[WARNING]", the "3" would begin a new list.) -There are several possibilities for the implementation: + I have mixed feelings about adding this functionality to the spec & + parser. It would certainly be useful to some users (myself + included; I often have to renumber lists). Perhaps it's too + clever, asking the parser to guess too much. What if you *do* want + three one-item lists in a row, each beginning with "1."? You'd + have to use empty comments to force breaks. Also, I question + whether "1,2,2 -> 1,2,3" is optimal behavior. -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: + In response, Fred came up with "a stricter and more explicit rule + [which] would be to only auto-number silently if *all* the + enumerators of a list were identical". In that case:: - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 + 1,1,1 -> 1,2,3 + 1,2,2 -> 1,2 [WARNING] 2 + 3,3,3 -> 3,4,5 + 1,2,2,3 -> 1,2 [WARNING] 2,3 + 1,1,2 -> 1,2 [WARNING] 2 - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. + Should any start-value be allowed ("3,3,3"), or should + auto-numbered lists be limited to begin with ordinal-1 ("1", "A", + "a", "I", or "i")? -2. Treating "divisions" uniformly brings us to the second - possibility:: + __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 + &group_id=38414&atid=422032 - <document> - <section name="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 +4. Alternative proposed by Tony Ibbs:: - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. + #1. First item. + #3. Aha - I edited this in later. + #2. Second item. -3. Implement them as "transitions", empty elements:: + The initial proposal required unique enumerators within a list, but + this limits the convenience of a feature of already limited + applicability and convenience. Not a useful requirement; dropped. - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 + Instead, simply prepend a "#" to a standard list enumerator to + indicate auto-enumeration. The numbers (or letters) of the + enumerators themselves are not significant, except: - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. + - as a sequence indicator (arabic, roman, alphabetic; upper/lower), -Solution 3 was chosen for incorporation into the document tree model. + - and perhaps as a start value (first list item). -.. _HTML: http://www.w3.org/MarkUp/ + Advantages: explicit, any enumeration sequence possible. + Disadvantages: a bit ugly. Nested Inline Markup @@ -2265,190 +2133,338 @@ directive only) until all Writers have been updated to support the new syntax & implementation. -Reworking Explicit Markup (Round 2) -=================================== +------------------- + ... Or Not To Do? +------------------- + +This is the realm of the possible but questionably probable. These +ideas are kept here as a record of what has been proposed, for +posterity and in case any of them prove to be useful. + + +Compound Enumerated Lists +========================= + +Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to +allow for nested enumerated lists without indentation? + + +Sloppy Indentation of List Items +================================ + +Perhaps the indentation shouldn't be so strict. Currently, this is +required:: + + 1. First line, + second line. + +Anything wrong with this? :: + + 1. First line, + second line. + +Problem? :: + + 1. First para. + + Block quote. (no good: requires some indent relative to first + para) + + Second Para. + + 2. Have to carefully define where the literal block ends:: + + Literal block + + Literal block? + +Hmm... Non-strict indentation isn't such a good idea. + + +Lazy Indentation of List Items +============================== + +Another approach: Going back to the first draft of reStructuredText +(2000-11-27 post to Doc-SIG):: + + - This is the fourth item of the main list (no blank line above). + The second line of this item is not indented relative to the + bullet, which precludes it from having a second paragraph. + +Change that to *require* a blank line above and below, to reduce +ambiguity. This "loosening" may be added later, once the parser's +been nailed down. However, a serious drawback of this approach is to +limit the content of each list item to a single paragraph. + + +David's Idea for Lazy Indentation +--------------------------------- + +Consider a paragraph in a word processor. It is a single logical line +of text which ends with a newline, soft-wrapped arbitrarily at the +right edge of the page or screen. We can think of a plaintext +paragraph in the same way, as a single logical line of text, ending +with two newlines (a blank line) instead of one, and which may contain +arbitrary line breaks (newlines) where it was accidentally +hard-wrapped by an application. We can compensate for the accidental +hard-wrapping by "unwrapping" every unindented second and subsequent +line. The indentation of the first line of a paragraph or list item +would determine the indentation for the entire element. Blank lines +would be required between list items when using lazy indentation. + +The following example shows the lazy indentation of multiple body +elements:: + + - This is the first paragraph + of the first list item. + + Here is the second paragraph + of the first list item. + + - This is the first paragraph + of the second list item. + + Here is the second paragraph + of the second list item. + +A more complex example shows the limitations of lazy indentation:: + + - This is the first paragraph + of the first list item. + + Next is a definition list item: + + Term + Definition. The indentation of the term is + required, as is the indentation of the definition's + first line. + + When the definition extends to more than + one line, lazy indentation may occur. (This is the second + paragraph of the definition.) + + - This is the first paragraph + of the second list item. + + - Here is the first paragraph of + the first item of a nested list. + + So this paragraph would be outside of the nested list, + but inside the second list item of the outer list. + + But this paragraph is not part of the list at all. + +And the ambiguity remains:: + + - Look at the hyphen at the beginning of the next line + - is it a second list item marker, or a dash in the text? + + Similarly, we may want to refer to numbers inside enumerated + lists: + + 1. How many socks in a pair? There are + 2. How many pants in a pair? Exactly + 1. Go figure. + +Literal blocks and block quotes would still require consistent +indentation for all their lines. For block quotes, we might be able +to get away with only requiring that the first line of each contained +element be indented. For example:: + + Here's a paragraph. + + This is a paragraph inside a block quote. + Second and subsequent lines need not be indented at all. + + - A bullet list inside + the block quote. + + Second paragraph of the + bullet list inside the block quote. + +Although feasible, this form of lazy indentation has problems. The +document structure and hierarchy is not obvious from the indentation, +making the source plaintext difficult to read. This will also make +keeping track of the indentation while writing difficult and +error-prone. However, these problems may be acceptable for Wikis and +email mode, where we may be able to rely on less complex structure +(few nested lists, for example). + -See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion. +Multiple Roles in Interpreted Text +================================== -In April 2004, a new thread becan on docutils-develop: `Inconsistency -in RST markup`__. Several arguments were made; the first argument -begat later arguments. Below, the arguments are paraphrased "in -quotes", with responses. +In reStructuredText, inline markup cannot be nested (yet; `see +above`__). This also applies to interpreted text. In order to +simultaneously combine multiple roles for a single piece of text, a +syntax extension would be necessary. Ideas: -__ http://thread.gmane.org/gmane.text.docutils.devel/1386 +1. Initial idea:: -1. References and targets take this form:: + `interpreted text`:role1,role2: - targetname_ +2. Suggested by Jason Diamond:: - .. _targetname: stuff + `interpreted text`:role1:role2: - But footnotes, "which generate links just like targets do", are - written as:: +If a document is so complex as to require nested inline markup, +perhaps another markup system should be considered. By design, +reStructuredText does not have the flexibility of XML. - [1]_ +__ `Nested Inline Markup`_ - .. [1] stuff - "Footnotes should be written as":: +Parameterized Interpreted Text +============================== - [1]_ +In some cases it may be expedient to pass parameters to interpreted +text, analogous to function calls. Ideas: - .. _[1]: stuff +1. Parameterize the interpreted text role itself (suggested by Jason + Diamond):: - But they're not the same type of animal. That's not a "footnote - target", it's a *footnote*. Being a target is not a footnote's - primary purpose (an arguable point). It just happens to grow a - target automatically, for convenience. Just as a section title:: + `interpreted text`:role1(foo=bar): - Title - ===== + Positional parameters could also be supported:: - isn't a "title target", it's a *title*, which happens to grow a - target automatically. The consistency is there, it's just deeper - than at first glance. + `CSS`:acronym(Cascading Style Sheets): is used for HTML, and + `CSS`:acronym(Content Scrambling System): is used for DVDs. - Also, ".. [1]" was chosen for footnote syntax because it closely - resembles one form of actual footnote rendering. ".. _[1]:" is too - verbose; excessive punctuation is required to get the job done. + Technical problem: current interpreted text syntax does not + recognize roles containing whitespace. Design problem: this smells + like programming language syntax, but reStructuredText is not a + programming language. - For more of the reasoning behind the syntax, see `Problems With - StructuredText (Hyperlinks) - <http://docutils.sf.net/spec/rst/problems.html#hyperlinks>`__ and - `Reworking Footnotes`_. +2. Put the parameters inside the interpreted text:: -2. "I expect directives to also look like ``.. this:`` [one colon] - because that also closely parallels the link and footnote target - markup." + `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and + `CSS (Content Scrambling System)`:acronym: is used for DVDs. - There are good reasons for the two-colon syntax: + Although this could be defined on an individual basis (per role), + we ought to have a standard. Hyperlinks with embedded URIs already + use angle brackets; perhaps they could be used here too:: - Two colons are used after the directive type for these reasons: + `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and + `CSS <Content Scrambling System>`:acronym: is used for DVDs. - - Two colons are distinctive, and unlikely to be used in common - text. + Do angle brackets connote URLs too much for this to be acceptable? + How about the "tag" connotation -- does it save them or doom them? - - Two colons avoids clashes with common comment text like:: +Does this push inline markup too far? Readability becomes a serious +issue. Substitutions may provide a better alternative (at the expense +of verbosity and duplication) by pulling the details out of the text +flow:: - .. Danger: modify at your own risk! + |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. - - If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a - level-3 (error) system message is generated, and the entire - directive block (including the directive itself) will be - included as a literal block. Thus "::" is a natural choice. + .. |CSS| acronym:: Cascading Style Sheets + .. |CSS-DVD| acronym:: Content Scrambling System + :text: CSS - -- http://docutils.sf.net/spec/rst/reStructuredText.html#directives +---------------------------------------------------------------------- - The last reason is not particularly compelling; it's more of a - convenient coincidence or mnemonic. +This whole idea may be going beyond the scope of reStructuredText. +Documents requiring this functionality may be better off using XML or +another markup system. -3. "Comments always seemed too easy. I almost never write comments. - I'd have no problem writing '.. comment:' in front of my comments. - In fact, it would probably be more readable, as comments *should* - be set off strongly, because they are very different from normal - text." +This argument comes up regularly when pushing the envelope of +reStructuredText syntax. I think it's a useful argument in that it +provides a check on creeping featurism. In many cases, the resulting +verbosity produces such unreadable plaintext that there's a natural +desire *not* to use it unless absolutely necessary. It's a matter of +finding the right balance. - Many people do use comments though, and some applications of - reStructuredText require it. For example, all reStructuredText - PEPs (and this document!) have an Emacs stanza at the bottom, in a - comment. Having to write ".. comment::" would be very obtrusive. - Comments *should* be dirt-easy to do. It should be easy to - "comment out" a block of text. Comments in programming languages - and other markup languages are invariably easy. +Syntax for Interpreted Text Role Bindings +========================================= - Any author is welcome to preface their comments with "Comment:" or - "Do Not Print" or "Note to Editor" or anything they like. A - "comment" directive could easily be implemented. It might be - confused with admonition directives, like "note" and "caution" - though. In unrelated (and unpublished and unfinished) work, adding - a "comment" directive as a true document element was considered:: +The following syntax (idea from Jeffrey C. Jacobs) could be used to +associate directives with roles:: - If structure is necessary, we could use a "comment" directive - (to avoid nonsensical DTD changes, the "comment" directive - could produce an untitled topic element). + .. :rewrite: class:: rewrite -4. "One of the goals of reStructuredText is to be *readable* by people - who don't know it. This construction violates that: it is not at - all obvious to the uninitiated that text marked by '..' is a - comment. On the other hand, '.. comment:' would be totally - transparent." + `She wore ribbons in her hair and it lay with streaks of + grey`:rewrite: - Totally transparent, perhaps, but also very obtrusive. Another of - `reStructuredText's goals`_ is to be unobtrusive, and - ".. comment::" would violate that. The goals of reStructuredText - are many, and they conflict. Determining the right set of goals - and finding solutions that best fit is done on a case-by-case - basis. +The syntax is similar to that of substitution declarations, and the +directive/role association may resolve implementation issues. The +semantics, ramifications, and implementation details would need to be +worked out. - Even readability is has two aspects. Being readable without any - prior knowledge is one. Being as easily read in raw form as in - processed form is the other. ".." may not contribute to the former - aspect, but ".. comment::" would certainly detract from the latter. +The example above would implement the "rewrite" role as adding a +``class="rewrite"`` attribute to the interpreted text ("inline" +element). The stylesheet would then pick up on the "class" attribute +to do the actual formatting. - .. _author's note: - .. _reStructuredText's goals: - http://docutils.sf.net/spec/rst/introduction.html#goals +The advantage of the new syntax would be flexibility. Uses other than +"class" may present themselves. The disadvantage is complexity: +having to implement new syntax for a relatively specialized operation, +and having new semantics in existing directives ("class::" would do +something different). -5. "Recently I sent someone an rst document, and they got confused; I - had to explain to them that '..' marks comments, *unless* it's a - directive, etc..." +The `"role" directive`__ has been implemented. - The explanation of directives *is* roundabout, defining comments in - terms of not being other things. That's definitely a wart. +__ http://docutils.sf.net/spec/rst/directives.html#role -6. "Under the current system, a mistyped directive (with ':' instead - of '::') will be silently ignored. This is an error that could - easily go unnoticed." - A parser option/setting like "--comments-on-stderr" would help. +Character Processing +==================== -7. "I'd prefer to see double-dot-space / command / double-colon as the - standard Docutils markup-marker. It's unusual enough to avoid - being accidently used. Everything that starts with a double-dot - should end with a double-colon." +Several people have suggested adding some form of character processing +to reStructuredText: - That would increase the punctuation verbosity of some constructs - considerably. +* Some sort of automated replacement of ASCII sequences: -8. Edward Loper proposed the following plan for backwards - compatibility: + - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). + - Convert quotes to curly quote entities. (Essentially impossible + for HTML? Unnecessary for TeX.) + - Various forms of ``:-)`` to smiley icons. + - ``"\ "`` to  . Problem with line-wrapping though: it could + end up escaping the newline. + - Escaped newlines to <BR>. + - Escaped period or quote or dash as a disappearing catalyst to + allow character-level inline markup? - 1. ".. foo" will generate a deprecation warning to stderr, and - nothing in the output (no system messages). - 2. ".. foo: bar" will be treated as a directive foo. If there - is no foo directive, then do the normal error output. - 3. ".. foo:: bar" will generate a deprecation warning to - stderr, and be treated as a directive. Or leave it valid? +* XML-style character entities, such as "©" for the copyright + symbol. - So some existing documents might start printing deprecation - warnings, but the only existing documents that would *break* - would be ones that say something like:: +Docutils has no need of a character entity subsystem. Supporting +Unicode and text encodings, character entities should be directly +represented in the text: a copyright symbol should be represented by +the copyright symbol character. If this is not possible in an +authoring environment, a pre-processing stage can be added, or a table +of substitution definitions can be devised. - .. warning: this should be a comment +A "unicode" directive has been implemented to allow direct +specification of esoteric characters. In combination with the +substitution construct, "include" files defining common sets of +character entities can be defined and used. `A set of character +entity set definition files have been defined`__ (`tarball`__). +There's also `a description and instructions for use`__. - instead of:: +__ http://docutils.sf.net/tmp/charents/ +__ http://docutils.sf.net/tmp/charents.tgz +__ http://docutils.sf.net/tmp/charents/README.html - .. warning:: this should be a comment +To allow for `character-level inline markup`_, a limited form of +character processing has been added to the spec and parser: escaped +whitespace characters are removed from the processed document. Any +further character processing will be of this functional type, rather +than of the character-encoding type. - Here, we're trading fairly common a silent error (directive - falsely treated as a comment) for a fairly uncommon explicitly - flagged error (comment falsely treated as directive). To make - things even easier, we could add a sentence to the - unknown-directive error. Something like "If you intended to - create a comment, please use '.. comment:' instead". +.. _character-level inline markup: + reStructuredText.html#character-level-inline-markup -On one hand, I understand and sympathize with the points raised. On -the other hand, I think the current syntax strikes the right balance -(but I acknowledge a possible lack of objectivity). On the gripping -hand, the comment and directive syntax has become well established, so -even if it's a wart, it may be a wart we have to live with. +* Directive idea:: -Making any of these changes would cause a lot of breakage or at least -deprecation warnings. I'm not sure the benefit is worth the cost. + .. text-replace:: "pattern" "replacement" -For now, we'll treat this as an unresolved legacy issue. + - Support Unicode "U+XXXX" codes. + - Support regexps, perhaps with alternative "regexp-replace" + directive. + - Flags for regexps; ":flags:" option, or individuals. + - Specifically, should the default be case-sensistive or + -insensitive? .. -- cgit v1.2.1 From cefaa079bf8d638beedb2f0bf51b8a14cce656bc Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 14 May 2004 20:43:46 +0000 Subject: added 'documentation cleanup' git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2099 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7d42a87e2..981dffa5b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -395,6 +395,39 @@ General Documentation ------------- +* The documentation is currently messed up. These are the plans for + an overall cleanup: + + - Move 'Acknowledgements' from ``HISTORY.txt`` to ``THANKS.txt``. + + - Move ``docs/*`` to ``docs/user/``. + + - Create ``docs/dev/``. + + - Split up ``spec/notes.txt`` to ``BUGS.txt``, + ``docs/dev/todo.txt``, ``docs/dev/policies.txt``, + ``docs/dev/website.txt``, ``docs/dev/release.txt``. + + - Move 'Future Plans' from ``HISTORY.txt`` to ``docs/dev/todo.txt``. + + - Move ``spec/rst/introduction.txt`` to ``docs/user/rst/``. + + - Move ``spec/rst/problems.txt`` and ``spec/rst/alternatives.txt`` + to ``docs/dev/rst/``. + + - Move ``spec/howto/`` to ``docs/dev/howto/``. + + - Move ``spec/`` to ``docs/spec/``. + +* After doing the cleanup: + + - Add 'how to report bugs' to ``BUGS.txt``. + + - Add ``docs/index.txt``. + + - Create a 'priority' section in ``docs/dev/todo.txt`` and (maybe) + ``BUGS.txt``. + * User docs. What's needed? * Add an "examples" directory, beside "tools" and "docs", for -- cgit v1.2.1 From 562167b4d14bf3738afda2141dc1cb73b1e0daaf Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 15 May 2004 03:40:23 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2100 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 53 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 981dffa5b..2f28c5268 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -398,42 +398,63 @@ Documentation * The documentation is currently messed up. These are the plans for an overall cleanup: + - Create new subdirectories of docs/: + + * ``docs/user/``: introductory/tutorial material for end-users + * ``docs/dev/``: for core-developers + * ``docs/ref/``: reference material for all groups + * ``docs/howto/``: for component-developers and core-developers + * ``docs/lib/``: API reference material for library-user/developers + - Move 'Acknowledgements' from ``HISTORY.txt`` to ``THANKS.txt``. - Move ``docs/*`` to ``docs/user/``. - - Create ``docs/dev/``. - - Split up ``spec/notes.txt`` to ``BUGS.txt``, ``docs/dev/todo.txt``, ``docs/dev/policies.txt``, ``docs/dev/website.txt``, ``docs/dev/release.txt``. - - Move 'Future Plans' from ``HISTORY.txt`` to ``docs/dev/todo.txt``. + - Move 'Future Plans' from ``HISTORY.txt`` to new 'Priorities' + section of ``docs/dev/todo.txt``. + + - Move ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from + ``spec/`` to ``docs/dev``. + + - Move ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd`` from + ``spec/`` to ``docs/ref/``. - - Move ``spec/rst/introduction.txt`` to ``docs/user/rst/``. + - Move ``transforms.txt`` from ``spec/`` to ``docs/lib/``. - - Move ``spec/rst/problems.txt`` and ``spec/rst/alternatives.txt`` - to ``docs/dev/rst/``. + - PEPs in ``spec/``? Move to ``docs/ref/`` or ``docs/dev/``? - - Move ``spec/howto/`` to ``docs/dev/howto/``. + - Move ``alternatives.txt``, ``introduction.txt``, and + ``problems.txt`` from ``spec/rst/`` to ``docs/dev/rst/``. + (Move "Doctree Representation of Transitions" section of + ``alternatives.txt`` elsewhere? Where?) - - Move ``spec/`` to ``docs/spec/``. + - Move ``reStructuredText.txt``, ``directives.txt``, and + ``interpreted.txt`` from ``spec/rst/`` to ``docs/ref/rst/``. + (Rename ``interpreted.txt`` to ``roles.txt``?) + + - Move ``spec/howto/`` to ``docs/howto``. + (Not to ``docs/dev/howto/``; not just for core-developers.) + + It would be useful to keep the CVS history of moved files. To do + so, we need to supply SourceForge with a `script for modifying the + Docutils CVS repository`__. Any other pending repository cleanups + (remove "module" module; others?) should be done at the same time. + + __ http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure * After doing the cleanup: - - Add 'how to report bugs' to ``BUGS.txt``. + - Add 'how to report bugs' to ``BUGS.txt`` (like `Subversion's + <http://svn.collab.net/viewcvs/svn/trunk/BUGS?rev=9086&view=markup>`__). - Add ``docs/index.txt``. - - Create a 'priority' section in ``docs/dev/todo.txt`` and (maybe) - ``BUGS.txt``. - * User docs. What's needed? -* Add an "examples" directory, beside "tools" and "docs", for - interesting examples of Docutils usage? Have a top-level README.txt - file and a subdirectory for each example. (Martin Blais) - Implementation Docs ``````````````````` -- cgit v1.2.1 From 562fdc222a9cd9c5ec3949081abaa95cf55b8afa Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 15 May 2004 23:16:23 +0000 Subject: Emphasized the DocTitle transfrom in docs, as it's a very FAQ. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2101 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 5 +++-- docs/user/rst/quickref.html | 7 +++++++ docs/user/rst/quickstart.txt | 15 +++++++++++---- 3 files changed, 21 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 52d30033d..b018c5f5a 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -443,8 +443,9 @@ Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after -the "document title" can become the document subtitle. See the -`DocTitle transform`_ for details. +the "document title" can become the document subtitle. The rest of +the sections are than lifted up a level or two. See the `DocTitle +transform`_ for details. Sections diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 6998e244c..64512058d 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -279,6 +279,10 @@ <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> <br><samp>The underline/overline must be at</samp> <br><samp>least as long as the title text.</samp> +<br><samp></samp> +<br><samp>A lone top-level (sub)section</samp> +<br><samp>is lifted up to be the document's</samp> +<br><samp>(sub)title.</samp> <td> <font size="+2"><strong>Title</strong></font> @@ -290,6 +294,9 @@ are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". The underline/overline must be at least as long as the title text. + <p>A lone top-level (sub)section is + lifted up to be the document's + (sub)title. </table> <h2><a href="#contents" name="paragraphs" class="backref" diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index c156b0b33..d7cde218c 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -302,10 +302,17 @@ their name. To link to the Lists_ heading, I write "``Lists_``". If the heading has a space in it like `text styles`_, we need to quote the heading "```text styles`_``". -To indicate the document title, use a unique adornment style at the -beginning of the document. To indicate the document subtitle, use -another unique adornment style immediately after the document title. -For example:: +Document Title / Subtitle +------------------------- + +The title of the whole document is a distinct concept from section titles and +is formatted somewhat differently (e.g. the HTML writer by default shows it as +a centered heading). + +To indicate the document title in reStructuredText, use a unique adornment +style at the beginning of the document. To indicate the document subtitle, +use another unique adornment style immediately after the document title. For +example:: ================ Document Title -- cgit v1.2.1 From 114e74a2a2bfba9c118723f2588f944dddafa08b Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 00:05:33 +0000 Subject: Demoted "Document Title / Subtitle" to a subsection of "Sections" -- seems more appropriate for this quiet short document. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2102 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index d7cde218c..d97bc6df7 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -303,7 +303,7 @@ the heading has a space in it like `text styles`_, we need to quote the heading "```text styles`_``". Document Title / Subtitle -------------------------- +````````````````````````` The title of the whole document is a distinct concept from section titles and is formatted somewhat differently (e.g. the HTML writer by default shows it as -- cgit v1.2.1 From 743c1f012b8e7326184e92846d33e41b743ee68a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 00:44:13 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2104 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index b018c5f5a..57b9df995 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -444,7 +444,7 @@ subtitle explicitly in reStructuredText. Instead, a lone top-level section title (see Sections_ below) can be treated as the document title. Similarly, a lone second-level section title immediately after the "document title" can become the document subtitle. The rest of -the sections are than lifted up a level or two. See the `DocTitle +the sections are then lifted up a level or two. See the `DocTitle transform`_ for details. -- cgit v1.2.1 From e7a0836407bc54a1bf333295df816b812a91bea2 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 00:46:32 +0000 Subject: date git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2105 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 64512058d..593660ff5 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -18,7 +18,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2004-02-23</em> + <br align="right"><em>Updated 2004-05-15</em> <blockquote> <p>Copyright: This document has been placed in the public domain. -- cgit v1.2.1 From b8ab1e5ca18b983eb4c29edbd393d266ecfa8b9a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 00:48:10 +0000 Subject: minor edit git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2106 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickstart.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index d97bc6df7..d36326473 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -302,12 +302,13 @@ their name. To link to the Lists_ heading, I write "``Lists_``". If the heading has a space in it like `text styles`_, we need to quote the heading "```text styles`_``". + Document Title / Subtitle ````````````````````````` -The title of the whole document is a distinct concept from section titles and -is formatted somewhat differently (e.g. the HTML writer by default shows it as -a centered heading). +The title of the whole document is distinct from section titles and +may be formatted somewhat differently (e.g. the HTML writer by default +shows it as a centered heading). To indicate the document title in reStructuredText, use a unique adornment style at the beginning of the document. To indicate the document subtitle, @@ -326,8 +327,8 @@ example:: ... -Note that "Document Title" and "Section Title" both use equals signs, -but are distict and unrelated styles. The text of +Note that "Document Title" and "Section Title" above both use equals +signs, but are distict and unrelated styles. The text of overline-and-underlined titles (but not underlined-only) may be inset for aesthetics. -- cgit v1.2.1 From 436aa0daedad0bcf6a63be423f9e65fd96035cad Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 13:35:16 +0000 Subject: doc cleanup: added docs/peps/ git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2108 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2f28c5268..ef8cc519d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -405,6 +405,7 @@ Documentation * ``docs/ref/``: reference material for all groups * ``docs/howto/``: for component-developers and core-developers * ``docs/lib/``: API reference material for library-user/developers + * ``docs/peps/``: Python Enhancement Proposals - Move 'Acknowledgements' from ``HISTORY.txt`` to ``THANKS.txt``. -- cgit v1.2.1 From 4f6306efaa650d80668f3f93d9e5dde7f0730789 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 16 May 2004 20:31:11 +0000 Subject: Multirow support. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2115 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 9d7ca4f8d..cecaa7745 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -231,8 +231,9 @@ Tables - baselineskip/stretch does not help. * Should there be two hlines after table head and on table end ? * Table: multicol cells are always {l}. +* The contents of a rowspan cell do not influence table height. + (Maybe if we put a tabular inside ?) * Table heads and footer for longtable (firstpage lastpage ..). -* Longtable does not work with multirow * Tabularx says "do not use any multicolmn which spans any X column. maybe use ltxtable instead of tabularx (Longtable combined with tabularx). but ltxtable disables longtable's multicolumn. -- cgit v1.2.1 From fa88eae3be69caa196190615302b9ee0d1d9cd10 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 24 May 2004 15:29:28 +0000 Subject: removed superfluous line git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2123 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index ef8cc519d..e5f4cc902 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -426,8 +426,6 @@ Documentation - Move ``transforms.txt`` from ``spec/`` to ``docs/lib/``. - - PEPs in ``spec/``? Move to ``docs/ref/`` or ``docs/dev/``? - - Move ``alternatives.txt``, ``introduction.txt``, and ``problems.txt`` from ``spec/rst/`` to ``docs/dev/rst/``. (Move "Doctree Representation of Transitions" section of -- cgit v1.2.1 From d72a0d3dcc4e7f713778f258a234491484b413d5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 25 May 2004 20:30:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2124 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e5f4cc902..fcfde28c7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -120,9 +120,9 @@ General 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 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"?) * Need a Unicode to HTML entities codec for HTML writer? No, the "xmlcharrefreplace" output encoding error handler is sufficient. @@ -963,6 +963,24 @@ __ rst/alternatives.html#or-not-to-do * 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. + Directives `````````` @@ -1365,7 +1383,7 @@ when used in a document. directive which transforms a uniform two-level bullet list into a table. Using a directive would allow the author to explicitly set the table's orientation (by column or by row), the presence of row - headers, etc. + headers, etc. How to handle row and/or column spans? - _`colorize.python`: Colorize Python code. Fine for HTML output, but what about other formats? Revert to a literal block? Do we -- cgit v1.2.1 From f766fc02c0e2d4d7e69c0dd8ad89347208593d34 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 26 May 2004 13:33:06 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2125 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fcfde28c7..aa7285fe5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1976,8 +1976,8 @@ 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_, and `reasonably complete`_. Adding to the `main source -tree`_ or to a `parallel project`_ implies a commitment to the +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? @@ -1992,6 +1992,12 @@ Docutils user community. * _`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). @@ -2009,6 +2015,9 @@ 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: ../docs/tools.html +.. _Docutils Configuration Files: ../docs/config.txt + Setting Up For Docutils Development ``````````````````````````````````` -- cgit v1.2.1 From e7e73998e0bb85cc2e98899cb59d85c83d90a128 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 26 May 2004 16:19:16 +0000 Subject: Chg: use raggedright instead of flushleft for literal-blocks inside tables. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2127 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index cecaa7745..1d1d2b96f 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -234,10 +234,16 @@ Tables * The contents of a rowspan cell do not influence table height. (Maybe if we put a tabular inside ?) * Table heads and footer for longtable (firstpage lastpage ..). -* Tabularx says "do not use any multicolmn which spans any X column. - maybe use ltxtable instead of tabularx (Longtable combined with tabularx). - but ltxtable disables longtable's multicolumn. * Table cells with multirow and multicolumn +* literal-blocks in table cells: + + - if verbatim or flushleft have vertical space above and below. + - if raggedright we might have firstline indent, depending on + the document setting. + +Notes +~~~~~ + * table-style booktabs: booktabs.sty 1.00 does not work with longtable. Miscellaneous -- cgit v1.2.1 From 7420feaf7c8bb020e99599966cac574c98b99aba Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 26 May 2004 17:20:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2129 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 67 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index aa7285fe5..703d27eec 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -395,65 +395,74 @@ General Documentation ------------- -* The documentation is currently messed up. These are the plans for +* .. _documentation cleanup: + + The documentation is currently messed up. These are the plans for an overall cleanup: - Create new subdirectories of docs/: * ``docs/user/``: introductory/tutorial material for end-users - * ``docs/dev/``: for core-developers + * ``docs/dev/``: for core-developers (development notes, plans, etc.) * ``docs/ref/``: reference material for all groups * ``docs/howto/``: for component-developers and core-developers - * ``docs/lib/``: API reference material for library-user/developers * ``docs/peps/``: Python Enhancement Proposals - - Move 'Acknowledgements' from ``HISTORY.txt`` to ``THANKS.txt``. - - Move ``docs/*`` to ``docs/user/``. - - Split up ``spec/notes.txt`` to ``BUGS.txt``, - ``docs/dev/todo.txt``, ``docs/dev/policies.txt``, - ``docs/dev/website.txt``, ``docs/dev/release.txt``. - - - Move 'Future Plans' from ``HISTORY.txt`` to new 'Priorities' - section of ``docs/dev/todo.txt``. - - Move ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from ``spec/`` to ``docs/dev``. - - Move ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd`` from - ``spec/`` to ``docs/ref/``. - - - Move ``transforms.txt`` from ``spec/`` to ``docs/lib/``. + - Move ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd``, + ``transforms.txt`` from ``spec/`` to ``docs/ref/``. - - Move ``alternatives.txt``, ``introduction.txt``, and - ``problems.txt`` from ``spec/rst/`` to ``docs/dev/rst/``. - (Move "Doctree Representation of Transitions" section of - ``alternatives.txt`` elsewhere? Where?) + - Move ``alternatives.txt``, and ``problems.txt`` from ``spec/rst/`` + to ``docs/dev/rst/``. (Move "Doctree Representation of + Transitions" section of ``alternatives.txt`` elsewhere? [Not + yet.]) - - Move ``reStructuredText.txt``, ``directives.txt``, and - ``interpreted.txt`` from ``spec/rst/`` to ``docs/ref/rst/``. - (Rename ``interpreted.txt`` to ``roles.txt``?) + - Move `reStructuredText.txt``, ``directives.txt``, + ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/`` + to ``docs/ref/rst/``. Rename ``interpreted.txt`` to + ``roles.txt``. Rename ``reStructuredText.txt`` to + ``restructuredtext.txt``. - Move ``spec/howto/`` to ``docs/howto``. (Not to ``docs/dev/howto/``; not just for core-developers.) - It would be useful to keep the CVS history of moved files. To do - so, we need to supply SourceForge with a `script for modifying the - Docutils CVS repository`__. Any other pending repository cleanups - (remove "module" module; others?) should be done at the same time. + In order to keep the CVS history of moved files, we need to supply + SourceForge with a `script for modifying the Docutils CVS + repository`__. Any other pending repository cleanups should be done + at the same time. Script now in CVS: + sandbox/davidg/infrastructure/cvs-reorg.sh. __ http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure -* After doing the cleanup: + After doing the cleanup (running the cvs-reorg.sh script): + + - Add ``docs/index.txt``. - Add 'how to report bugs' to ``BUGS.txt`` (like `Subversion's <http://svn.collab.net/viewcvs/svn/trunk/BUGS?rev=9086&view=markup>`__). - - Add ``docs/index.txt``. + - Move 'Future Plans' from ``HISTORY.txt`` to new 'Priorities' + section of ``docs/dev/todo.txt``. + + - Add ``THANKS.txt`` from 'Acknowledgements' in ``HISTORY.txt``. + + - Add ``BUGS.txt``, ``docs/dev/policies.txt``, + ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but + the "to do" list in ``docs/dev/todo.txt``. + + - Add symlinks from all old paths to new paths. + + - Go through all the docs (including under web/) & code and fix + broken links. * User docs. What's needed? + - reST cheat sheet -- max. 2 pages. + Implementation Docs ``````````````````` -- cgit v1.2.1 From 46d5297ffc6be4cb54479aa54ea6f90d52d8ae38 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 May 2004 20:59:24 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2133 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 703d27eec..65b0e576f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -421,7 +421,7 @@ Documentation Transitions" section of ``alternatives.txt`` elsewhere? [Not yet.]) - - Move `reStructuredText.txt``, ``directives.txt``, + - Move ``reStructuredText.txt``, ``directives.txt``, ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/`` to ``docs/ref/rst/``. Rename ``interpreted.txt`` to ``roles.txt``. Rename ``reStructuredText.txt`` to @@ -434,9 +434,10 @@ Documentation SourceForge with a `script for modifying the Docutils CVS repository`__. Any other pending repository cleanups should be done at the same time. Script now in CVS: - sandbox/davidg/infrastructure/cvs-reorg.sh. + `sandbox/davidg/infrastructure/cvs-reorg.sh`__. __ http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure + __ http://docutils.sourceforge.net/sandbox/davidg/infrastructure/cvs-reorg.sh After doing the cleanup (running the cvs-reorg.sh script): -- cgit v1.2.1 From 20e99ef35863b0e027fcfd29265ce7a1c2a515a4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 May 2004 21:31:27 +0000 Subject: fixed invalid example git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2135 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index cc2657b1b..9f0f11952 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -836,7 +836,7 @@ output stream:: .. raw:: latex - \documentclass[twocolumn]{article} + \setlength{\parindent}{0pt} Raw data can also be read from an external file, specified in a directive option. In this case, the content block must be empty. For -- cgit v1.2.1 From b0bc4fbea3eb3981d9d09cc8b451f080b715cb9a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 29 May 2004 21:47:31 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2136 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 65b0e576f..19528a978 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -455,10 +455,13 @@ Documentation ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but the "to do" list in ``docs/dev/todo.txt``. - - Add symlinks from all old paths to new paths. + - Add a ``.htaccess`` file to the ``web`` module containing + redirects from all old paths to new paths. They'll preserve + fragments (the "#name" part of a URL), and won't clutter up the + file system, and will correct the URL in the user's browser. - - Go through all the docs (including under web/) & code and fix - broken links. + - Go through all the docs (including under web/) & code and update + links. * User docs. What's needed? -- cgit v1.2.1 From 5a7e57e94aecca40e785fa525e4c60c6e90ecbc6 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 30 May 2004 17:28:22 +0000 Subject: *** empty log message *** git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2141 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 1d1d2b96f..c3db84776 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -237,9 +237,10 @@ Tables * Table cells with multirow and multicolumn * literal-blocks in table cells: - - if verbatim or flushleft have vertical space above and below. - - if raggedright we might have firstline indent, depending on - the document setting. + If verbatim or flushleft one gets vertical space above and below. + This is bad for the topmost paragraph in a cell, therefore the writer + uses raggedright. Ragged right fails on followup paragraphs as the + vertical space would get lost. Notes ~~~~~ -- cgit v1.2.1 From 4592539c50f46977272f46d5de1db4c735b42e30 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 30 May 2004 18:46:46 +0000 Subject: Better? english. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2142 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index c3db84776..dca7147e5 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -237,10 +237,11 @@ Tables * Table cells with multirow and multicolumn * literal-blocks in table cells: - If verbatim or flushleft one gets vertical space above and below. - This is bad for the topmost paragraph in a cell, therefore the writer - uses raggedright. Ragged right fails on followup paragraphs as the - vertical space would get lost. + - If verbatim or flushleft is used one gets vertical space above and below. + - This is bad for the topmost paragraph in a cell, therefore the writer + uses raggedright. + - Ragged right fails on followup paragraphs as the vertical space would be + missing. Notes ~~~~~ -- cgit v1.2.1 From e865d212ffa1684207616d71ce7c5a9abd5e6684 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 30 May 2004 18:55:49 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2143 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 9f0f11952..4d72e4c24 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -443,9 +443,14 @@ constructs a literal block where the text is parsed for inline markup. It is equivalent to a `line block`_ with different rendering: typically in a typewriter/monospaced typeface, like an ordinary literal block. Parsed literal blocks are useful for adding hyperlinks -to code examples. However, care must be taken with the text, because -inline markup is recognized; there is no protection from parsing. -Backslash-escapes may be necessary in places. +to code examples. + +However, care must be taken with the text, because inline markup is +recognized and there is no protection from parsing. Backslash-escapes +may be necessary to prevent unintended parsing. And because the +markup characters are removed by the parser, care must also be taken +with vertical alignment. Parsed "ASCII art" is tricky, and extra +whitespace may be necessary. For example, all the element names in this content model are links:: -- cgit v1.2.1 From 79eef33c08e3c23042e76702ab41b51a4baf5f20 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 31 May 2004 16:54:59 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2149 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index 150978728..af13ee155 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -244,7 +244,8 @@ _`generator` _`halt_level` The threshold at or above which system messages are converted to - exceptions, halting execution immediately. + exceptions, halting execution immediately. If `traceback`_ is + set, the exception will propagate; otherwise, Docutils will exit. Default: severe (4). Options: ``--halt, --strict``. @@ -323,7 +324,10 @@ _`toc_backlinks` --toc-top-backlinks, --no-toc-backlinks``. _`traceback` - Enable Python tracebacks when an error occurs. + Enable Python tracebacks when halt-level system messages and other + exceptions occur. Useful for debugging, and essential for issue + reports. Exceptions are allowed to propagate, instead of being + caught and reported (in a user-friendly way) by Docutils. Default: disabled (None). Options: ``--traceback, --no-traceback``. -- cgit v1.2.1 From 47a67f3522eb913fb28d5463a29564f8e1bc8c6f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 31 May 2004 20:48:13 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2151 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 19528a978..09fe33cac 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1398,6 +1398,50 @@ when used in a document. the table's orientation (by column or by row), the presence of row headers, etc. How to handle row and/or column spans? + This is what it might look like:: + + .. list-table:: + + * - Treat + - Quantity + - Description + * - Albatross! + - 299 + - On a stick! + * - Crunchy Frog! + - 1499 + - If we took the bones out, it wouldn't be crunchy, + now would it? + * - Gannet Ripple! + - 199 + - On a stick! + + Issues: + + * How to indicate that there's 1 header row? Perhaps two lists? + :: + + .. list-table:: + + + - Treat + - Quantity + - Description + + * - Albatross! + - 299 + - On a stick! + + A directive option (``:headrows: 1``)? + + * How to indicate the column widths? A directive option? :: + + .. list-table:: + :widths: 15 10 35 + + Automatic defaults from the text used? + + * How to handle row and/or column spans? + - _`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" -- cgit v1.2.1 From 71acc9450058eedbb90dfeaea2fcf6c9b96e1ccd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 31 May 2004 20:53:24 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2152 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 09fe33cac..02274603e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1396,7 +1396,7 @@ when used in a document. directive which transforms a uniform two-level bullet list into a table. Using a directive would allow the author to explicitly set the table's orientation (by column or by row), the presence of row - headers, etc. How to handle row and/or column spans? + headers, etc. This is what it might look like:: -- cgit v1.2.1 From c132fb2a3961dd90e6131737e426c337c4e9e8cc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 03:36:04 +0000 Subject: Minimal reStructuredText cheat sheet. Source text to be printed out for reference. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2153 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/cheatsheet.txt | 115 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/user/rst/cheatsheet.txt (limited to 'docs') diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt new file mode 100644 index 000000000..21a694ede --- /dev/null +++ b/docs/user/rst/cheatsheet.txt @@ -0,0 +1,115 @@ +.. Comments begin with ".. ". Document title (specialized section title) next: + +===================================================== + The reStructuredText_ Cheat Sheet: Syntax Reminders +===================================================== +:Author: David Goodger <goodger@python.org> +:Date: $Date$ +:Revision: $Revision$ +:Info: Use the `text source <cheatsheet.txt>`_, **not** the HTML. + See <http://docutils.sf.net/rst.html> for full info. +:Description: This is a "docinfo block", or bibliographic field list + +Section Structure +================= +Section titles are underlined or overlined & underlined. + +Body Elements +============= +Grid table: + ++--------------------------------+-----------------------------------+ +| Paragraphs are flush-left, | Literal block, preceded by "::":: | +| separated by blank lines. | | +| | Indented | +| Block quotes are indented. | | ++--------------------------------+ or:: | +| >>> print 'Doctest block' | | +| Doctest block | > Quoted | ++--------------------------------+-----------------------------------+ + +Simple tables: + +================ ==================================================== +List Type Examples +================ ==================================================== +Bullet list * items begin with "-", "+", or "*" +Enumerated list 1. items use any variation of "1.", "A)", and "(i)" +Definition list Term is flush-left : optional classifier + Definition is indented, no blank line between +Field list :field name: field body +Option list -o at least 2 spaces between option & description +================ ==================================================== + +================ ==================================================== +Explicit Markup Examples (only visible in the `text source`_) +================ ==================================================== +Footnote .. [1] Manually numbered or [#] auto-numbered + (even [#labelled]) or [*] auto-symbol +Citation .. [CIT2002] A citation. +Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html + .. _indirect target: reStructuredText_ + .. _internal target: +Anonymous Target __ http://docutils.sf.net/spec/rst/reStructuredText.html +Directive ("::") .. image:: images/biohazard.png +Substitution Def .. |substitution| replace:: like an inline directive +Comment .. is anything else +================ ==================================================== + +Inline Markup +============= +*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text +with role`:emphasis:; ``inline literal text``; standalone hyperlink, +http://docutils.sourceforge.net; named reference, reStructuredText_; +`anonymous reference`__; footnote reference, [1]_; citation reference, +[CIT2002]_; |substitution|; _`inline internal target`. + +Directive Quick Reference +========================= +See <http://docutils.sf.net/spec/rst/directives.html> for full info. + +================ ==================================================== +Directive Name Description +================ ==================================================== +attention Specific admonition; also "caution", "danger", + "error", "hint", "important", "note", "tip", "warning" +admonition Generic admonition: ``.. admonition:: By The Way`` +image ``.. image:: picture.png``; many options possible +figure Like "image", but with optional caption and legend +topic ``.. topic:: Title``; like a mini section +sidebar ``.. sidebar:: Title``; like a mini parallel document +line-block Line breaks and leading whitespace is significant; + useful for addresses & verse +parsed-literal A literal block with parsed inline markup +rubric ``.. rubric:: Informal Heading`` +epigraph Block quote with class="epigraph" +highlights Block quote with class="highlights" +pull-quote Block quote with class="pull-quote" +contents Generate a table of contents +sectnum Automatically number sections, subsections, etc. +target-notes Create an explicit footnote for each external target +meta HTML-specific metadata +include Read an external reST file as if it were inline +raw Non-reST data passed untouched to the Writer +replace Replacement text for substitution definitions +unicode Unicode character code conversion for substitution defs +class Set a "class" attribute on the next element +role Create a custom interpreted text role +================ ==================================================== + +Interpreted Text Role Quick Reference +===================================== +See <http://docutils.sf.net/spec/rst/interpreted.html> for full info. + +================ ==================================================== +Role Name Description +================ ==================================================== +emphasis Equivalent to *emphasis* +literal Equivalent to ``literal``, except not as literal +PEP Reference to a numbered Python Enhancement Proposal +RFC Reference to a numbered Internet Request For Comments +strong Equivalent to **strong** +sub Subscript +sup Superscript +title Title reference (book, etc.); standard default role +================ ==================================================== -- cgit v1.2.1 From 17e233f30780538bd284c4da57777a4a1d8c5260 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 13:06:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 02274603e..4350a61a5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -465,8 +465,6 @@ Documentation * User docs. What's needed? - - reST cheat sheet -- max. 2 pages. - Implementation Docs ``````````````````` -- cgit v1.2.1 From 0556d5c6b7da0ea8fc9c59bd0004b115ec689355 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 21:25:34 +0000 Subject: added "table" directive docs git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2162 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/directives.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs') diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index 4d72e4c24..b75f52e51 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -545,6 +545,34 @@ Pull-Quote Produces a pull-quote-class block quote. See Epigraph_ above. +Table +===== + +:Directive Type: "table" +:Doctree Element: table +:Directive Arguments: 1, optional (table title). +:Directive Options: Possible. +:Directive Content: A normal reStructuredText table. + +The "table" directive is used to create a titled table, to associate a +title with a table:: + + .. table:: Truth table for "not" + + ===== ===== + A not A + ===== ===== + False True + True False + ===== ===== + +The following option is recognized: + +``class`` : text + Set a "class" attribute value on the table element. See the + class_ directive below. + + ---------------- Document Parts ---------------- -- cgit v1.2.1 From 59b205027d116ad96d719cd1f9968120a64b4747 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 21:28:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2163 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/cheatsheet.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt index 21a694ede..c0edf88c9 100644 --- a/docs/user/rst/cheatsheet.txt +++ b/docs/user/rst/cheatsheet.txt @@ -85,6 +85,7 @@ rubric ``.. rubric:: Informal Heading`` epigraph Block quote with class="epigraph" highlights Block quote with class="highlights" pull-quote Block quote with class="pull-quote" +table Create a titled table contents Generate a table of contents sectnum Automatically number sections, subsections, etc. target-notes Create an explicit footnote for each external target -- cgit v1.2.1 From b94c294c2abc80d523762018c6a902bfde8661fc Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 1 Jun 2004 21:39:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4350a61a5..e72ba1911 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1018,8 +1018,6 @@ when used in a document. - All directives that produce titled elements should grow implicit reference names based on the titles. - - @ _`body.table`: Document, add tests. - - _`images.image`: "border"? _`Units of measure`? (See `docutils-users, 2003-03-02 -- cgit v1.2.1 From 07652bb75e589e82adec3a89c547e8473f495410 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 2 Jun 2004 14:27:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2166 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e72ba1911..9119f941f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -2072,6 +2072,25 @@ to completion. .. _Docutils Configuration Files: ../docs/config.txt +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 ``````````````````````````````````` -- cgit v1.2.1 From 30f3875d81e16c2377b20758e990b6d2f86ef98d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 03:47:04 +0000 Subject: Docutils Project Documentation Overview git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2171 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 181 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/index.txt (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 000000000..2fca4707f --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,181 @@ +========================================= + Docutils Project Documentation Overview +========================================= + +:Date: $Date$ +:Revision: $Revision$ + +The latest working documents may be accessed individually below, or +from the ``docs`` directory of the `development snapshots`__. They +are also distributed with the `latest project release package`__, but +those may not be completely up to date. + +__ ../index.html#development-snapshots +__ ../index.html#latest-project-release-package + + +.. contents:: + + +Docutils Stakeholders +===================== + +There are several distinct groups of Docutils stakeholders: + +1. End-users: users of reStructuredText and the Docutils tools. + Although some are developers (e.g. Python developers utilizing + reStructuredText for docstrings in their source), many are not. + +2. Client-developers: developers using Docutils as a library, + programmers developing *with* Docutils. + +3. Component-developers: those who implement application-specific + components, directives, and/or roles, without contributing them + back to Docutils. + +4. Core-developers: developers of the Docutils codebase and + participants in the Docutils project community. + +5. Re-implementers: developers of alternate implementations of + Docutils. + +There's a lot of overlap between these groups. Most (perhaps all) +core-developers, component-developers, client-developers, and +re-implementers are also end-users. Core-developers are also +library-user/developers, and may also be component-developers in other +projects. Component-developers are also client-developers. + + +Project Fundamentals +==================== + +These files are for all Docutils stakeholders. They are kept at the +top level of the Docutils project directory. + +:README.txt_: Project overview: quick-start, requirements, + installation, and usage. +:COPYING.txt_: Conditions for Docutils redistribution, with links to + licenses. +:FAQ.txt_: Docutils Frequently Asked Questions. If you have a + question or issue, there's a good chance it's already + answered here. Please take a look. +:BUGS.txt_: A list of known bugs, and how to report a bug. +:HISTORY.txt_: Change history log. +:THANKS.txt_: Acknowledgements. + +.. _README.txt: ../README.html +.. _BUGS.txt: ../BUGS.html +.. _COPYING.txt: ../COPYING.html +.. _Docutils FAQ: +.. _FAQ.txt: ../FAQ.html +.. _HISTORY.txt: ../HISTORY.html +.. _THANKS.txt: ../THANKS.html + + +``user/``: Introductory/Tutorial Material for End-Users +======================================================= + +Docutils-general: + +* `Docutils Front-End Tools <user/tools.html>`__ +* `Docutils Configuration Files <user/config.html>`__ +* `Docutils LaTeX Writer <user/latex.html>`__ + +`reStructuredText <../rst.html>`_: + +* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or + `text source <user/rst/quickstart.txt>`__) +* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference) +* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text + only; 1 page for syntax, 1 page directive & role reference) + + +``ref/``: Reference Material for All Groups +=========================================== + +Many of these files began as developer specifications, but now that +they're mature and used by end-users and client-developers, they have +become reference material. Successful specs evolve into refs. + +Docutils-general: + +* `The Docutils Document Tree <ref/doctree.html>`__ (incomplete) +* `Docutils Transforms <ref/transforms.html>`__ +* `Docutils Generic DTD <ref/docutils.dtd>`__ +* `OASIS XML Exchange Table Model Declaration Module + <ref/soextblx.dtd>`__ (CALS tables DTD module) + +Although not in the "ref" directory, `PEP 258 <peps/pep-0258.html>`_ +is a must-read reference for any Docutils developer. + +reStructuredText_: + +* `An Introduction to reStructuredText <ref/rst/introduction.html>`__ + (includes the `Goals <ref/rst/introduction.html#goals>`__ and + `History <ref/rst/introduction.html#history>`__ of reStructuredText) +* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__ +* `reStructuredText Directives <ref/rst/directives.html>`__ +* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__ + + +``howto/``: Instructions for Component-Developers and Core-Developers +===================================================================== + +* `Docutils Internationalization <howto/i18n.html>`__ +* `Creating reStructuredText Directives <howto/rst-directives.html>`__ +* `Creating reStructuredText Interpreted Text Roles + <howto/rst-roles.html>`__ + + +``peps/``: Python Enhancement Proposals +======================================= + +* `PEP 256: Docstring Processing System Framework`__ is a high-level + generic proposal. [`PEP 256`__ in the `master repository`_] +* `PEP 257: Docstring Conventions`__ addresses docstring style and + touches on content. [`PEP 257`__ in the `master repository`_] +* `PEP 258: Docutils Design Specification`__ documents design issues + and implementation details for Docutils (this project), a specific + docstring processing system. [`PEP 258`__ in the `master + repository`_] +* `PEP 287: reStructuredText Docstring Format`__ proposes a standard + markup syntax. [`PEP 287`__ in the `master repository`_] + +Please note that PEPs in the `master repository`_ may not be current, +whereas the local versions are. + +__ peps/pep-0287.html +__ http://www.python.org/peps/pep-0287.html +__ peps/pep-0257.html +__ http://www.python.org/peps/pep-0257.html +__ peps/pep-0256.html +__ http://www.python.org/peps/pep-0256.html +__ peps/pep-0258.html +__ http://www.python.org/peps/pep-0258.html + + +``dev/``: Development Notes and Plans for Core-Developers +========================================================= + +Docutils-general: + +* `The Docutils To Do List <dev/todo.html>`__ +* `Docutils Project Policies <dev/policies.html>`__ +* `Docstring Semantics <dev/semantics.html>`__ (incomplete) +* `Python Source Reader <dev/pysource.html>`_ (incomplete) +* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) + +reStructuredText_: + +* `A Record of reStructuredText Syntax Alternatives + <dev/rst/alternatives.html>`__ +* `Problems With StructuredText <dev/rst/problems.html>`__ + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: -- cgit v1.2.1 From ff74b373fbff5c74f297c2cf0406156ff3e0aefe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 03:49:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2172 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 68 ------------------------------------------------------- 1 file changed, 68 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 9119f941f..77aece7d2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -395,74 +395,6 @@ General Documentation ------------- -* .. _documentation cleanup: - - The documentation is currently messed up. These are the plans for - an overall cleanup: - - - Create new subdirectories of docs/: - - * ``docs/user/``: introductory/tutorial material for end-users - * ``docs/dev/``: for core-developers (development notes, plans, etc.) - * ``docs/ref/``: reference material for all groups - * ``docs/howto/``: for component-developers and core-developers - * ``docs/peps/``: Python Enhancement Proposals - - - Move ``docs/*`` to ``docs/user/``. - - - Move ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from - ``spec/`` to ``docs/dev``. - - - Move ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd``, - ``transforms.txt`` from ``spec/`` to ``docs/ref/``. - - - Move ``alternatives.txt``, and ``problems.txt`` from ``spec/rst/`` - to ``docs/dev/rst/``. (Move "Doctree Representation of - Transitions" section of ``alternatives.txt`` elsewhere? [Not - yet.]) - - - Move ``reStructuredText.txt``, ``directives.txt``, - ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/`` - to ``docs/ref/rst/``. Rename ``interpreted.txt`` to - ``roles.txt``. Rename ``reStructuredText.txt`` to - ``restructuredtext.txt``. - - - Move ``spec/howto/`` to ``docs/howto``. - (Not to ``docs/dev/howto/``; not just for core-developers.) - - In order to keep the CVS history of moved files, we need to supply - SourceForge with a `script for modifying the Docutils CVS - repository`__. Any other pending repository cleanups should be done - at the same time. Script now in CVS: - `sandbox/davidg/infrastructure/cvs-reorg.sh`__. - - __ http://sf.net/docman/display_doc.php?docid=768&group_id=1#repositoryrestructure - __ http://docutils.sourceforge.net/sandbox/davidg/infrastructure/cvs-reorg.sh - - After doing the cleanup (running the cvs-reorg.sh script): - - - Add ``docs/index.txt``. - - - Add 'how to report bugs' to ``BUGS.txt`` (like `Subversion's - <http://svn.collab.net/viewcvs/svn/trunk/BUGS?rev=9086&view=markup>`__). - - - Move 'Future Plans' from ``HISTORY.txt`` to new 'Priorities' - section of ``docs/dev/todo.txt``. - - - Add ``THANKS.txt`` from 'Acknowledgements' in ``HISTORY.txt``. - - - Add ``BUGS.txt``, ``docs/dev/policies.txt``, - ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but - the "to do" list in ``docs/dev/todo.txt``. - - - Add a ``.htaccess`` file to the ``web`` module containing - redirects from all old paths to new paths. They'll preserve - fragments (the "#name" part of a URL), and won't clutter up the - file system, and will correct the URL in the user's browser. - - - Go through all the docs (including under web/) & code and update - links. - * User docs. What's needed? -- cgit v1.2.1 From 126aa312db806edd54ffa21af269d71b624cbfb0 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 03:55:04 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2174 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index 2fca4707f..71bee5c67 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -152,6 +152,7 @@ __ peps/pep-0256.html __ http://www.python.org/peps/pep-0256.html __ peps/pep-0258.html __ http://www.python.org/peps/pep-0258.html +.. _master repository: http://www.python.org/peps/ ``dev/``: Development Notes and Plans for Core-Developers -- cgit v1.2.1 From 558d61d2593dfab29cfef0a8ddbfc885ef024ab7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 04:58:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2176 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index 71bee5c67..85f5df213 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -160,8 +160,10 @@ __ http://www.python.org/peps/pep-0258.html Docutils-general: -* `The Docutils To Do List <dev/todo.html>`__ +* `Docutils To Do List <dev/todo.html>`__ * `Docutils Project Policies <dev/policies.html>`__ +* `Docutils Web Site <dev/website.html>`__ +* `Docutils Release Procedure <dev/release.html>`__ * `Docstring Semantics <dev/semantics.html>`__ (incomplete) * `Python Source Reader <dev/pysource.html>`_ (incomplete) * `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) -- cgit v1.2.1 From 35842c18be940c4d05f445ee0e619a181469a502 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 14:10:05 +0000 Subject: Added to project (extracted from ``docs/dev/todo.txt``, formerly ``spec/notes.txt``) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2183 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/policies.txt | 401 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/dev/release.txt | 130 ++++++++++++++++ docs/dev/website.txt | 42 ++++++ 3 files changed, 573 insertions(+) create mode 100644 docs/dev/policies.txt create mode 100644 docs/dev/release.txt create mode 100644 docs/dev/website.txt (limited to 'docs') diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt new file mode 100644 index 000000000..801ca028e --- /dev/null +++ b/docs/dev/policies.txt @@ -0,0 +1,401 @@ +=========================== + Docutils Project Policies +=========================== + +:Author: David Goodger; open to all Docutils developers +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This document has been placed in the public domain. + + +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 <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, +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 + +* 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/ + + +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: ../docs/tools.html +.. _Docutils Configuration Files: ../docs/config.txt + + +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@python.org). +* Docutils-develop__, for implementation discussions + (email to docutils-develop@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: diff --git a/docs/dev/release.txt b/docs/dev/release.txt new file mode 100644 index 000000000..3be30bec6 --- /dev/null +++ b/docs/dev/release.txt @@ -0,0 +1,130 @@ +============================= + Docutils_ Release Procedure +============================= +:Author: David Goodger; open to all Docutils developers +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +: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@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@lists.sourceforge.net + * docutils-users@lists.sourceforge.net + * doc-sig@python.org + * python-list@python.org + * python-announce@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: diff --git a/docs/dev/website.txt b/docs/dev/website.txt new file mode 100644 index 000000000..73ef8b10f --- /dev/null +++ b/docs/dev/website.txt @@ -0,0 +1,42 @@ +=================== + Docutils Web Site +=================== +:Author: David Goodger; open to all Docutils developers +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +: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: -- cgit v1.2.1 From 987f1dc271eeab1ed3bbbd703bc13364307db53b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 14:10:28 +0000 Subject: extracted parts to docs/dev/policies.txt, docs/dev/release.txt, docs/dev/website.txt, and BUGS.txt git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2184 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 619 ++---------------------------------------------------- 1 file changed, 17 insertions(+), 602 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 77aece7d2..600c84f53 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1,8 +1,9 @@ -================= - Docutils_ Notes -================= -:Author: David Goodger (with input from many) -:Contact: goodger@users.sourceforge.net +====================== + Docutils_ To Do List +====================== +:Author: David Goodger (with input from many); open to all Docutils + developers +:Contact: goodger@python.org :Date: $Date$ :Revision: $Revision$ :Copyright: This document has been placed in the public domain. @@ -12,9 +13,6 @@ .. contents:: -To Do -===== - 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. @@ -23,80 +21,23 @@ Many of these items are awaiting champions. If you see something you'd like to tackle, please do! -Bugs ----- - -Also see the `SourceForge Bug Tracker`__. - -__ http://sourceforge.net/tracker/?group_id=38414&atid=422030 - -* 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. - -* In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need "source" and "line" keyword arguments. - Elements' .line assignments should be checked. (Assign to .source - too? Add a set_info method? To what?) There's a test in - test/test_parsers/test_rst/test_directives/test_include.py. - -* Explicit targets are sometimes mis-located. In particular, placing - a target before a section header puts the target at the end of the - previous section instead of the start of the next section. The code - in docutils.transforms.misc.ClassAttribute could be used to fix - this. (Reported by David Priest.) - -* Upon reviewing RFC 2396, I see that asterisks are valid URL - characters, sometimes actually used. Beni Cherniavsky found one in - mid-November and fixed it by modifying the text. There's a conflict - with emphasis, but backslash escapes should overcome that; they - don't though. I consider it a bug in the parser that escaped - asterisks in URLs aren't recognized. Here's the URL that broke:: - - http://cvs.sf.net/viewcvs.py/*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD - - We should be able to escape the first asterisk like this:: - - http://cvs.sf.net/viewcvs.py/\*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD - -* Document title should grow an implicit target. +Priorities +========== -* David Abrahams pointed out that doubly-indirect substitutions have a - bug, but only when there's multiple references:: +* Include substitution files for character entities, produced by the + tools/unicode2rstsubs.py. As static data, these files could go + inside the docutils package somewhere. - |substitute| my coke for gin - |substitute| you for my mum - at least I'll get my washing done +* Rename front-end tools (perhaps to "rst2*" pattern) and have + setup.py install them. - .. |substitute| replace:: |replace| - .. |replace| replace:: swap - - This is tricky. Substitutions have to propagate back completely. - -* Another bug from David Abrahams (run with ``rst2html.py --traceback``):: - - .. [#crtp] See |runtime| - - foo [#tag_dispatching]_ - - .. [#tag_dispatching] See |runtime| - - .. |runtime| replace:: 7__ - __ runtime.html - - __ reference/__main.html - - Change the references.Substitutions tranform's priority from 220 to - 680, so it happens after reference resolution? Then we have to deal - with multiple IDs. Perhaps the Substitution transform should remove - all IDs from definitions after the first substitution reference is - processed. +* A Python Source Reader component (Python auto-documentation) will be + added as soon as there's enough time, effort, and will. If you'd + like to help, let me know! General -------- +------- <<<<<<<<<<<<<<<<< * Refactor @@ -1788,532 +1729,6 @@ Front-End Tools * Create a single dynamic_ or unqualified_ front end that can be installed? - -Project Policies -================ - -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 <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, -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 - -* 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/ - - -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: ../docs/tools.html -.. _Docutils Configuration Files: ../docs/config.txt - - -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@python.org). -* Docutils-develop__, for implementation discussions - (email to docutils-develop@lists.sourceforge.net). -* Docutils-checkins__, to monitor CVS checkin messages (automatically - generated; normally read-only). - -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins - - -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. - - -Web Site -======== - -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 - - -Release Procedure -================= - -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@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@lists.sourceforge.net - * docutils-users@lists.sourceforge.net - * doc-sig@python.org - * python-list@python.org - * python-announce@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: -- cgit v1.2.1 From 6596a6eb2afc97566cfe47b2f4217a71a0f8e51d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 14:11:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2185 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index 85f5df213..81594e984 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -2,8 +2,11 @@ Docutils Project Documentation Overview ========================================= +:Author: David Goodger +:Contact: goodger@python.org :Date: $Date$ :Revision: $Revision$ +:Copyright: This document has been placed in the public domain. The latest working documents may be accessed individually below, or from the ``docs`` directory of the `development snapshots`__. They -- cgit v1.2.1 From 32ffcbf8030e285a2d05429f9b9fa3678ebd19b4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 14:21:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2186 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 153 +++++++++++++++++++++++++----------------------------- 1 file changed, 70 insertions(+), 83 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 600c84f53..f69101def 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1,6 +1,7 @@ ====================== Docutils_ To Do List ====================== + :Author: David Goodger (with input from many); open to all Docutils developers :Contact: goodger@python.org @@ -37,12 +38,12 @@ Priorities General -------- <<<<<<<<<<<<<<<<< +======= * Refactor - Rename methods & variables according to the `Python coding - conventions`_ below. + 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 @@ -66,7 +67,7 @@ General with new entries. ("Persistent ID mapping"?) * Need a Unicode to HTML entities codec for HTML writer? No, the - "xmlcharrefreplace" output encoding error handler is sufficient. + "xmlcharrefreplace" output error handler is sufficient. Make it the default for HTML & XML writers? * Perhaps the ``Component.supports`` method should deal with @@ -334,13 +335,13 @@ General Documentation -------------- +============= * User docs. What's needed? Implementation Docs -``````````````````` +------------------- * Internal module documentation (docstrings). @@ -363,7 +364,7 @@ Implementation Docs Specification -````````````` +------------- * Complete PEP 258 Docutils Design Specification. @@ -381,7 +382,7 @@ Specification Python Source Reader --------------------- +==================== General: @@ -481,7 +482,7 @@ Miscellaneous ideas: reStructuredText Parser ------------------------ +======================= Also see the `... Or Not To Do?`__ list. @@ -850,7 +851,7 @@ __ rst/alternatives.html#or-not-to-do * _`Segmented lists`:: : segment : segment : segment - : segment : segment : very long + : segment : segment : very long segment : segment : segment : segment @@ -867,7 +868,7 @@ __ rst/alternatives.html#or-not-to-do Directives -`````````` +---------- Directives below are often referred to as "module.directive", the directive function. The "module." is not part of the directive name @@ -1286,7 +1287,7 @@ when used in a document. - On a stick! Issues: - + * How to indicate that there's 1 header row? Perhaps two lists? :: @@ -1391,7 +1392,7 @@ when used in a document. Interpreted Text -```````````````` +---------------- Interpreted text is entirely a reStructuredText markup construct, a way to get around built-in limitations of the medium. Some roles are @@ -1541,100 +1542,86 @@ elements. 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: +* _`Footnote & Citation Gathering` -* duplicate reference and/or substitution names that need to be made - unique; and/or -* duplicate footnote numbers that need to be renumbered. + Collect and move footnotes & citations to the end of a document. + (Separate transforms.) -Should this be done before or after reference-resolving transforms -are applied? What about references from within one subdocument to -inside another? +* _`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. -Document Splitting -`````````````````` +* _`Reference Merging` -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. + When merging two or more subdocuments (such as docstrings), + conflicting references may need to be resolved. There may be: -(HTML only? Initially, yes. Eventually, anything should be -splittable.) + * duplicate reference and/or substitution names that need to be made + unique; and/or + * duplicate footnote numbers that need to be renumbered. -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. + Should this be done before or after reference-resolving transforms + are applied? What about references from within one subdocument to + inside another? +* _`Document Splitting` -Navigation -`````````` + 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. -If a document is split up, each segment will need navigation links: -parent, children (small TOC), previous (preorder), next (preorder). -Part of `Document Splitting`_? + (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. -List of System Messages -``````````````````````` +* _`Navigation` -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". + If a document is split up, each segment will need navigation links: + parent, children (small TOC), previous (preorder), next (preorder). + Part of `Document Splitting`_? -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. +* _`List of System Messages` -Fred L. Drake, Jr. wrote: + 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". - 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. + 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. -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). + 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. -Others -`````` + 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 +* _`Index Generation` HTML Writer ------------ +=========== * Construct a _`templating system`, as in ht2html/yaptu, using directives and substitutions for dynamic stuff? Or a specialized @@ -1677,7 +1664,7 @@ HTML Writer 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 -- cgit v1.2.1 From a6baa560562a76ae915bdbea2dd8e78eef79c5cd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 15:19:49 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2188 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/policies.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt index 801ca028e..d3c311cf3 100644 --- a/docs/dev/policies.txt +++ b/docs/dev/policies.txt @@ -8,6 +8,7 @@ :Revision: $Revision$ :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 -- cgit v1.2.1 From 5d6ae98dbb5bdaeaf2e679f63d792fadea522a60 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:29:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2190 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index f72f8f140..fb8661789 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -44,8 +44,8 @@ ReStructuredText Primer`_. For complete technical details, see the .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: ../docs/rst/quickstart.html -.. _reStructuredText Markup Specification: rst/reStructuredText.html +.. _A ReStructuredText Primer: ../user/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/restructuredtext.html ------------------- -- cgit v1.2.1 From 72a3cc815ed28998d2e6483ac6778e071cd72627 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:40:54 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2191 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 3b195e139..0fb0d65e2 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -166,9 +166,12 @@ be overridden by command-line options or configuration files. The "``tools/stylesheets/pep.css``" stylesheet is intended specifically for PEP use. +.. XXX the docutils.conf in spec/ was next to the PEPs. Now it's + gone; there is no docutils.conf in docs/peps/. + The "``docutils.conf``" `configuration file`_ in the "``spec``" directory of Docutils contains a default setup for use in processing -the PEP files there (``spec/pep-*.txt``) into HTML. It specifies a +the PEP files there (``docs/peps/pep-*.txt``) into HTML. It specifies a default template (``tools/pep-html-template``) and a default stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above for more information. -- cgit v1.2.1 From 0890f4ef7aaedd7fbbcf1c97f8fd9e537e5c02b5 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:49:04 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/policies.txt | 4 ++-- docs/ref/doctree.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt index d3c311cf3..6a21291e8 100644 --- a/docs/dev/policies.txt +++ b/docs/dev/policies.txt @@ -218,8 +218,8 @@ 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: ../docs/tools.html -.. _Docutils Configuration Files: ../docs/config.txt +.. _Docutils Front-End Tools: ../user/tools.html +.. _Docutils Configuration Files: ../user/config.html CVS Startup File diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index fb8661789..4be13e81d 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -4041,8 +4041,8 @@ immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. -__ rst/alternatives.txt#doctree-representation-of-transitions -__ rst/alternatives.txt +__ ../dev/rst/alternatives.txt#doctree-representation-of-transitions +__ ../dev/rst/alternatives.txt Details -- cgit v1.2.1 From 14e4571c1eeaf8cf8824f45509d11da5cb5b1527 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 16:57:26 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2194 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f69101def..5575d9edb 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -345,10 +345,10 @@ Implementation Docs * Internal module documentation (docstrings). -* spec/doctree.txt: DTD element structural relationships, semantics, +* ../ref/doctree.txt: DTD element structural relationships, semantics, and attributes. In progress; element descriptions to be completed. -* How-to docs: In spec/howto/. +* How-to docs: In docs/howto/. - How a Writer works & how to write one @@ -779,7 +779,7 @@ __ rst/alternatives.html#or-not-to-do * Add new syntax for _`nested inline markup`? Or extend the parser to parse nested inline markup somehow? See the `collected notes - <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. + <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? :: -- cgit v1.2.1 From 05aabf41e9ed2e35a6996f1e66b8f8ced70b2def Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:07:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2195 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/doctree.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt index 4be13e81d..5959849e4 100644 --- a/docs/ref/doctree.txt +++ b/docs/ref/doctree.txt @@ -1581,7 +1581,7 @@ Details complete details, please see `RCS Keywords`_ in the `reStructuredText Markup Specification`_. - .. _RCS Keywords: rst/reStructuredText.html#rcs-keywords + .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords Content Model @@ -4041,8 +4041,8 @@ immediately adjacent. See `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. -__ ../dev/rst/alternatives.txt#doctree-representation-of-transitions -__ ../dev/rst/alternatives.txt +__ ../dev/rst/alternatives.html#doctree-representation-of-transitions +__ ../dev/rst/alternatives.html Details -- cgit v1.2.1 From 55804f23231f53831e2d812e7dc74caf79a54972 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:25:41 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2196 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 11 +++++------ docs/dev/rst/problems.txt | 3 ++- docs/dev/todo.txt | 11 +++++------ 3 files changed, 12 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 7e60cc025..3bd60c258 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1540,8 +1540,7 @@ __ http://thread.gmane.org/gmane.text.docutils.devel/1386 verbose; excessive punctuation is required to get the job done. For more of the reasoning behind the syntax, see `Problems With - StructuredText (Hyperlinks) - <http://docutils.sf.net/spec/rst/problems.html#hyperlinks>`__ and + StructuredText (Hyperlinks) <problems.html#hyperlinks>`__ and `Reworking Footnotes`_. 2. "I expect directives to also look like ``.. this:`` [one colon] @@ -1565,7 +1564,8 @@ __ http://thread.gmane.org/gmane.text.docutils.devel/1386 directive block (including the directive itself) will be included as a literal block. Thus "::" is a natural choice. - -- http://docutils.sf.net/spec/rst/reStructuredText.html#directives + -- `restructuredtext.html#directives + <../../ref/rst/restructuredtext.html#directives>`__ The last reason is not particularly compelling; it's more of a convenient coincidence or mnemonic. @@ -1615,8 +1615,7 @@ __ http://thread.gmane.org/gmane.text.docutils.devel/1386 aspect, but ".. comment::" would certainly detract from the latter. .. _author's note: - .. _reStructuredText's goals: - http://docutils.sf.net/spec/rst/introduction.html#goals + .. _reStructuredText's goals: ../../ref/rst/introduction.html#goals 5. "Recently I sent someone an rst document, and they got confused; I had to explain to them that '..' marks comments, *unless* it's a @@ -2404,7 +2403,7 @@ something different). The `"role" directive`__ has been implemented. -__ http://docutils.sf.net/spec/rst/directives.html#role +__ ../../ref/rst/directives.html#role Character Processing diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index a8747af88..9fcdf6d2a 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -858,7 +858,8 @@ cleanly readable text. .. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/ python/python/dist/src/README .. _Emacs table mode: http://table.sourceforge.net/ -.. _reStructuredText Markup Specification: reStructuredText.html +.. _reStructuredText Markup Specification: + ../../ref/rst/restructuredtext.html .. diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5575d9edb..8e1ed8d67 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1416,11 +1416,10 @@ 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 -spec/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. +<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: @@ -1513,7 +1512,7 @@ elements. trigger warnings, similar to the rules of `implicit hyperlink targets`__. - __ rst/reStructuredText.html#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 -- cgit v1.2.1 From e24803d012f4cb591d207ef22b535feeeda788fe Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:36:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2197 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8e1ed8d67..3da3ec83b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -345,8 +345,9 @@ Implementation Docs * Internal module documentation (docstrings). -* ../ref/doctree.txt: DTD element structural relationships, semantics, - and attributes. In progress; element descriptions to be completed. +* docs/ref/doctree.txt: DTD element structural relationships, + semantics, and attributes. In progress; element descriptions to be + completed. * How-to docs: In docs/howto/. -- cgit v1.2.1 From b98a8f5204104fe344e6c262031812f66ae09756 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:36:35 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2198 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 5 +++-- docs/howto/rst-directives.txt | 4 ++-- docs/howto/rst-roles.txt | 8 +++++--- docs/ref/rst/directives.txt | 9 +++++---- 4 files changed, 15 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 3bd60c258..c9070712e 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -18,7 +18,8 @@ for full details of the established syntax. .. _StructuredText: http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _Problems with StructuredText: problems.html -.. _reStructuredText Markup Specification: reStructuredText.html +.. _reStructuredText Markup Specification: + ../../ref/rst/restructuredtext.html .. contents:: @@ -2452,7 +2453,7 @@ further character processing will be of this functional type, rather than of the character-encoding type. .. _character-level inline markup: - reStructuredText.html#character-level-inline-markup + ../../ref/rst/restructuredtext.html#character-level-inline-markup * Directive idea:: diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index f44dbc07c..14a73b951 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -19,8 +19,8 @@ Specification`_, and standard directives are described in `reStructuredText Directives`_. .. _reStructuredText Markup Specification: - ../rst/reStructuredText.html#directives -.. _reStructuredText Directives: ../rst/directives.html + ../ref/rst/restructuredtext.html#directives +.. _reStructuredText Directives: ../ref/rst/directives.html .. contents:: Table of Contents diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt index 634dbcc68..bda9a6433 100644 --- a/docs/howto/rst-roles.txt +++ b/docs/howto/rst-roles.txt @@ -16,9 +16,11 @@ Standard roles are described in `reStructuredText Interpreted Text Roles`_. See the `Interpreted Text`_ section in the `reStructuredText Markup Specification`_ for syntax details. -.. _reStructuredText Interpreted Text Roles: ../rst/interpreted.html -.. _Interpreted Text: ../rst/reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: ../rst/reStructuredText.html +.. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html +.. _Interpreted Text: + ../ref/rst/restructuredtext.html#interpreted-text +.. _reStructuredText Markup Specification: + ../ref/rst/restructuredtext.html .. contents:: diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt index b75f52e51..b9ea19ccd 100644 --- a/docs/ref/rst/directives.txt +++ b/docs/ref/rst/directives.txt @@ -36,11 +36,12 @@ Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document type definition. For directive implementation details, see `Creating reStructuredText Directives`_. -.. _Directives: reStructuredText.html#directives -.. _reStructuredText Markup Specification: reStructuredText.html +.. _Directives: restructuredtext.html#directives +.. _reStructuredText Markup Specification: restructuredtext.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Directives: ../howto/rst-directives.html +.. _Creating reStructuredText Directives: + ../../howto/rst-directives.html ------------- @@ -1082,7 +1083,7 @@ Specific roles may support other options and/or directive content. See the `reStructuredText Interpreted Text Roles`_ document for details. -.. _reStructuredText Interpreted Text Roles: interpreted.html +.. _reStructuredText Interpreted Text Roles: roles.html Restructuredtext-Test-Directive -- cgit v1.2.1 From ac0e496a22d643632293773e7cadf4a924eecdcf Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:47:43 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2199 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/introduction.txt | 19 +++++++++---------- docs/ref/rst/roles.txt | 7 ++++--- docs/user/rst/quickstart.txt | 6 +++--- 3 files changed, 16 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt index 13823b5b7..2b64399a5 100644 --- a/docs/ref/rst/introduction.txt +++ b/docs/ref/rst/introduction.txt @@ -34,10 +34,10 @@ http://docutils.sourceforge.net/rst.html. http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/rst/quickref.html -.. _reStructuredText Markup Specification: reStructuredText.html -.. _Problems with StructuredText: problems.html +.. _A ReStructuredText Primer: ../../user/rst/quickstart.html +.. _Quick reStructuredText: ../../user/rst/quickref.html +.. _reStructuredText Markup Specification: restructuredtext.html +.. _Problems with StructuredText: ../../dev/rst/problems.html Goals @@ -281,8 +281,8 @@ followed. - `PEP 257: Docstring Conventions`__ Current working versions of the PEPs can be found in - http://docutils.sourceforge.net/spec/, and official versions can be - found in the `master PEP repository`_. + http://docutils.sourceforge.net/docs/peps/, and official versions + can be found in the `master PEP repository`_. __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html @@ -296,10 +296,9 @@ followed. .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ .. _StructuredTextNG: http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: http://docutils.sourceforge.net/HISTORY.html -.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.html -.. _Docstring Processing System framework: - http://docutils.sourceforge.net/spec/pep-0256.html +.. _project history file: ../../../HISTORY.html +.. _PEP 287: ../../peps/pep-0287.html +.. _Docstring Processing System framework: ../../peps/pep-0256.html .. _comp.lang.python: news:comp.lang.python .. _Python-dev: http://mail.python.org/pipermail/python-dev/ .. _Docstring Processing System: http://docstring.sourceforge.net/ diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index d93a2bf9d..f619aae03 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -30,11 +30,12 @@ implementation details, see `Creating reStructuredText Interpreted Text Roles`_. .. _"role" directive: directives.html#role -.. _Interpreted Text: reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: reStructuredText.html +.. _Interpreted Text: restructuredtext.html#interpreted-text +.. _reStructuredText Markup Specification: restructuredtext.html .. _The Docutils Document Tree: ../doctree.html .. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Interpreted Text Roles: ../howto/rst-roles.html +.. _Creating reStructuredText Interpreted Text Roles: + ../../howto/rst-roles.html .. contents:: diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index d36326473..f17ff8803 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -16,7 +16,7 @@ quick reference`_ document. __ .. _Quick reStructuredText: quickref.html .. _master quick reference: - http://docutils.sourceforge.net/docs/rst/quickref.html + http://docutils.sourceforge.net/docs/user/rst/quickref.html Structure @@ -380,10 +380,10 @@ mailing list`_. The `Docutils project web site`_ has more information. .. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html. + http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. .. _reStructuredText Markup Specification: - ../../spec/rst/reStructuredText.html + ../../ref/rst/restructuredtext.html .. _post a message: mailto:docutils-users@lists.sourceforge.net .. _Docutils-Users mailing list: http://lists.sourceforge.net/lists/listinfo/docutils-users -- cgit v1.2.1 From b447165077e564a25c8d788a45000fd0b5e5ef27 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 17:52:31 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2200 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/roles.txt | 6 +++--- docs/user/rst/cheatsheet.txt | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt index f619aae03..4aa6b0337 100644 --- a/docs/ref/rst/roles.txt +++ b/docs/ref/rst/roles.txt @@ -191,9 +191,9 @@ Implements subscripts. See `the reStructuredText spec`__ for further information on `character-level markup`__ and `the substitution mechanism`__. - __ ./reStructuredText.html - __ ./reStructuredText.html#character-level-inline-markup - __ ./reStructuredText.html#substitution-references + __ restructuredtext.html + __ restructuredtext.html#character-level-inline-markup + __ restructuredtext.html#substitution-references ``:superscript:`` diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt index c0edf88c9..79322025a 100644 --- a/docs/user/rst/cheatsheet.txt +++ b/docs/user/rst/cheatsheet.txt @@ -50,7 +50,7 @@ Citation .. [CIT2002] A citation. Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html .. _indirect target: reStructuredText_ .. _internal target: -Anonymous Target __ http://docutils.sf.net/spec/rst/reStructuredText.html +Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html Directive ("::") .. image:: images/biohazard.png Substitution Def .. |substitution| replace:: like an inline directive Comment .. is anything else -- cgit v1.2.1 From 64033c609954c8f759f7c25b6482a0b592803319 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 18:00:56 +0000 Subject: updated (there hasn't been a spec/docutils.conf file since July 2002\!) git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2201 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 0fb0d65e2..3fdc9491e 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -166,16 +166,26 @@ be overridden by command-line options or configuration files. The "``tools/stylesheets/pep.css``" stylesheet is intended specifically for PEP use. -.. XXX the docutils.conf in spec/ was next to the PEPs. Now it's - gone; there is no docutils.conf in docs/peps/. - -The "``docutils.conf``" `configuration file`_ in the "``spec``" +The "``docutils.conf``" `configuration file`_ in the "``tools``" directory of Docutils contains a default setup for use in processing -the PEP files there (``docs/peps/pep-*.txt``) into HTML. It specifies a +the PEP files (``docs/peps/pep-*.txt``) into HTML. It specifies a default template (``tools/pep-html-template``) and a default stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above for more information. +``pep.py`` can be run from the ``tools`` directory or from the +``docs/peps/`` directory, by adjusting the settings. These two sets +of commands are equivalent:: + + cd <path-to-docutils>/tools + # This will pick up the "docutils.conf" file automatically: + pep.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html + + cd <path-to-docutils>/docs/peps + # Must tell the tool where to find the config file: + ../../tools/pep.py --config ../../tools/docutils.conf \ + pep-0287.txt pep-0287.html + pep2html.py ----------- -- cgit v1.2.1 From 27aa4684460f1798a91ed44ff6557f67a45548c6 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 18:27:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2202 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 5 +++-- docs/peps/pep-0287.txt | 18 +++++++++--------- 2 files changed, 12 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index c76920995..2c012a7b4 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -470,7 +470,8 @@ Front-End Tools The ``tools/`` directory contains several front ends for common Docutils processing. See `Docutils Front-End Tools`_ for details. -.. _Docutils Front-End Tools: http://docutils.sf.net/docs/tools.html +.. _Docutils Front-End Tools: + http://docutils.sourceforge.net/docs/user/tools.html Document Tree @@ -954,7 +955,7 @@ stylist code will lower the barrier considerably. .. _soextbl.dtd: http://docutils.sourceforge.net/spec/soextblx.dtd .. _The Docutils Document Tree: - http://docutils.sourceforge.net/spec/doctree.html + http://docutils.sourceforge.net/docs/ref/doctree.html .. _VMS error condition severity levels: http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt index c6e48901b..d22efe224 100644 --- a/docs/peps/pep-0287.txt +++ b/docs/peps/pep-0287.txt @@ -513,7 +513,7 @@ Questions & Answers See `Section Structure via Indentation`__ in `Problems With StructuredText`_ for further elaboration. - __ http://docutils.sourceforge.net/spec/rst/problems.html + __ http://docutils.sourceforge.net/docs/dev/rst/problems.html #section-structure-via-indentation 4. Why use reStructuredText for PEPs? What's wrong with the existing @@ -741,7 +741,7 @@ __ http://www.python.org/doc/Humor.html#zen .. [#PEP-216] PEP 216, Docstring Format, Zadka (http://www.python.org/peps/pep-0216.html) -.. _reStructuredText markup: http://docutils.sourceforge.net/spec/rst.html +.. _reStructuredText markup: http://docutils.sourceforge.net/rst.html .. _Doc-SIG: http://www.python.org/sigs/doc-sig/ @@ -767,25 +767,25 @@ __ http://www.python.org/doc/Humor.html#zen http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage .. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/rst/quickstart.html + http://docutils.sourceforge.net/docs/user/rst/quickstart.html .. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/rst/quickref.html + http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/spec/rst/introduction.html + http://docutils.sourceforge.net/docs/ref/rst/introduction.html .. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html + http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html .. _reStructuredText Directives: - http://docutils.sourceforge.net/spec/rst/directives.html + http://docutils.sourceforge.net/docs/ref/rst/directives.html .. _Problems with StructuredText: - http://docutils.sourceforge.net/spec/rst/problems.html + http://docutils.sourceforge.net/docs/dev/rst/problems.html .. _A Record of reStructuredText Syntax Alternatives: - http://docutils.sourceforge.net/spec/rst/alternatives.html + http://docutils.sourceforge.net/docs/dev/rst/alternatives.html .. _Docutils: http://docutils.sourceforge.net/ -- cgit v1.2.1 From c0b62760b263f06be663e126c42768c038a53a5a Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:01:31 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2203 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 2 +- docs/ref/transforms.txt | 2 +- docs/user/rst/quickref.html | 46 ++++++++++++++++++++++----------------------- 3 files changed, 25 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 2c012a7b4..767fb7272 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -950,7 +950,7 @@ stylist code will lower the barrier considerably. .. [#PEP-216] PEP 216, Docstring Format, Zadka (http://www.python.org/peps/pep-0216.html) -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _docutils.dtd: http://docutils.sourceforge.net/docs/ref/docutils.dtd .. _soextbl.dtd: http://docutils.sourceforge.net/spec/soextblx.dtd diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt index dd1d13ba3..f5c045bb7 100644 --- a/docs/ref/transforms.txt +++ b/docs/ref/transforms.txt @@ -15,7 +15,7 @@ For background about transforms and the Transformer object, see `PEP 258`_. -.. _PEP 258: pep-0258.html#transformer +.. _PEP 258: ../peps/pep-0258.html#transformer Transforms Listed in Priority Order diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 593660ff5..a3e6f0bd8 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -31,7 +31,7 @@ <p>Links that look like "(<a href="#details">details</a>)" point into the HTML version of the full <a - href="../../spec/rst/reStructuredText.html">reStructuredText + href="../../ref/rst/restructuredtext.html">reStructuredText specification</a> document. These are relative links; if they don't work, please use the <a href="http://docutils.sourceforge.net/docs/rst/quickref.html" @@ -75,7 +75,7 @@ <h2><a href="#contents" name="inline-markup" class="backref" >Inline Markup</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>) <p>Inline markup allows words and phrases within text to have character styles (like italics and boldface) and functionality @@ -208,7 +208,7 @@ >Escaping with Backslashes</a></h2> <p>(<a - href="../../spec/rst/reStructuredText.html#escaping-mechanism">details</a>) + href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>) <p>reStructuredText uses backslashes ("\") to override the special meaning given to markup characters and get the literal characters @@ -256,7 +256,7 @@ <h2><a href="#contents" name="section-structure" class="backref" >Section Structure</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#sections">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -302,7 +302,7 @@ <h2><a href="#contents" name="paragraphs" class="backref" >Paragraphs</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#paragraphs">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -330,7 +330,7 @@ <h2><a href="#contents" name="bullet-lists" class="backref" >Bullet Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#bullet-lists">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -404,7 +404,7 @@ <h2><a href="#contents" name="definition-lists" class="backref" >Definition Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#definition-lists">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -445,7 +445,7 @@ <h2><a href="#contents" name="field-lists" class="backref" >Field Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#field-lists">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -484,7 +484,7 @@ <h2><a href="#contents" name="option-lists" class="backref" >Option Lists</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#option-lists">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -532,7 +532,7 @@ <h2><a href="#contents" name="literal-blocks" class="backref" >Literal Blocks</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#literal-blocks">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -621,7 +621,7 @@ unindented literal blocks: <h2><a href="#contents" name="block-quotes" class="backref" >Block Quotes</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#block-quotes">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -650,7 +650,7 @@ unindented literal blocks: <h2><a href="#contents" name="doctest-blocks" class="backref" >Doctest Blocks</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#doctest-blocks">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -686,7 +686,7 @@ unindented literal blocks: <h2><a href="#contents" name="tables" class="backref" >Tables</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#tables">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>) <p>There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are @@ -795,7 +795,7 @@ unindented literal blocks: <h2><a href="#contents" name="transitions" class="backref" >Transitions</a></h2> - <p>(<a href="../../spec/rst/reStructuredText.html#transitions">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -845,7 +845,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="footnotes" class="backref" >Footnotes</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -938,7 +938,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="citations" class="backref" >Citations</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#citations">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -991,7 +991,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="hyperlink-targets" class="backref" >Hyperlink Targets</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>) <h4><a href="#contents" name="external-hyperlink-targets" class="backref" >External Hyperlink Targets</a></h4> @@ -1071,7 +1071,7 @@ A transition marker is a horizontal line <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" >Indirect Hyperlink Targets</a></h4> - <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>) <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <thead> @@ -1111,7 +1111,7 @@ A transition marker is a horizontal line <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" >Implicit Hyperlink Targets</a></h4> - <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>) <p>Section titles, footnotes, and citations automatically generate hyperlink targets (the title text or footnote/citation label is @@ -1138,12 +1138,12 @@ A transition marker is a horizontal line <h3><a href="#contents" name="directives" class="backref" >Directives</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#directives">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>) <p>Directives are a general-purpose extension mechanism, a way of adding support for new constructs without adding new syntax. For a description of all standard directives, see <a - href="../../spec/rst/directives.html" >reStructuredText + href="../../ref/rst/directives.html" >reStructuredText Directives</a>. <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> @@ -1166,7 +1166,7 @@ A transition marker is a horizontal line <h3><a href="#contents" name="substitution-references-and-definitions" class="backref" >Substitution References and Definitions</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>) <p>Substitutions are like inline directives, allowing graphics and arbitrary constructs within text. @@ -1197,7 +1197,7 @@ dispose of medical waste.</samp> <h3><a href="#contents" name="comments" class="backref" >Comments</a></h3> - <p>(<a href="../../spec/rst/reStructuredText.html#comments">details</a>) + <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>) <p>Any text which begins with an explicit markup start but doesn't use the syntax of any of the constructs above, is a comment. -- cgit v1.2.1 From db65ba68318fb4551011e66a657895507e2c85bb Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:05:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2204 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 767fb7272..1ba20a02e 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -950,9 +950,11 @@ stylist code will lower the barrier considerably. .. [#PEP-216] PEP 216, Docstring Format, Zadka (http://www.python.org/peps/pep-0216.html) -.. _docutils.dtd: http://docutils.sourceforge.net/docs/ref/docutils.dtd +.. _docutils.dtd: + http://docutils.sourceforge.net/docs/ref/docutils.dtd -.. _soextbl.dtd: http://docutils.sourceforge.net/spec/soextblx.dtd +.. _soextbl.dtd: + http://docutils.sourceforge.net/docs/ref/soextblx.dtd .. _The Docutils Document Tree: http://docutils.sourceforge.net/docs/ref/doctree.html @@ -961,10 +963,10 @@ stylist code will lower the barrier considerably. http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html #error_cond_severity -.. _log4j project: http://jakarta.apache.org/log4j/ +.. _log4j project: http://logging.apache.org/log4j/ .. _Docutils Python Source DTD: - http://docutils.sourceforge.net/spec/pysource.dtd + http://docutils.sourceforge.net/docs/dev/pysource.dtd .. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html -- cgit v1.2.1 From d7920f44434f714f389c5a0c8ceb689179fa93aa Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:16:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2205 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 2 +- docs/howto/rst-roles.txt | 2 +- docs/ref/rst/restructuredtext.txt | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index 14a73b951..a9c3511ea 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -84,7 +84,7 @@ have no corresponding element; choose the most appropriate elements from the existing Docutils elements. See `The Docutils Document Tree`_ and the ``docutils.nodes`` module. -.. _The Docutils Document Tree: ../doctree.html +.. _The Docutils Document Tree: ../ref/doctree.html Specify Directive Arguments, Options, and Content diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt index bda9a6433..f271bff9d 100644 --- a/docs/howto/rst-roles.txt +++ b/docs/howto/rst-roles.txt @@ -109,7 +109,7 @@ Note that unlike directives, the "arguments" function attribute is not supported for role customization. Directive arguments are handled by the "role" directive itself. -.. _"role" directive: directives.html#role +.. _"role" directive: ../ref/rst/directives.html#role .. _Creating reStructuredText Directives: rst-directives.html#specify-directive-arguments-options-and-content diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 57b9df995..4a3740197 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -14,8 +14,8 @@ reStructuredText, please read `A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user reference first. -.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/rst/quickref.html +.. _A ReStructuredText Primer: ../../user/rst/quickstart.html +.. _Quick reStructuredText: ../../user/rst/quickref.html reStructuredText_ is plaintext that uses simple and intuitive @@ -2734,7 +2734,7 @@ Markup errors are handled according to the specification in `PEP .. _getopt.py: http://www.python.org/doc/current/lib/module-getopt.html .. _GNU libc getopt_long(): - http://www.gnu.org/manual/glibc-2.2.3/html_node/libc_516.html + http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html .. _doctest module: http://www.python.org/doc/current/lib/module-doctest.html .. _Emacs table mode: http://table.sourceforge.net/ @@ -2746,11 +2746,11 @@ Markup errors are handled according to the specification in `PEP .. _HTML Techniques for Web Content Accessibility Guidelines: http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text .. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: interpreted.html +.. _reStructuredText Interpreted Text Roles: roles.html .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -.. _PEP 258: http://docutils.sourceforge.net/spec/pep-0258.txt +.. _PEP 258: http://docutils.sourceforge.net/docs/peps/pep-0258.txt .. -- cgit v1.2.1 From 02bca6cdf86ccf60250b1b66efe54361a665e5ea Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 19:35:53 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2206 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/policies.txt | 9 +++++---- docs/dev/pysource.txt | 4 ++-- docs/dev/rst/problems.txt | 2 +- docs/dev/todo.txt | 13 +++++++------ docs/peps/pep-0256.txt | 4 +++- 5 files changed, 18 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt index 6a21291e8..64a1b8e93 100644 --- a/docs/dev/policies.txt +++ b/docs/dev/policies.txt @@ -87,7 +87,7 @@ least important): .. _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 +.. _Docutils Internationalization: ../howto/i18n.html#python-code Copyrights and Licensing @@ -132,8 +132,8 @@ 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 <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, -set it up on your own machine, and experiment *there* first. +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 @@ -172,7 +172,8 @@ mistake is easy to fix. That's what CVS is for. .. _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 --------------------- diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index ab677a004..2336ebd54 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -118,8 +118,8 @@ The role may be one of 'package', 'module', 'class', 'method', 'exception_class', 'exception', 'warning_class', or 'warning'. Other roles may be defined. -.. _pysource.dtd: http://docutils.sourceforge.net/spec/pysource.dtd -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd +.. _pysource.dtd: pysource.dtd +.. _docutils.dtd: ../ref/docutils.dtd .. diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt index 9fcdf6d2a..01853c8bd 100644 --- a/docs/dev/rst/problems.txt +++ b/docs/dev/rst/problems.txt @@ -851,7 +851,7 @@ cleanly readable text. .. _Setext: http://docutils.sourceforge.net/mirror/setext.html .. _reStructuredText: http://docutils.sourceforge.net/rst.html .. _detailed description: - http://www.tibsnjoan.demon.co.uk/STNG-format.html + http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html .. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html .. _StructuredTextNG: http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3da3ec83b..7b1160dab 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -81,7 +81,7 @@ General /usr/local/etc/docutils.conf too? See the `Filesystem Hierarchy Standard`_. - .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. + .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs * Add _`object numbering and object references` (tables & figures). These would be the equivalent of DocBook's "formal" elements. @@ -193,7 +193,7 @@ General mapping database for cross-references. Docutils could use a similar system for large-scale, multipart documents. - __ rst/directives.html#including-an-external-document-fragment + __ ../ref/rst/directives.html#including-an-external-document-fragment Aahz's idea: @@ -450,7 +450,8 @@ Miscellaneous ideas: ``##`` is useful though. It allows doc-comments and implementation comments. - .. _additional docstrings: pep-0258.html#additional-docstrings + .. _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 @@ -698,9 +699,9 @@ __ rst/alternatives.html#or-not-to-do somehow? See docutils-develop 2003-02-13. * Include the _`character entity substitution definition files` - `temporarily stored here <tmp/charents>`__, perhaps in a - ``docutils/parsers/rst/includes/`` directory. See `misc.include`_ - below. + `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? diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index bad386391..5eb7425b8 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -256,13 +256,15 @@ References and Footnotes .. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html .. _doc.py: - http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py + http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py .. _pythondoc: .. _gendoc: http://starship.python.net/crew/danilo/pythondoc/ .. _HappyDoc: http://happydoc.sourceforge.net/ +.. XXX Crystal 404. + .. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/ .. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html -- cgit v1.2.1 From 530104164de9d1f3e88ca9c4cc766704689987ba Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 3 Jun 2004 20:47:34 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2210 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/user/config.txt b/docs/user/config.txt index af13ee155..8b8457a05 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -211,13 +211,13 @@ _`error_encoding_error_handler` otherwise. Options: ``--error-encoding-error-handler, --error-encoding, -e``. -_`exit_level` +_`exit_status_level` A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.). - Default: disabled (5). Options: ``--exit``. + Default: disabled (5). Options: ``--exit-status``. _`expose_internals` List of internal attribues to expose as external attributes (with -- cgit v1.2.1 From da5c356c7877826f4510a27a137ed213435b27bd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 4 Jun 2004 14:32:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2214 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 2 +- docs/user/config.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index 81594e984..e7964d4c7 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -61,7 +61,7 @@ top level of the Docutils project directory. licenses. :FAQ.txt_: Docutils Frequently Asked Questions. If you have a question or issue, there's a good chance it's already - answered here. Please take a look. + answered here. :BUGS.txt_: A list of known bugs, and how to report a bug. :HISTORY.txt_: Change history log. :THANKS.txt_: Acknowledgements. diff --git a/docs/user/config.txt b/docs/user/config.txt index 8b8457a05..fde9c3a87 100644 --- a/docs/user/config.txt +++ b/docs/user/config.txt @@ -365,7 +365,7 @@ _`tab_width` Default: 8. Options: ``--tab-width``. -_`trim-footnote-reference-space` +_`trim_footnote_reference_space` Remove spaces before footnote references. Default: don't (None). Options: -- cgit v1.2.1 From 4709317f814a5d22e268a81c81cf74e18e2dc616 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 4 Jun 2004 21:31:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2216 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/peps/pep-0258.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt index 1ba20a02e..5ad1c9e26 100644 --- a/docs/peps/pep-0258.txt +++ b/docs/peps/pep-0258.txt @@ -963,7 +963,7 @@ stylist code will lower the barrier considerably. http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html #error_cond_severity -.. _log4j project: http://logging.apache.org/log4j/ +.. _log4j project: http://logging.apache.org/log4j/docs/index.html .. _Docutils Python Source DTD: http://docutils.sourceforge.net/docs/dev/pysource.dtd -- cgit v1.2.1 From 0b3190bf8e104cbba89ef3ed8b0863fc127e6eac Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 4 Jun 2004 21:40:07 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2217 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/ref/rst/restructuredtext.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt index 4a3740197..a8d11753e 100644 --- a/docs/ref/rst/restructuredtext.txt +++ b/docs/ref/rst/restructuredtext.txt @@ -1590,7 +1590,7 @@ reused, doubled and then tripled, and so on ("**" etc.). "xmlcharrefreplace" `output encoding error handler`__ (available in Python 2.3 & later). -__ http://docutils.sf.net/docs/config.html#output-encoding-error-handler +__ ../../user/config.html#output-encoding-error-handler Mixed Manual and Auto-Numbered Footnotes @@ -2750,7 +2750,7 @@ Markup errors are handled according to the specification in `PEP .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt .. _Zope: http://www.zope.com/ -.. _PEP 258: http://docutils.sourceforge.net/docs/peps/pep-0258.txt +.. _PEP 258: ../../peps/pep-0258.html .. -- cgit v1.2.1 From ec961e4e6b8886bd627898bb257a1671886caec7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 02:45:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2218 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index a9c3511ea..c401b5b96 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -79,10 +79,25 @@ are as follows: Directive functions return a list of nodes which will be inserted into the document tree at the point where the directive was encountered. -This can be an empty list if there is nothing to insert. Directives -have no corresponding element; choose the most appropriate elements -from the existing Docutils elements. See `The Docutils Document -Tree`_ and the ``docutils.nodes`` module. +This can be an empty list if there is nothing to insert. For ordinary +directives, the list must contain body elements or structural +elements. Some directives are intended specifically for substitution +definitions, and must return a list of ``Text`` nodes and/or inline +elements (suitable for inline insertion, in place of the substitution +reference). Such directives must verify substitution definition +context, typically using code like this:: + + if not isinstance(state, states.SubstitutionDef): + error = state_machine.reporter.error( + 'Invalid context: the "%s" directive can only be used ' + 'within a substitution definition.' % (name), + nodes.literal_block(block_text, block_text), line=lineno) + return [error] + +There is no single element that corresponds exactly to directives. +Instead, choose the most appropriate elements from the existing +Docutils elements. See `The Docutils Document Tree`_ and the +``docutils.nodes`` module. .. _The Docutils Document Tree: ../ref/doctree.html @@ -227,7 +242,8 @@ function simply hands off control to a generic directive function:: Note that the only thing distinguishing the various admonition directives is the element (node class) generated. In the code above, the node class is passed as the first argument to the generic -directive function, where the actual processing takes place:: +directive function (early version), where the actual processing takes +place:: def admonition(node_class, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -265,8 +281,8 @@ Three things are noteworthy in the function above: The "image" directive is used to insert a picture into a document. This directive has one argument, the path to the image file, and -supports several options. There is no directive content. Here's the -image directive function:: +supports several options. There is no directive content. Here's an +early version of the image directive function:: def image(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -318,8 +334,8 @@ Several things are noteworthy in the code above: The "contents" directive is used to insert an auto-generated table of contents (TOC) into a document. It takes one optional argument, a title for the TOC. If no title is specified, a default title is used -instead. The directive also handles several options. Here's the -code:: +instead. The directive also handles several options. Here's an early +version of the code:: def contents(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): -- cgit v1.2.1 From 3fef8b4d6cee499ae4a1aaa28437220f258d5a15 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 02:59:13 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2219 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/howto/rst-directives.txt | 16 +++++++++------- docs/peps/pep-0256.txt | 8 ++------ 2 files changed, 11 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt index c401b5b96..9689b6849 100644 --- a/docs/howto/rst-directives.txt +++ b/docs/howto/rst-directives.txt @@ -18,9 +18,18 @@ The syntax of directives is detailed in the `reStructuredText Markup Specification`_, and standard directives are described in `reStructuredText Directives`_. +Directives are a reStructuredText markup/parser concept. There is no +"directive" element, no single element that corresponds exactly to the +concept of directives. Instead, choose the most appropriate elements +from the existing Docutils elements. Directives build structures +using the existing building blocks. See `The Docutils Document Tree`_ +and the ``docutils.nodes`` module for more about the building blocks +of Docutils documents. + .. _reStructuredText Markup Specification: ../ref/rst/restructuredtext.html#directives .. _reStructuredText Directives: ../ref/rst/directives.html +.. _The Docutils Document Tree: ../ref/doctree.html .. contents:: Table of Contents @@ -94,13 +103,6 @@ context, typically using code like this:: nodes.literal_block(block_text, block_text), line=lineno) return [error] -There is no single element that corresponds exactly to directives. -Instead, choose the most appropriate elements from the existing -Docutils elements. See `The Docutils Document Tree`_ and the -``docutils.nodes`` module. - -.. _The Docutils Document Tree: ../ref/doctree.html - Specify Directive Arguments, Options, and Content ================================================= diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt index 5eb7425b8..42c1bada9 100644 --- a/docs/peps/pep-0256.txt +++ b/docs/peps/pep-0256.txt @@ -89,7 +89,7 @@ for Python (not an exhaustive list): - Doug Hellmann's HappyDoc_ -- Laurence Tratt's Crystal_ +- Laurence Tratt's Crystal (no longer available on the web) - Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard library; see below) @@ -263,13 +263,9 @@ References and Footnotes .. _HappyDoc: http://happydoc.sourceforge.net/ -.. XXX Crystal 404. - -.. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/ - .. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html -.. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/ +.. _docutils: http://www.tibsnjoan.co.uk/docutils.html .. _Docutils project: http://docutils.sourceforge.net/ -- cgit v1.2.1 From c61dfed29ab3e4a08217eb581e36a35e8f7cfe44 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 03:10:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2220 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/cheatsheet.txt | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt index 79322025a..ca4dd4775 100644 --- a/docs/user/rst/cheatsheet.txt +++ b/docs/user/rst/cheatsheet.txt @@ -1,13 +1,10 @@ -.. Comments begin with ".. ". Document title (specialized section title) next: - ===================================================== The reStructuredText_ Cheat Sheet: Syntax Reminders ===================================================== +:Info: See <http://docutils.sf.net/rst.html> for introductory docs. :Author: David Goodger <goodger@python.org> :Date: $Date$ :Revision: $Revision$ -:Info: Use the `text source <cheatsheet.txt>`_, **not** the HTML. - See <http://docutils.sf.net/rst.html> for full info. :Description: This is a "docinfo block", or bibliographic field list Section Structure @@ -66,7 +63,7 @@ http://docutils.sourceforge.net; named reference, reStructuredText_; Directive Quick Reference ========================= -See <http://docutils.sf.net/spec/rst/directives.html> for full info. +See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info. ================ ==================================================== Directive Name Description @@ -100,7 +97,7 @@ role Create a custom interpreted text role Interpreted Text Role Quick Reference ===================================== -See <http://docutils.sf.net/spec/rst/interpreted.html> for full info. +See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info. ================ ==================================================== Role Name Description -- cgit v1.2.1 From 8f8de463619bf3e376dc404e6edf16842167831b Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 19:01:01 +0000 Subject: fixed links which are broken when viewing locally git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2221 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index e7964d4c7..b41b410da 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -13,8 +13,8 @@ from the ``docs`` directory of the `development snapshots`__. They are also distributed with the `latest project release package`__, but those may not be completely up to date. -__ ../index.html#development-snapshots -__ ../index.html#latest-project-release-package +__ http://docutils.sourceforge.net/#development-snapshots +__ http://docutils.sourceforge.net/#latest-project-release-package .. contents:: @@ -84,7 +84,7 @@ Docutils-general: * `Docutils Configuration Files <user/config.html>`__ * `Docutils LaTeX Writer <user/latex.html>`__ -`reStructuredText <../rst.html>`_: +`reStructuredText <http://docutils.sourceforge.net/rst.html>`_: * `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or `text source <user/rst/quickstart.txt>`__) -- cgit v1.2.1 From c195d16bd6754c4747c1477161ea71a3b6228947 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 19:04:09 +0000 Subject: another fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2222 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index b41b410da..f2ab46122 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -14,7 +14,7 @@ are also distributed with the `latest project release package`__, but those may not be completely up to date. __ http://docutils.sourceforge.net/#development-snapshots -__ http://docutils.sourceforge.net/#latest-project-release-package +__ http://docutils.sourceforge.net/#project-releases .. contents:: -- cgit v1.2.1 From 6c18a0548558d3eefb532ef613a49533328dd357 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 19:32:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2223 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/pysource.dtd | 5 +++-- docs/dev/pysource.txt | 2 +- docs/ref/docutils.dtd | 2 +- docs/user/rst/quickstart.txt | 6 +++--- 4 files changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/dev/pysource.dtd b/docs/dev/pysource.dtd index 79a074cec..fb8af4091 100644 --- a/docs/dev/pysource.dtd +++ b/docs/dev/pysource.dtd @@ -14,7 +14,8 @@ 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/spec/pysource.dtd. +is available from +http://docutils.sourceforge.net/docs/dev/pysource.dtd. The formal public identifier for this DTD is:: @@ -45,7 +46,7 @@ The formal public identifier for this DTD is:: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This DTD extends the Docutils Generic DTD, available from -http://docutils.sourceforge.net/spec/docutils.dtd. +http://docutils.sourceforge.net/docs/ref/docutils.dtd. --> <!ENTITY % docutils PUBLIC diff --git a/docs/dev/pysource.txt b/docs/dev/pysource.txt index 2336ebd54..6f173a709 100644 --- a/docs/dev/pysource.txt +++ b/docs/dev/pysource.txt @@ -40,7 +40,7 @@ goes something like this: - merge hyperlinks - merge namespaces - create various sections like "Module Attributes", "Functions", - "Classes", "Class Attributes", etc.; see spec/ppdi.dtd + "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 diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd index 5087d23d7..e4a1c27aa 100644 --- a/docs/ref/docutils.dtd +++ b/docs/ref/docutils.dtd @@ -12,7 +12,7 @@ More information about this DTD (document type definition) 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/spec/docutils.dtd. +http://docutils.sourceforge.net/docs/ref/docutils.dtd. The formal public identifier for this DTD is:: diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt index f17ff8803..bf6b21275 100644 --- a/docs/user/rst/quickstart.txt +++ b/docs/user/rst/quickstart.txt @@ -360,10 +360,10 @@ you wish to supply additional information, you may:: :scale: 50 :alt: alternate text -See the full image directive documentation__ for more info. +See the full `image directive documentation`__ for more info. -__ ../../spec/rst/directives.html -__ ../../spec/rst/directives.html#images +__ ../../ref/rst/directives.html +__ ../../ref/rst/directives.html#images What Next? -- cgit v1.2.1 From ae82315c489d8015f1c902bfed4df47ddb3b35a3 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 5 Jun 2004 19:55:24 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2225 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7b1160dab..9fcb6e95f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -305,7 +305,7 @@ General with examples of every setting (many/most commented out). It's currently sparse, requiring doc lookups. -* Merge doc/latex.txt info into tools.txt and config.txt. +* Merge docs/user/latex.txt info into tools.txt and config.txt. * Add internationalization to _`footer boilerplate text` (resulting from "--generator", "--source-link", and "--date" etc.), allowing -- cgit v1.2.1 From ef00f6c16cc56a9224f89eda04a96ef4b9873510 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 7 Jun 2004 15:51:27 +0000 Subject: Update title and some more. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2234 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index dca7147e5..6d5c9a6b9 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -1,6 +1,6 @@ -======================= - Docutils LaTeX Writer -======================= +================================ + Generating LaTeX with Docutils +================================ :Author: Engelbert Gruber :Contact: grubert@users.sourceforge.net @@ -45,7 +45,7 @@ config documentytion. ===================== ================================================ -Setting/Config Entry Description +Configuration Issue Description ===================== ================================================ papersize Default: a4paper. Paper geometry can be changed using ``\geometry{xxx}`` entries. @@ -94,11 +94,6 @@ rubric style The header contains the definition of a new font selection see below ===================== ================================================ -Missing options ---------------- - -* Selection of LaTeX fontsize. -* Assumed reST linelength for table width setting. Font selection -------------- @@ -207,7 +202,7 @@ Open to be fixed or open to discussion. Tilde in italian ---------------- -Does not work, or only in verbatim or verb. +Does not work, or only in verbatim or verb. Could be fixed by using T1. Tables ------ @@ -251,6 +246,9 @@ Notes Miscellaneous ------------- +* Selection of LaTeX fontsize configurable. +* Assumed reST linelength for table width setting configurable. +* literal-block indentation configurable. * The underscore ``_`` does not work in literal-blocks, has different width. I tried @@ -307,4 +305,8 @@ Miscellaneous \textbullet \bullet gefüllter Kreis auf halber Höhe \textperiodcentered \cdot · \textvisiblespace (n.v.) sichtbares Leerzeichen +* keep literal-blocks together on a page, avoid pagebreaks. + + failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before + the block. -- cgit v1.2.1 From 44aa09235c5def785e191afc22fd27f782165813 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 7 Jun 2004 15:52:08 +0000 Subject: Update LaTeX section. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2235 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/tools.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/user/tools.txt b/docs/user/tools.txt index 3fdc9491e..55e905aa6 100644 --- a/docs/user/tools.txt +++ b/docs/user/tools.txt @@ -231,11 +231,9 @@ Some limitations and difference apply: ``latex``; use ``pdflatex`` instead. - Only the Latin-1 output encoding has been tested up to now (Latin-1 has been made the default output encoding for LaTeX). -- The generated file includes a file ``style.tex``, which allows the - inclusion of special packages or changes to settings made in the - header. -- Not all constructs are possible (e.g. row/column spans in tables are - not). +- The optional stylesheet file allows the inclusion of special packages + or overwriting default settings for LaTeX. +- Not all constructs are possible, see `Generating LaTeX with Docutils`_. docutils-xml.py @@ -313,7 +311,7 @@ set once and take effect every time you use a front-end tool. For details, see `Docutils Configuration Files`_. .. _Docutils Configuration Files: config.html - +.. _Generating LaTeX with Docutils: latex.html .. Local Variables: -- cgit v1.2.1 From de53435f369b87f8ec6ada83f91171248548a5a9 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 7 Jun 2004 15:55:55 +0000 Subject: Add problem with figures (images,footnotes,citations). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2236 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 6d5c9a6b9..e8372f7c5 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -199,6 +199,17 @@ Problems Open to be fixed or open to discussion. +footnotes and citations +----------------------- + +Initially both were implemented using figures, because hyperlinking back +and forth seemed to be impossible. Later images were put into figures. + +This results in footnotes images and figures possibly being mixed at page +foot. + +* use LaTeX footnotes and citations (to be implemented). + Tilde in italian ---------------- -- cgit v1.2.1 From 76af72379beb821341b30d0e74798a9f3f83d4b7 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 07:23:36 +0000 Subject: Fix: dont insert bibliography if no bibitems were collected. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2239 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index e8372f7c5..b05612ced 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -208,7 +208,12 @@ and forth seemed to be impossible. Later images were put into figures. This results in footnotes images and figures possibly being mixed at page foot. -* use LaTeX footnotes and citations (to be implemented). +* Use LaTeX footnotes and citations for printing or more complex layout. +* Footnotes and citations done with figures might excell in hyperlink + support. + +If ``use-latex-citations`` is used a bibliography is inserted right at +the end of the document. *This should be customizable*. Tilde in italian ---------------- -- cgit v1.2.1 From 311c13a5efdb13fb0824389703e4191f48ec0251 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 20:18:54 +0000 Subject: added "Plan for Enthought API Documentation Tool" and "Enthought API Documentation Tool RFP" git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2241 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/enthought-plan.txt | 372 ++++++++++++++++++++++++++++++++++++++++++++ docs/dev/enthought-rfp.txt | 146 +++++++++++++++++ 2 files changed, 518 insertions(+) create mode 100644 docs/dev/enthought-plan.txt create mode 100644 docs/dev/enthought-rfp.txt (limited to 'docs') diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt new file mode 100644 index 000000000..ab4bfb2d4 --- /dev/null +++ b/docs/dev/enthought-plan.txt @@ -0,0 +1,372 @@ +=========================================== + Plan for Enthought API Documentation Tool +=========================================== + +:Author: David Goodger +:Contact: goodger@python.org +:Date: $Date$ +:Revision: $Revision$ +: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:: + + +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 -- althought 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. diff --git a/docs/dev/enthought-rfp.txt b/docs/dev/enthought-rfp.txt new file mode 100644 index 000000000..31b483229 --- /dev/null +++ b/docs/dev/enthought-rfp.txt @@ -0,0 +1,146 @@ +================================== + 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: o + + * 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. -- cgit v1.2.1 From 3527deb198d68be151c5f1f7e17cf6fd41418a34 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 20:35:45 +0000 Subject: Add line spacing description. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2242 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index b05612ced..7ff8ff490 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -91,6 +91,14 @@ rubric style The header contains the definition of a new Default: subsection style italic. --------------------- ------------------------------------------------ +line spacing Is done with package *setspace*, which gives + singlespace, onehalfspace and doublespace + commands. To get documentwide double spacing, + add this to your stylesheet :: + + \usepackage{setspace} + \doublespacing +--------------------- ------------------------------------------------ font selection see below ===================== ================================================ -- cgit v1.2.1 From 3851899ad6afb3f283eafdfafde1dc504ce4ab8f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 21:38:41 +0000 Subject: added introduction git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2243 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/enthought-plan.txt | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'docs') diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt index ab4bfb2d4..9c5299578 100644 --- a/docs/dev/enthought-plan.txt +++ b/docs/dev/enthought-plan.txt @@ -20,6 +20,48 @@ __ enthought-rfp.html .. 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, and plenty of Texas +hospitality later, the initial version of this document was the +result. + +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! + +As details become clear and milestones are reached, I will update this +document to reflect the evolution of the project. + +.. _PyCon 2004: http://pycon.org/dc2004/ +.. _reStructuredText: http://docutils.sf.net/rst.html +.. _SciPy: http://www.scipy.org/ + + Development Plan ================ -- cgit v1.2.1 From 1e4810b51c076053eebe3d454c89f12aa3efbfd6 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 21:40:36 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2244 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/enthought-plan.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt index 9c5299578..2dd8be6c5 100644 --- a/docs/dev/enthought-plan.txt +++ b/docs/dev/enthought-plan.txt @@ -104,7 +104,7 @@ 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 -- althought I doubt that there would be any problem -- we may +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. -- cgit v1.2.1 From 3b9f8b5c28a0ca6fd7fc21350f39774c0c9ae18b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 21:42:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2245 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/index.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/index.txt b/docs/index.txt index f2ab46122..7eab4801b 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -170,6 +170,8 @@ Docutils-general: * `Docstring Semantics <dev/semantics.html>`__ (incomplete) * `Python Source Reader <dev/pysource.html>`_ (incomplete) * `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) +* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_ +* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_ reStructuredText_: -- cgit v1.2.1 From 32fad80e63a26761e7c17cae35e149ea731ef8bd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 8 Jun 2004 22:00:36 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2246 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 9fcb6e95f..80e998585 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -522,6 +522,10 @@ __ rst/alternatives.html#or-not-to-do 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 @@ -868,6 +872,25 @@ __ rst/alternatives.html#or-not-to-do 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. + +* When using superscripted footnotes 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. + Directives ---------- -- cgit v1.2.1 From 4d6f14042947b4cd69e21dfa8f12e0342b4c54f4 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 9 Jun 2004 06:00:14 +0000 Subject: More linespacing possibilities. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2247 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index 7ff8ff490..e537e052c 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -98,6 +98,17 @@ line spacing Is done with package *setspace*, which gives \usepackage{setspace} \doublespacing + + Another way :: + + \renewcommand{\baselinestretch}{2} + + And yet another, add ``doublesp`` to the + documentoptions and put :: + + \setstretch{1.7} + + or for bigger linespacing. --------------------- ------------------------------------------------ font selection see below ===================== ================================================ -- cgit v1.2.1 From 17649658fcfe3b6039ce961627e9834a5e7ed71c Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jun 2004 10:59:47 +0000 Subject: Fixes in linepsacing doc. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2249 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index e537e052c..aa99a5e17 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -101,14 +101,14 @@ line spacing Is done with package *setspace*, which gives Another way :: - \renewcommand{\baselinestretch}{2} + \linespread{1.55} And yet another, add ``doublesp`` to the - documentoptions and put :: + documentoptions and e.g. :: \setstretch{1.7} - or for bigger linespacing. + for bigger linespacing. --------------------- ------------------------------------------------ font selection see below ===================== ================================================ -- cgit v1.2.1 From 8939a91f69c6a51970bbb4f45becd15082b7bc45 Mon Sep 17 00:00:00 2001 From: grubert <grubert@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jun 2004 13:30:31 +0000 Subject: News to T1. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2250 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/latex.txt | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/user/latex.txt b/docs/user/latex.txt index aa99a5e17..9b7c60ea2 100644 --- a/docs/user/latex.txt +++ b/docs/user/latex.txt @@ -118,8 +118,8 @@ Font selection -------------- When generating pdf-files from LaTeX, use the pdflatex command, the files -are a lot smaller if postscript fonts are used. To do so put -``\usepackage{times}`` into the stylesheet. +are a lot smaller if postscript fonts are used. This *was* fixed by putting +``\usepackage{times}`` into the stylesheet. It is said that the typewriter font in computer modern font, the default LaTeX font package, is too heavy compared to the others. There is a package @@ -129,6 +129,13 @@ Some people diagnose a similar unbalance for the postscript fonts, the package to fix this is ``\usepackage{pslatex}``. pslatex in contrast to the standard LaTeX fonts has a bold typewriter font. +As ``times`` does not use the appropriate mathematical fonts and ``pslatex`` +does not work with T1 encodings one should use:: + + \usepackage{mathptmx} + \usepackage[scaled=.90]{helvet} + \usepackage{courier} + Table of figures ---------------- @@ -237,7 +244,11 @@ the end of the document. *This should be customizable*. Tilde in italian ---------------- -Does not work, or only in verbatim or verb. Could be fixed by using T1. +Does not work, or only in verbatim or verb. Could be fixed by using T1, but +the hyphen in literal environments is different: + +* inline or in verbatim it is lower than it should. +* in a block with markup two hyphens become one (endashed ?). Tables ------ -- cgit v1.2.1 From a163be228623eeae5901ac5596eea63f46bcf37d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jun 2004 16:25:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2251 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/enthought-plan.txt | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt index 2dd8be6c5..87554b654 100644 --- a/docs/dev/enthought-plan.txt +++ b/docs/dev/enthought-plan.txt @@ -29,9 +29,9 @@ 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, and plenty of Texas -hospitality later, the initial version of this document was the -result. +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, @@ -54,9 +54,6 @@ the community will benefit from the end result, which will be great. All that's left now is to actually do the work! -As details become clear and milestones are reached, I will update this -document to reflect the evolution of the project. - .. _PyCon 2004: http://pycon.org/dc2004/ .. _reStructuredText: http://docutils.sf.net/rst.html .. _SciPy: http://www.scipy.org/ -- cgit v1.2.1 From 72068eaa976dce33b3b8a9f8fce8d5a26cbc7aca Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jun 2004 17:45:00 +0000 Subject: added "List-Driven Tables" section git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2252 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 251 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index c9070712e..fb9dd14a8 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -2133,6 +2133,257 @@ directive only) until all Writers have been updated to support the new syntax & implementation. +List-Driven Tables +================== + +The original idea came from Dylan Jay: + + ... to use a two level bulleted list with something to + indicate it should be rendered as a table ... + +It's an interesting idea. It could be implemented in as a directive +which transforms a uniform two-level list into a table. Using a +directive would allow the author to explicitly set the table's +orientation (by column or by row), the presence of row headers, etc. + +Alternatives: + +1. Bullet-list-tables might look like this:: + + .. list-table:: + + * - Treat + - Quantity + - Description + * - Albatross! + - 299 + - On a stick! + * - Crunchy Frog! + - 1499 + - If we took the bones out, it wouldn't be crunchy, + now would it? + * - Gannet Ripple! + - 199 + - On a stick! + + This list must be written in two levels. This wouldn't work:: + + .. list-table:: + + * Treat + * Albatross! + * Gannet! + * Crunchy Frog! + + * Quantity + * 299 + * 199 + * 1499 + + * Description + * On a stick! + * On a stick! + * If we took the bones out... + + The above is a single list of 12 items. The blank lines are not + significant to the markup. We'd have to explicitly specify how + many columns or rows to use, which isn't a good idea. + +2. Beni Cherniavsky suggested a field list alternative. It could look + like this:: + + .. field-list-table:: + :headrows: 1 + + - :treat: Treat + :quantity: Quantity + :descr: Description + + - :treat: Albatross! + :quantity: 299 + :descr: On a stick! + + - :treat: Crunchy Frog! + :quantity: 1499 + :descr: If we took the bones out, it wouldn't be + crunchy, now would it? + + Column order is determined from the order of fields in the first + row. Field order in all other rows is ignored. As a side-effect, + this allows trivial re-arrangement of columns. By using named + fields, it becomes possible to omit fields in some rows without + losing track of things, which is important for spans. + +3. An alternative to two-level bullet lists would be to use enumerated + lists for the table cells:: + + .. list-table:: + + * 1. Treat + 2. Quantity + 3. Description + * 1. Albatross! + 2. 299 + 3. On a stick! + * 1. Crunchy Frog! + 2. 1499 + 3. If we took the bones out, it wouldn't be crunchy, + now would it? + + That provides better correspondence between cells in the same + column than does bullet-list syntax, but not as good as field list + syntax. I think that were only field-list-tables available, a lot + of users would use the equivalent degenerate case:: + + .. field-list-table:: + - :1: Treat + :2: Quantity + :3: Description + ... + +4. Another natural variant is to allow a description list with field + lists as descriptions:: + + .. list-table:: + :headrows: 1 + + Treat + :quantity: Quantity + :descr: Description + Albatross! + :quantity: 299 + :descr: On a stick! + Crunchy Frog! + :quantity: 1499 + :descr: If we took the bones out, it wouldn't be + crunchy, now would it? + + This would make the whole first column a header column ("stub"). + It's limited to a single column and a single paragraph fitting on + one source line. Also it wouldn't allow for empty cells or row + spans in the first column. But these are limitations that we could + live with, like those of simple tables. + +The List-driven table feature could be done in many ways. Each user +will have their preferred usage. Perhaps a single "list-table" +directive could handle them all, depending on which options and +content are present. + +Issues: + +* How to indicate that there's 1 header row? Perhaps two lists? :: + + .. list-table:: + + + - Treat + - Quantity + - Description + + * - Albatross! + - 299 + - On a stick! + + This is probably too subtle though. Better would be a directive + option, like ``:headrows: 1``. An early suggestion for the header + row(s) was to use a directive option:: + + .. field-list-table:: + :header: + - :treat: Treat + :quantity: Quantity + :descr: Description + - :treat: Albatross! + :quantity: 299 + :descr: On a stick! + + But the table data is at two levels and looks inconsistent. + + In general, we cannot extract the header row from field lists' field + names because field names cannot contain everything one might put in + a table cell. A separate header row also allows shorter field names + and doesn't force one to rewrite the whole table when the header + text changes. But for simpler cases, we can offer a ":header: + fields" option, which does extract header cells from field names:: + + .. field-list-table:: + :header: fields + + - :Treat: Albatross! + :Quantity: 299 + :Description: On a stick! + +* How to indicate the column widths? A directive option? :: + + .. list-table:: + :widths: 15 10 35 + + Automatic defaults from the text used? + +* How to handle row and/or column spans? + + In a field list, column-spans can be indicated by specifying the + first and last fields, separated by space-dash-space or ellipsis:: + + - :foo - baz: quuux + - :foo ... baz: quuux + + Commas were proposed for column spans:: + + - :foo, bar: quux + + But non-adjacent columns become problematic. Should we report an + error, or duplicate the value into each span of adjacent columns (as + was suggested)? The latter suggestion is appealing but may be too + clever. Best perhaps to simply specify the two ends. + + It was suggested that comma syntax should be allowed, too, in order + to allow the user to avoid trouble when changing the column order. + But changing the column order of a table with spans is not trivial; + we shouldn't make it easier to mess up. + + One possible syntax for row-spans is to simply treat any row where a + field is missing as a row-span from the last row where it appeared. + Leaving a field empty would still be possible by writing a field + with empty content. But this is too implicit. + + Another way would be to require an explicit continuation marker + (``...``/``-"-``/``"``?) in all but the first row of a spanned + field. Empty comments could work (".."). If implemented, the same + marker could also be supported in simple tables, which lack + row-spanning abilities. + + Explicit markup like ":rowspan:" and ":colspan:" was also suggested. + + Sometimes in a table, the first header row contains spans. It may + be necessary to provide a way to specify the column field names + independently of data rows. A directive option would do it. + +* We could specify "column-wise" or "row-wise" ordering, with the same + markup structure. For example, with definition data:: + + .. list-table:: + :column-wise: + + Treat + - Albatross! + - Crunchy Frog! + Quantity + - 299 + - 1499 + Description + - On a stick! + - If we took the bones out, it wouldn't be + crunchy, now would it? + +* A syntax for stubs in ASCII-art tables is easy to imagine:: + + +------------------------++------------+----------+ + | Header row, column 1 || Header 2 | Header 3 | + +========================++============+==========+ + | body row 1, column 1 || column 2 | column 3 | + +------------------------++------------+----------+ + + ------------------- ... Or Not To Do? ------------------- -- cgit v1.2.1 From c6de99db667763252ff20b7682b12e0000b70f7d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Thu, 10 Jun 2004 17:45:37 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2253 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 86 +++++++++++++++++++++---------------------------------- 1 file changed, 32 insertions(+), 54 deletions(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 80e998585..95e78a6e7 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -333,6 +333,36 @@ General & 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. + Documentation ============= @@ -1282,60 +1312,8 @@ when used in a document. internal section structure, with adornment styles independent of the main document. - - _`body.list-table`: The idea came from Dylan Jay: - - ... to use a two level bulleted list with something to - indicate it should be rendered as a table ... - - It's an interesting idea. It could be implemented in as a - directive which transforms a uniform two-level bullet list into a - table. Using a directive would allow the author to explicitly set - the table's orientation (by column or by row), the presence of row - headers, etc. - - This is what it might look like:: - - .. list-table:: - - * - Treat - - Quantity - - Description - * - Albatross! - - 299 - - On a stick! - * - Crunchy Frog! - - 1499 - - If we took the bones out, it wouldn't be crunchy, - now would it? - * - Gannet Ripple! - - 199 - - On a stick! - - Issues: - - * How to indicate that there's 1 header row? Perhaps two lists? - :: - - .. list-table:: - - + - Treat - - Quantity - - Description - - * - Albatross! - - 299 - - On a stick! - - A directive option (``:headrows: 1``)? - - * How to indicate the column widths? A directive option? :: - - .. list-table:: - :widths: 15 10 35 - - Automatic defaults from the text used? - - * How to handle row and/or column spans? + - _`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 -- cgit v1.2.1 From 7724aa9e1c0fb2fc94efba2088ae5a014a3494d4 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 14:02:52 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2254 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 95e78a6e7..5933e9d82 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -906,7 +906,9 @@ __ rst/alternatives.html#or-not-to-do :Case Study\: Event Handling: This chapter will be dropped. -* When using superscripted footnotes references, the space looks ugly. +* _`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. -- cgit v1.2.1 From 01aeb19cae1b76c54ee60bad5264f6a934eb2dc8 Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 15:35:15 +0000 Subject: Updated link to self. Fixed table attributes to not suggest any formatting difference between full and simple table syntaxes - synced both to the HTML writer's output. Closed some tags and fixed indentation in the process to understand what I'm editing. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2255 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 58 ++++++++++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index a3e6f0bd8..476a92372 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -15,10 +15,10 @@ <!-- Caveat: if you're reading the HTML for the examples, --> <!-- beware that it was hand-generated, not by Docutils/ReST. --> - <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" + <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2004-05-15</em> + <br align="right"><em>Updated 2004-06-11</em> <blockquote> <p>Copyright: This document has been placed in the public domain. @@ -717,28 +717,36 @@ unindented literal blocks: <td> <p>Grid table:</p> <table border="1"> - <tr valign="top"> - <th>Header 1 - <th>Header 2 - <th>Header 3 - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - <tr valign="top"> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - <tr valign="top"> - <td>body row 4 + <thead valign="bottom"> + <tr> + <th>Header 1 + <th>Header 2 + <th>Header 3 + </tr> + </thead> + <tbody valign="top"> + <tr> + <td>body row 1 + <td>column 2 + <td>column 3 + </tr> + <tr> + <td>body row 2 + <td colspan="2">Cells may span columns. + </tr> + <tr> + <td>body row 3 + <td rowspan="2">Cells may<br>span rows. + <td rowspan="2"> + <ul> + <li>Cells + <li>contain + <li>blocks. + </ul> + </tr> + <tr> + <td>body row 4 + </tr> </table> <tr valign="top"> <td> @@ -757,7 +765,7 @@ unindented literal blocks: <td> <p>Simple table:</p> - <table frame="border" rules="all"> + <table border="1"> <colgroup> <col colwidth="31%" /> <col colwidth="31%" /> -- cgit v1.2.1 From 13969793880cd4ff3416f965aa5c94fb8dd7aed3 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 15:50:14 +0000 Subject: let CVS take care of the date for us git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2256 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 476a92372..e7caa804e 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -18,7 +18,7 @@ <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2004-06-11</em> + <br align="right"><em>Updated $Date$</em> <blockquote> <p>Copyright: This document has been placed in the public domain. -- cgit v1.2.1 From 304fe50cad583e0933d81de2e9cecaf24b6fbb7b Mon Sep 17 00:00:00 2001 From: cben <cben@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 16:02:22 +0000 Subject: Updated text of link to self (only updated the URL in last commit). git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2258 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index e7caa804e..19af15a38 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -16,7 +16,7 @@ <!-- beware that it was hand-generated, not by Docutils/ReST. --> <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" - >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> + >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em> <br align="right"><em>Being a cheat-sheet for reStructuredText</em> <br align="right"><em>Updated $Date$</em> -- cgit v1.2.1 From c4650955dc85bdcdbae8315d4383a9835dee8b9b Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 19:26:31 +0000 Subject: fixed link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2259 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 19af15a38..1ffbc9e9d 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -34,7 +34,7 @@ href="../../ref/rst/restructuredtext.html">reStructuredText specification</a> document. These are relative links; if they don't work, please use the <a - href="http://docutils.sourceforge.net/docs/rst/quickref.html" + href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" >master "Quick reStructuredText"</a> document. <h2><a name="contents">Contents</a></h2> -- cgit v1.2.1 From e431aee87ef44fefb85fd0b0e41bf94b4c106f73 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 11 Jun 2004 19:51:17 +0000 Subject: html validity fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2260 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/user/rst/quickref.html | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html index 1ffbc9e9d..a34eafb53 100644 --- a/docs/user/rst/quickref.html +++ b/docs/user/rst/quickref.html @@ -1,7 +1,10 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + <html> <head> <title>Quick reStructuredText + @@ -53,6 +55,7 @@
  • Field Lists
  • Option Lists
  • Literal Blocks
    • +
  • Line Blocks
  • Block Quotes
  • Doctest Blocks
  • Tables
    • @@ -512,20 +515,20 @@ - - - - -

    -a -

    command-line option "a" +

    		-a + command-line option "a"

    -b file -

    options can have arguments and long descriptions +

    		-b file + options can have arguments and long descriptions

    --long -

    options can be long also +

    		--long + options can be long also

    --input=file -

    long options can also have arguments +

    		--input=file + long options can also have arguments

    /V -

    DOS/VMS-style options too +

    		/V + DOS/VMS-style options too
    @@ -621,6 +624,48 @@ unindented literal blocks: > for Haskell literate programming. +

    Line Blocks

    + +

    (details) + +

    + + + + + +
    Plain text + Typical result +
    +| Line blocks are useful for addresses, +
    | verse, and adornment-free lists. +
    | +
    | Each new line begins with a +
    | vertical bar ("|"). +
    |     Line breaks and initial indents +
    |     are preserved. +
    | Continuation lines are wrapped +
      portions of long lines; they begin +
      with spaces in place of vertical bars. + +     		+
    +
    Line blocks are useful for addresses,
    +
    verse, and adornment-free lists.
    +

    +
    Each new line begins with a
    +
    vertical bar ("|").
    +
    +
    Line breaks and initial indents
    +
    are preserved.
    +
    +
    Continuation lines are wrapped portions + of long lines; they begin + with spaces in place of vertical bars.
    +
    +
    +

    Block Quotes

    -- cgit v1.2.1 From 90276ab6b54a4e0eb5a4e2b273098df046d2cec1 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 5 Oct 2004 01:23:03 +0000 Subject: implemented line blocks git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2698 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/rst/alternatives.txt | 426 +++++++++++++++++++++--------------------- docs/dev/todo.txt | 4 - 2 files changed, 213 insertions(+), 217 deletions(-) (limited to 'docs') diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt index 37234c33c..639212a25 100644 --- a/docs/dev/rst/alternatives.txt +++ b/docs/dev/rst/alternatives.txt @@ -1226,6 +1226,219 @@ Solution 3 was chosen for incorporation into the document tree model. .. _HTML: http://www.w3.org/MarkUp/ +Syntax for Line Blocks +====================== + +* An early idea: How about a literal-block-like prefix, perhaps + "``;;``"? (It is, after all, a *semi-literal* literal block, no?) + Example:: + + Take it away, Eric the Orchestra Leader! ;; + + A one, two, a one two three four + + Half a bee, philosophically, + must, *ipso facto*, half not be. + But half the bee has got to be, + *vis a vis* its entity. D'you see? + + But can a bee be said to be + or not to be an entire bee, + when half the bee is not a bee, + due to some ancient injury? + + Singing... + + Kinda lame. + +* Another idea: in an ordinary paragraph, if the first line ends with + a backslash (escaping the newline), interpret the entire paragraph + as a verse block? For example:: + + Add just one backslash\ + And this paragraph becomes + An awful haiku + + (Awful, and arguably invalid, since in Japanese the word "haiku" + contains three syllables not two.) + + This idea was superceded by the rules for escaped whitespace, useful + for `character-level inline markup`_. + +* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed + a "plain list" syntax (and also provided a patch):: + + | John Doe + | President, SuperDuper Corp. + | jdoe@example.org + + __ http://thread.gmane.org/gmane.text.docutils.devel/1187 + + This syntax is very natural. However, these "plain lists" seem very + similar to line blocks, and I see so little intrinsic "list-ness" + that I'm loathe to add a new object. I used the term "blurbs" to + remove the "list" connotation from the originally proposed name. + Perhaps line blocks could be refined to add the two properties they + currently lack: + + A) long lines wrap nicely + B) HTML output doesn't look like program code in non-CSS web + browsers + + (A) is an issue of all 3 aspects of Docutils: syntax (construct + behaviour), internal representation, and output. (B) is partly an + issue of internal representation but mostly of output. + +ReStructuredText will redefine line blocks with the "|"-quoting +syntax. The following is my current thinking. + + +Syntax +------ + +Perhaps line block syntax like this would do:: + + | M6: James Bond + | MIB: Mr. J. + | IMF: not decided yet, but probably one of the following: + | Ethan Hunt + | Jim Phelps + | Claire Phelps + | CIA: Felix Leiter + +Note that the "nested" list does not have nested syntax (the "|" are +not further indented); the leading whitespace would still be +significant somehow (more below). As for long lines in the input, +this could suffice:: + + | John Doe + | Founder, President, Chief Executive Officer, Cook, Bottle + Washer, and All-Round Great Guy + | SuperDuper Corp. + | jdoe@example.org + +The lack of "|" on the third line indicates that it's a continuation +of the second line, wrapped. + +I don't see much point in allowing arbitrary nested content. Multiple +paragraphs or bullet lists inside a "blurb" doesn't make sense to me. +Simple nested line blocks should suffice. + + +Internal Representation +----------------------- + +Line blocks are currently represented as text blobs as follows:: + + + + +Instead, we could represent each line by a separate element:: + + + + + + + +We'd keep the significance of the leading whitespace of each line +either by converting it to non-breaking spaces at output, or with a +per-line margin. Non-breaking spaces are simpler (for HTML, anyway) +but kludgey, and wouldn't support indented long lines that wrap. But +should inter-word whitespace (i.e., not leading whitespace) be +preserved? Currently it is preserved in line blocks. + +Representing a more complex line block may be tricky:: + + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + +Perhaps the representation could allow for nested line blocks:: + + + +With this model, leading whitespace would no longer be significant. +Instead, left margins are implied by the nesting. The example above +could be represented as follows:: + + + + But can a bee be said to be + + + or not to be an entire bee, + + + when half the bee is not a bee, + + + due to some ancient injury? + +I wasn't sure what to do about even more complex line blocks:: + + | Indented + | Not indented + | Indented a bit + | A bit more + | Only one space + +How should that be parsed and nested? Should the first line have +the same nesting level (== indentation in the output) as the fourth +line, or the same as the last line? Mark Nodine suggested that such +line blocks be parsed similarly to complexly-nested block quotes, +which seems reasonable. In the example above, this would result in +the nesting of first line matching the last line's nesting. In +other words, the nesting would be relative to neighboring lines +only. + + +Output +------ + +In HTML, line blocks are currently output as "
    " blocks, which
+gives us significant whitespace and line breaks, but doesn't allow
+long lines to wrap and causes monospaced output without stylesheets.
+Instead, we could output "
    " elements parallelling the
+representation above, where each nested 
     would
+have an increased left margin (specified in the stylesheet).
+
+Jarno suggested the following HTML output::
+
+    
    
+       First, top level line
+       
    
+          Second, once nested
+          Third, once nested
+          ...
+       
    
+       ...
+    
    
+
+The ```` and `` `` are meant to support non-CSS and
+non-graphical browsers.  I understand the case for "br", but I'm not
+so sure about hidden " ".  I question how much effort should be
+put toward supporting non-graphical and especially non-CSS browsers,
+at least for html4css1.py output.
+
+Should the lines themselves be ```` or ``
    ``?  I don't like
+mixing inline and block-level elements.
+
+
+Implementation Plan
+-------------------
+
+We'll leave the old implementation in place (via the "line-block"
+directive only) until all Writers have been updated to support the new
+syntax & implementation.  The "line-block" directive can then be
+updated to use the new internal representation, and its documentation
+will be updated to recommend the new syntax.
+
+
 -----------------
  Not Implemented
 -----------------
@@ -1922,219 +2135,6 @@ unambiguous::
 IOW, the parser ought to be as permissive as possible.
 
 
-Syntax for Line Blocks
-======================
-
-* An early idea: How about a literal-block-like prefix, perhaps
-  "``;;``"?  (It is, after all, a *semi-literal* literal block, no?)
-  Example::
-
-      Take it away, Eric the Orchestra Leader!  ;;
-
-          A one, two, a one two three four
-
-          Half a bee, philosophically,
-          must, *ipso facto*, half not be.
-          But half the bee has got to be,
-          *vis a vis* its entity.  D'you see?
-
-          But can a bee be said to be
-          or not to be an entire bee,
-          when half the bee is not a bee,
-          due to some ancient injury?
-
-          Singing...
-
-  Kinda lame.
-
-* Another idea: in an ordinary paragraph, if the first line ends with
-  a backslash (escaping the newline), interpret the entire paragraph
-  as a verse block?  For example::
-
-      Add just one backslash\
-      And this paragraph becomes
-      An awful haiku
-
-  (Awful, and arguably invalid, since in Japanese the word "haiku"
-  contains three syllables not two.)
-
-  This idea was superceded by the rules for escaped whitespace, useful
-  for `character-level inline markup`_.
-
-* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed
-  a "plain list" syntax (and also provided a patch)::
-
-       | John Doe
-       | President, SuperDuper Corp.
-       | jdoe@example.org
-
-  __ http://thread.gmane.org/gmane.text.docutils.devel/1187
-
-  This syntax is very natural.  However, these "plain lists" seem very
-  similar to line blocks, and I see so little intrinsic "list-ness"
-  that I'm loathe to add a new object.  I used the term "blurbs" to
-  remove the "list" connotation from the originally proposed name.
-  Perhaps line blocks could be refined to add the two properties they
-  currently lack:
-
-  A) long lines wrap nicely
-  B) HTML output doesn't look like program code in non-CSS web
-     browsers
-
-  (A) is an issue of all 3 aspects of Docutils: syntax (construct
-  behaviour), internal representation, and output.  (B) is partly an
-  issue of internal representation but mostly of output.
-
-ReStructuredText will redefine line blocks with the "|"-quoting
-syntax.  The following is my current thinking.
-
-
-Syntax
-------
-
-Perhaps line block syntax like this would do::
-
-     | M6: James Bond
-     | MIB: Mr. J.
-     | IMF: not decided yet, but probably one of the following:
-     |   Ethan Hunt
-     |   Jim Phelps
-     |   Claire Phelps
-     | CIA: Felix Leiter
-
-Note that the "nested" list does not have nested syntax (the "|" are
-not further indented); the leading whitespace would still be
-significant somehow (more below).  As for long lines in the input,
-this could suffice::
-
-     | John Doe
-     | Founder, President, Chief Executive Officer, Cook, Bottle
-       Washer, and All-Round Great Guy
-     | SuperDuper Corp.
-     | jdoe@example.org
-
-The lack of "|" on the third line indicates that it's a continuation
-of the second line, wrapped.
-
-I don't see much point in allowing arbitrary nested content.  Multiple
-paragraphs or bullet lists inside a "blurb" doesn't make sense to me.
-Simple nested line blocks should suffice.
-
-
-Internal Representation
------------------------
-
-Line blocks are currently represented as text blobs as follows::
-
-     
-     
-
-Instead, we could represent each line by a separate element::
-
-     
-     
-
-     
-     
-
-We'd keep the significance of the leading whitespace of each line
-either by converting it to non-breaking spaces at output, or with a
-per-line margin.  Non-breaking spaces are simpler (for HTML, anyway)
-but kludgey, and wouldn't support indented long lines that wrap.  But
-should inter-word whitespace (i.e., not leading whitespace) be
-preserved?  Currently it is preserved in line blocks.
-
-Representing a more complex line block may be tricky::
-
-     | But can a bee be said to be
-     |     or not to be an entire bee,
-     |         when half the bee is not a bee,
-     |             due to some ancient injury?
-
-Perhaps the representation could allow for nested line blocks::
-
-     
-
-With this model, leading whitespace would no longer be significant.
-Instead, left margins are implied by the nesting.  The example above
-could be represented as follows::
-
-     
-         
-             But can a bee be said to be
-         
-             
-                  or not to be an entire bee,
-             
-                 
-                     when half the bee is not a bee,
-                 
-                     
-                         due to some ancient injury?
-
-I wasn't sure what to do about even more complex line blocks::
-
-     |     Indented
-     | Not indented
-     |   Indented a bit
-     |     A bit more
-     |  Only one space
-
-How should that be parsed and nested?  Should the first line have
-the same nesting level (== indentation in the output) as the fourth
-line, or the same as the last line?  Mark Nodine suggested that such
-line blocks be parsed similarly to complexly-nested block quotes,
-which seems reasonable.  In the example above, this would result in
-the nesting of first line matching the last line's nesting.  In
-other words, the nesting would be relative to neighboring lines
-only.
-
-
-Output
-------
-
-In HTML, line blocks are currently output as "
    " blocks, which
-gives us significant whitespace and line breaks, but doesn't allow
-long lines to wrap and causes monospaced output without stylesheets.
-Instead, we could output "
    " elements parallelling the
-representation above, where each nested 
     would
-have an increased left margin (specified in the stylesheet).
-
-Jarno suggested the following HTML output::
-
-    
    
-       First, top level line
-       
    
-          Second, once nested
-          Third, once nested
-          ...
-       
    
-       ...
-    
    
-
-The ```` and `` `` are meant to support non-CSS and
-non-graphical browsers.  I understand the case for "br", but I'm not
-so sure about hidden " ".  I question how much effort should be
-put toward supporting non-graphical and especially non-CSS browsers,
-at least for html4css1.py output.
-
-Should the lines themselves be ```` or ``
    ``?  I don't like
-mixing inline and block-level elements.
-
-
-Implementation Plan
--------------------
-
-We'll leave the old implementation in place (via the "line-block"
-directive only) until all Writers have been updated to support the new
-syntax & implementation.  The "line-block" directive can then be
-updated to use the new internal representation, and its documentation
-will be updated to recommend the new syntax.
-
-
 List-Driven Tables
 ==================
 
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 7c773c425..9b2d6c65f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -786,10 +786,6 @@ __ rst/alternatives.html#or-not-to-do
   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
-- 
cgit v1.2.1


From 198d5c5a45884775674de0dd52aeae523128ad7b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 5 Oct 2004 01:27:41 +0000
Subject: new in 0.3.5

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2700 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 5b05f952d..f8c7787f4 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1156,7 +1156,7 @@ Syntax diagram::
 Line Blocks
 -----------
 
-Doctree elements: line_block, line.
+Doctree elements: line_block, line.  New in Docutils 0.3.5.
 
 Line blocks are useful for address blocks, verse (poetry, song
 lyrics), and unadorned lists, where the structure of lines is
-- 
cgit v1.2.1


From 2cdc5c5df80ff79387774cb8e89c982bc2cd2328 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 11 Oct 2004 16:34:11 +0000
Subject: created "Index Entries & Indexes" section in
 docs/dev/rst/alternatives.txt, moved from docs/dev/todo.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2705 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 132 ++++++++++++++++++++++++++++++++++++++++++
 docs/dev/todo.txt             |  95 +-----------------------------
 2 files changed, 134 insertions(+), 93 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 639212a25..02b916080 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -2386,6 +2386,138 @@ Issues:
       +------------------------++------------+----------+
 
 
+Index Entries & Indexes
+=======================
+
+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 `,
+    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::
+
+    
+    
+    Here's a 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::
+
+    
+    Here's a paragraph.
+    
+
+
+from 2002-06-24 docutils-develop posts
+--------------------------------------
+
+    If all of your index entries will appear verbatim in the text,
+    this should be sufficient.  If not (e.g., if you want "Van Rossum,
+    Guido" in the index but "Guido van Rossum" in the text), we'll
+    have to figure out a supplemental mechanism, perhaps using
+    substitutions.
+
+I've thought a bit more on this, and I came up with two possibilities:
+
+1. Using interpreted text, embed the index entry text within the
+   interpreted text::
+
+       ... by `Guido van Rossum [Van Rossum, Guido]` ...
+
+   The problem with this is obvious: the text becomes cluttered and
+   hard to read.  The processed output would drop the text in
+   brackets, which goes against the spirit of interpreted text.
+
+2. Use substitutions::
+
+       ... by |Guido van Rossum| ...
+
+       .. |Guido van Rossum| index:: Van Rossum, Guido
+
+   A problem with this is that each substitution definition must have
+   a unique name.  A subsequent ``.. |Guido van Rossum| index:: BDFL``
+   would be illegal.  Some kind of anonymous substitution definition
+   mechanism would be required, but I think that's going too far.
+
+Both of these alternatives are flawed.  Any other ideas?
+
+
 -------------------
  ... Or Not To Do?
 -------------------
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 9b2d6c65f..bd83bce0f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1316,99 +1316,8 @@ when used in a document.
 
   - _`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 `,
-        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::
-
-        
-        
-        Here's a 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::
-
-        
-        Here's a paragraph.
-        
+    See `Index Entries & Indexes
+    <./rst/alternatives.html#index-entries-indexes>`__.
 
   - _`body.literal`: Literal block, possibly "formal" (see `object
     numbering and object references`_ above).  Possible options:
-- 
cgit v1.2.1


From 6889b4137fe508a5c4de91b55c58c9714ec2c041 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 17 Oct 2004 23:06:53 +0000
Subject: updated docs to match new footnote-reference and
 footnote-reference-space-trimming behavior

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2709 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index ea0a70988..6508874f2 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -410,8 +410,12 @@ _`tab_width`
 _`trim_footnote_reference_space`
     Remove spaces before footnote references.
 
-    Default: don't (None).  Options:
-    ``--trim-footnote-reference-space``.
+    Default: don't (None); may be overriden by a writer-specific
+    footnote_references__ default though.  Options:
+    ``--trim-footnote-reference-space,
+    --leave-footnote-reference-space``.
+
+__ `footnote_references [latex2e writer]`_
 
 
 [readers]
@@ -519,8 +523,10 @@ footnote_references
     Format for footnote references, one of "superscript" or
     "brackets".  Also defined for the `LaTeX Writer`__.
 
-    Default: "superscript"; "brackets" in PEP/HTML Writer.  Options:
-    ``--footnote-references``.
+    Overrides [#override]_ trim_footnote_reference_space_, if
+    applicable. [#footnote_space]_
+
+    Default: "brackets".  Option: ``--footnote-references``.
 
     __ `footnote_references [latex2e writer]`_
 
@@ -674,7 +680,10 @@ footnote_references
     Format for footnote references: one of "superscript" or
     "brackets".  Also defined for the `HTML Writer`__.
 
-    Default: "brackets".  Option: ``--footnote-references``.
+    Overrides [#override]_ trim_footnote_reference_space_, if
+    applicable. [#footnote_space]_
+
+    Default: "superscript".  Option: ``--footnote-references``.
 
     __ `footnote_references [html4css1 writer]`_
 
@@ -836,6 +845,13 @@ _`_source`
      stylesheets are both unconditionally recorded as dependencies
      when using the LaTeX writer.
    
+.. [#footnote_space] The footnote space is trimmed if the reference
+   style is "superscript", and it is left if the reference style is
+   "brackets".
+
+   The overriding only happens if the parser supports the
+   trim_footnote_reference_space option.
+
 
 ------------------------------
 Old-Format Configuration Files
-- 
cgit v1.2.1


From 465c87e73035e8e8cefd444cfc7ab4fbcfbdec56 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 17 Oct 2004 23:47:37 +0000
Subject: removed implemented to-do list entry; added leftover bug -- I'm too
 tired right now to fix it

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2712 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 18 ++++--------------
 1 file changed, 4 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index bd83bce0f..ccd0ef120 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1000,20 +1000,10 @@ __ rst/alternatives.html#or-not-to-do
 
 * _`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.
+  When supplying the command line options
+  --footnote-references=brackets and --use-latex-footnotes with the
+  LaTeX writer (which might very well happen when using configuration
+  files), the spaces in front of footnote references aren't trimmed.
 
 * Enable _`tables inside XML comments`, where "--" ends comments.  I
   see three implementation possibilities:
-- 
cgit v1.2.1


From 2785ad18c6eba45a22c5dc1d8141c62332bd1f66 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Mon, 18 Oct 2004 23:39:41 +0000
Subject: updated description of compound paragraphs to what is really planned;
 we don't want to mix inline and block level elements

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2717 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index ccd0ef120..cb70e7dcf 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1337,9 +1337,10 @@ when used in a document.
 
     compound paragraph
         A paragraph containing embedded block-level elements such as
-        literal blocks, tables, lists, etc., in addition to directly
-        containing text and inline elements.  Compound paragraphs are
-        typically rendered as multiple distinct text blocks.
+        simple paragraphs, literal blocks, tables, lists, etc.,
+        instead of directly containing text and inline elements.
+        Compound paragraphs are typically rendered as multiple
+        distinct text blocks.
 
     simple paragraph
         A paragraph which directly contains only text and inline
-- 
cgit v1.2.1


From 213315b799f5fe8f0e18afc129d89e45204f5317 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 19 Oct 2004 22:40:53 +0000
Subject: minor cleanup

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2719 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index ff75b03d7..4a8c15cf1 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -209,7 +209,7 @@ http://www.oasis-open.org/html/tm9901.htm).
 
 
 
-
 
 
@@ -217,7 +217,7 @@ Eventual replacement for docinfo? -->
 
 
 
-
+
 
 
 
@@ -257,7 +257,7 @@ Eventual replacement for docinfo? -->
 
 
 
-          
+
 
 
 
@@ -267,7 +267,7 @@ Eventual replacement for docinfo? -->
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -->
 
-
 
 
@@ -369,7 +369,7 @@ or " ") or the text between option arguments (typically either "," or
     %basic.atts;
     %fixedspace.att;>
 
-
+
 
 
 
-- 
cgit v1.2.1


From 50ecea709bc5fe58c4f9085b4f6fa545e6927d25 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 19 Oct 2004 22:42:19 +0000
Subject: minor cleanup

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2720 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 4a8c15cf1..a9338d03a 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -115,7 +115,8 @@ resolve to either an internal or external reference.
 
 
 
 
 
 
+
+
+
 
 
Date: Tue, 19 Oct 2004 22:45:32 +0000
Subject: oops; revert 1.30

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2721 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index a9338d03a..4a8c15cf1 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -115,8 +115,7 @@ resolve to either an internal or external reference.
 
 
 
 
 
 
-
-
-
 
 
Date: Tue, 19 Oct 2004 22:46:07 +0000
Subject: added "compound" element

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2722 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 4a8c15cf1..a9338d03a 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -115,7 +115,8 @@ resolve to either an internal or external reference.
 
 
 
 
 
 
+
+
+
 
 
Date: Tue, 19 Oct 2004 23:29:44 +0000
Subject: added --strict-visitor option

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2723 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 6508874f2..1a49391ff 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -335,6 +335,14 @@ _`source_url`
     Default: compute if source_link (None).  Options: ``--source-url,
     --no-source-link``.
 
+_`strict_visitor`
+    When processing a document tree with the Visitor pattern, ignore
+    unknown node types listed as optional.  For transitional
+    development use.
+
+    Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
+    for development use only).
+
 _`toc_backlinks`
     Enable backlinks from section titles to table of contents entries
     ("entry"), to the top of the TOC ("top"), or disable ("none").
-- 
cgit v1.2.1


From 69b8abd9c0622b034d97f1b860314544d101554b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 20 Oct 2004 14:07:12 +0000
Subject: added "compound" directive docs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2735 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 50 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 685c6c446..9c54d7d43 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -567,6 +567,56 @@ The "pull-quote" directive produces a "pull-quote"-class block quote.
 See Epigraph_ above for an analogous example.
 
 
+.. _compound:
+
+Compound Paragraph
+==================
+
+:Directive Type: "compound"
+:Doctree Element: compound
+:Directive Arguments: None.
+:Directive Options: Possible.
+:Directive Content: Interpreted as body elements.
+
+(New in Docutils 0.3.6)
+
+The "compound" directive is used to create a compound paragraph, which
+is a single logical paragraph containing multiple physical body
+elements such as simple paragraphs, literal blocks, tables, lists,
+etc., instead of directly containing text and inline elements.  For
+example::
+
+    .. compound::
+
+       The 'rm' command is very dangerous.  If you are logged
+       in as root and enter these commands ::
+
+           cd /
+           rm -rf *
+
+       you will erase the entire contents of your file system.
+
+In the example above, a literal block is "embedded" within a sentence
+that begins in one physical paragraph and ends in another.  A compound
+paragraph
+
+Compound paragraphs are typically rendered as multiple distinct text
+blocks, with the possibility of variations to emphasize their logical
+unity:
+
+* If paragraphs are rendered with a first-line indent, only the first
+  physical paragraph of a compound paragraph should have that indent
+  -- second and further physical paragraphs should omit the indents;
+* vertical spacing between physical elements may be reduced;
+* and so on.
+
+The following option is recognized:
+
+``class`` : text
+    Set a "class" attribute value on the compound element.  See the
+    class_ directive below.
+
+
 --------
  Tables
 --------
-- 
cgit v1.2.1


From 4ffd31813cec1cbfc7b713b258cf0c0aa527c7c8 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Wed, 20 Oct 2004 16:22:04 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2739 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 9c54d7d43..07571f11e 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -589,7 +589,7 @@ example::
     .. compound::
 
        The 'rm' command is very dangerous.  If you are logged
-       in as root and enter these commands ::
+       in as root and enter these commands::
 
            cd /
            rm -rf *
@@ -597,8 +597,7 @@ example::
        you will erase the entire contents of your file system.
 
 In the example above, a literal block is "embedded" within a sentence
-that begins in one physical paragraph and ends in another.  A compound
-paragraph
+that begins in one physical paragraph and ends in another.
 
 Compound paragraphs are typically rendered as multiple distinct text
 blocks, with the possibility of variations to emphasize their logical
-- 
cgit v1.2.1


From 2ddb93c07ed872613266b5ff8cb01ed316fe873a Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Wed, 20 Oct 2004 23:11:25 +0000
Subject: added example for compound directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2749 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/demo.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

(limited to 'docs')

diff --git a/docs/user/rst/demo.txt b/docs/user/rst/demo.txt
index b8812ef18..4a3211c7c 100644
--- a/docs/user/rst/demo.txt
+++ b/docs/user/rst/demo.txt
@@ -497,6 +497,24 @@ I recommend you try |Python|_.
 
 .. |Python| replace:: Python, *the* best language around
 
+Compound Paragraph
+``````````````````
+
+.. compound::
+
+   This paragraph contains a literal block::
+
+       Connecting... OK
+       Transmitting data... OK
+       Disconnecting... OK
+      
+   and thus consists of a simple paragraph, a literal block, and
+   another simple paragraph.  Nonetheless it is semantically *one*
+   paragraph.
+
+This construct is called a *compound paragraph* and can be produced
+with the "compound" directive.
+
 Substitution Definitions
 ------------------------
 
-- 
cgit v1.2.1


From 7d9d0adc58d9bdd341d3aed623e2717f9da9d46e Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 21 Oct 2004 03:34:22 +0000
Subject: reworked text; this one is not a typo (no colon desired)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2753 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 07571f11e..e0328d94c 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -589,7 +589,7 @@ example::
     .. compound::
 
        The 'rm' command is very dangerous.  If you are logged
-       in as root and enter these commands::
+       in as root and enter ::
 
            cd /
            rm -rf *
-- 
cgit v1.2.1


From 6afac12eac4a055bc4c37fea0d00cd5e1b3c3e1f Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 22 Oct 2004 00:53:50 +0000
Subject: clarified text

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2758 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 1a49391ff..c5bdb6300 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -337,8 +337,8 @@ _`source_url`
 
 _`strict_visitor`
     When processing a document tree with the Visitor pattern, ignore
-    unknown node types listed as optional.  For transitional
-    development use.
+    raise an error if a writer does not support a nod types listed as
+    optional.  For transitional development use.
 
     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
     for development use only).
-- 
cgit v1.2.1


From fa9c91d1c2ad8f1cc5cd4ef5eba9c23bfc9ac250 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Fri, 22 Oct 2004 01:04:18 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2759 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index c5bdb6300..5fe169011 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -336,9 +336,9 @@ _`source_url`
     --no-source-link``.
 
 _`strict_visitor`
-    When processing a document tree with the Visitor pattern, ignore
-    raise an error if a writer does not support a nod types listed as
-    optional.  For transitional development use.
+    When processing a document tree with the Visitor pattern, raise an
+    error if a writer does not support a node type listed as optional.
+    For transitional development use.
 
     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
     for development use only).
-- 
cgit v1.2.1


From 04554113a5f8dada787e7c561954875fb036b4a2 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 22 Oct 2004 01:23:47 +0000
Subject: added directive; cleanup

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2760 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/cheatsheet.txt | 39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)

(limited to 'docs')

diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index df7a00b1a..b83b781c6 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -24,27 +24,27 @@ Grid table:
 | >>> print 'Doctest block'      |                                   |
 | Doctest block                  | > Quoted                          |
 +--------------------------------+-----------------------------------+
-| | Line blocks preserve line breaks & indents.                      |
+| | Line blocks preserve line breaks & indents. [new in 0.3.6]       |
 | |     Useful for addresses, verse, and adornment-free lists; long  |
 |       lines can be wrapped with continuation lines.                |
 +--------------------------------------------------------------------+
 
 Simple tables:
 
-================  ====================================================
+================  ============================================================
 List Type         Examples
-================  ====================================================
+================  ============================================================
 Bullet list       * items begin with "-", "+", or "*"
 Enumerated list   1. items use any variation of "1.", "A)", and "(i)"
 Definition list   Term is flush-left : optional classifier
                       Definition is indented, no blank line between
 Field list        :field name: field body
 Option list       -o  at least 2 spaces between option & description
-================  ====================================================
+================  ============================================================
 
-================  ====================================================
+================  ============================================================
 Explicit Markup   Examples (visible in the `text source `_)
-================  ====================================================
+================  ============================================================
 Footnote          .. [1] Manually numbered or [#] auto-numbered
                      (even [#labelled]) or [*] auto-symbol
 Citation          .. [CIT2002] A citation.
@@ -55,7 +55,7 @@ Anonymous Target  __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
 Directive ("::")  .. image:: images/biohazard.png
 Substitution Def  .. |substitution| replace:: like an inline directive
 Comment           .. is anything else
-================  ====================================================
+================  ============================================================
 
 Inline Markup
 =============
@@ -69,9 +69,9 @@ Directive Quick Reference
 =========================
 See  for full info.
 
-================  ====================================================
-Directive Name    Description
-================  ====================================================
+================  ============================================================
+Directive Name    Description (Docutils version added to, in [brackets])
+================  ============================================================
 attention         Specific admonition; also "caution", "danger",
                   "error", "hint", "important", "note", "tip", "warning"
 admonition        Generic titled admonition: ``.. admonition:: By The Way``
@@ -82,11 +82,12 @@ sidebar           ``.. sidebar:: Title``; like a mini parallel document
 parsed-literal    A literal block with parsed inline markup
 rubric            ``.. rubric:: Informal Heading``
 epigraph          Block quote with class="epigraph"
-highlights        Block quote with class="highlights" 
+highlights        Block quote with class="highlights"
 pull-quote        Block quote with class="pull-quote"
-table             Create a titled table (new in Docutils 0.3.1)
-csv-table         Create a titled table from CSV data (requires Python 2.3+;
-                  new in Docutils 0.3.4)
+compound          Compound paragraphs [0.3.6]
+table             Create a titled table [0.3.1]
+csv-table         Create a titled table from CSV data (requires Python 2.3+)
+                  [0.3.4]
 contents          Generate a table of contents
 sectnum           Automatically number sections, subsections, etc.
 target-notes      Create an explicit footnote for each external target
@@ -96,16 +97,16 @@ raw               Non-reST data passed untouched to the Writer
 replace           Replacement text for substitution definitions
 unicode           Unicode character code conversion for substitution defs
 class             Set a "class" attribute on the next element
-role              Create a custom interpreted text role (new in Docutils 0.3.2)
-================  ====================================================
+role              Create a custom interpreted text role [0.3.2]
+================  ============================================================
 
 Interpreted Text Role Quick Reference
 =====================================
 See  for full info.
 
-================  ====================================================
+================  ============================================================
 Role Name         Description
-================  ====================================================
+================  ============================================================
 emphasis          Equivalent to *emphasis*
 literal           Equivalent to ``literal`` but processes backslash escapes
 PEP               Reference to a numbered Python Enhancement Proposal
@@ -114,4 +115,4 @@ strong            Equivalent to **strong**
 sub               Subscript
 sup               Superscript
 title             Title reference (book, etc.); standard default role
-================  ====================================================
+================  ============================================================
-- 
cgit v1.2.1


From bb10e40d88e30feef6fc125bf172b7c9125c8124 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 30 Oct 2004 14:22:20 +0000
Subject: removed to do list entry about transitions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2776 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 12 ------------
 1 file changed, 12 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index cb70e7dcf..e12eb7adb 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -958,18 +958,6 @@ __ rst/alternatives.html#or-not-to-do
 
       .. _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::
-
-      
-
 * Add an option to allow arbitrary URI schemes (not just those in
   urischemes.py)?  This would make text like "signal:noise" into a
   URI.
-- 
cgit v1.2.1


From b88302881a584c7dc5382b1b9188fb73392fd4f1 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 30 Oct 2004 14:23:32 +0000
Subject: updated DTD to allow transitions between sections

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2777 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index a9338d03a..faaf3f6de 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -141,10 +141,11 @@ resolve to either an internal or external reference.
 ================================================================== -->
 
 
+   " ( ( (%body.elements; | topic | sidebar)+,
+         (transition, (%body.elements; | topic | sidebar)+ )*,
+         ( (%section.elements;), (transition?, (%section.elements;) )* ) )
+     | ( (%section.elements;), (transition?, (%section.elements;) )* )
+) ">
 
 
@@ -182,7 +183,9 @@ http://www.oasis-open.org/html/tm9901.htm).
 
 
 
+    ((title, subtitle?)?,
+    ((docinfo, decoration?, transition?) | decoration?),
+    %structure.model;)>
 
 
 
 
-- 
cgit v1.2.1


From 8ba1d9d714d6bfe722332deeeaa279ac6cc11eb1 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 2 Nov 2004 22:14:08 +0000
Subject: Added "ltrim" and "rtrim" attributes to ``substitution_definition``
 element.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2794 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 6970b19b7..5d858b2a8 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -447,7 +447,10 @@ or " ") or the text between option arguments (typically either "," or
     %anonymous.att;>
 
 
-
+
 
 
 
Date: Tue, 2 Nov 2004 22:14:14 +0000
Subject: Added "trim", "ltrim", and "rtrim" options to "unicode" directive.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2795 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index e0328d94c..60058ac27 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1147,7 +1147,7 @@ Unicode Character Codes
 :Doctree Element: Text
 :Directive Arguments: One or more, required (Unicode character codes,
                       optional text, and comments).
-:Directive Options: None.
+:Directive Options: Possible.
 :Directive Content: None.
 
 The "unicode" directive converts Unicode character codes (numerical
@@ -1175,6 +1175,7 @@ For example, the following text::
     Copyright |copy| 2003, |BogusMegaCorp (TM)|.
 
     .. |copy| unicode:: 0xA9 .. copyright sign
+       :ltrim:
     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
        .. with trademark sign
 
@@ -1183,9 +1184,22 @@ results in:
     Copyright |copy| 2003, |BogusMegaCorp (TM)|.
 
     .. |copy| unicode:: 0xA9 .. copyright sign
+       :ltrim:
     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
        .. with trademark sign
 
+The following options are recognized:
+
+``ltrim`` : flag
+    Whitespace to the left of the substitution reference is removed.
+
+``rtrim`` : flag
+    Whitespace to the right of the substitution reference is removed.
+
+``trim`` : flag
+    Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
+    of the substitution reference is removed.
+
 
 Class
 =====
-- 
cgit v1.2.1


From b7ca1d367a9b0c8fbb13e5e9434586a0a025752b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 2 Nov 2004 22:25:37 +0000
Subject: improved example

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2798 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 60058ac27..727327cd3 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1172,21 +1172,25 @@ Hexadecimal codes are case-insensitive.
 
 For example, the following text::
 
-    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
+    all rights reserved.
 
     .. |copy| unicode:: 0xA9 .. copyright sign
-       :ltrim:
     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
        .. with trademark sign
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
 
 results in:
 
-    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
+    all rights reserved.
 
     .. |copy| unicode:: 0xA9 .. copyright sign
-       :ltrim:
     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
        .. with trademark sign
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
 
 The following options are recognized:
 
-- 
cgit v1.2.1


From a6a2dd50bbaaea7412ef021329d7b3b518636583 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 3 Nov 2004 14:31:26 +0000
Subject: Enabled multiple format names for "raw" directive.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2799 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd       |  2 +-
 docs/ref/rst/directives.txt | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 5d858b2a8..86f4e0357 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -500,7 +500,7 @@ Table elements: table, tgroup, colspec, thead, tbody, row, entry.
 
+    format    NMTOKENS  #IMPLIED>
 
 
 
 
 
-
+
 
 
 
-- 
cgit v1.2.1


From 09367b914711e1c22a65e1e82dc421c4d45a5b85 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 3 Nov 2004 20:10:50 +0000
Subject: Definition list items may have multiple classifiers.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2801 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index f8c7787f4..a5cd99745 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -740,10 +740,10 @@ Definition Lists
 Doctree elements: definition_list, definition_list_item, term,
 classifier, definition.
 
-Each definition list item contains a term, an optional classifier, and
-a definition.  A term is a simple one-line word or phrase.  An
-optional classifier may follow the term on the same line, after an
-inline " : " (space, colon, space).  A definition is a block indented
+Each definition list item contains a term, optional classifiers, and a
+definition.  A term is a simple one-line word or phrase.  Optional
+classifiers may follow the term on the same line, each after an inline
+" : " (space, colon, space).  A definition is a block indented
 relative to the term, and may contain multiple paragraphs and other
 body elements.  There may be no blank line between a term line and a
 definition block (this distinguishes definition lists from `block
@@ -761,7 +761,10 @@ last definition list item, but are optional in-between.  For example::
     term 3 : classifier
         Definition 3.
 
-Inline markup is parsed in the term line before the term/classifier
+    term 4 : classifier one : classifier two
+        Definition 4.
+
+Inline markup is parsed in the term line before the classifier
 delimiter (" : ") is recognized.  The delimiter will only be
 recognized if it appears outside of any inline markup.
 
@@ -780,12 +783,12 @@ A definition list may be used in various ways, including:
 
 Syntax diagram::
 
-    +---------------------------+
-    | term [ " : " classifier ] |
-    +--+------------------------+--+
-       | definition                |
-       | (body elements)+          |
-       +---------------------------+
+    +----------------------------+
+    | term [ " : " classifier ]* |
+    +--+-------------------------+--+
+       | definition                 |
+       | (body elements)+           |
+       +----------------------------+
 
 
 Field Lists
-- 
cgit v1.2.1


From 1fc88a1b648b96717a3126bc46e97962e7a9b737 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 3 Nov 2004 20:14:38 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2804 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index e0d200626..d4400c863 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -268,6 +268,16 @@ ordinary comments that are then block-commented.  This applies to
 double-hash-marks on the first line only as well.  So they're out.
 
 
+Update
+``````
+
+Enthought's Traits system has switched to a metaclass base, and traits
+are now defined via ordinary attributes.  Therefore doc comments are
+no longer absolutely necessary; attribute docstrings will suffice.
+Doc comments may still be desirable though, since they allow
+documentation to precede the thing being documented.
+
+
 Docstring Density & Whitespace Minimization
 -------------------------------------------
 
-- 
cgit v1.2.1


From 1b493552e93c8497137b6d10ae0b3759021a621a Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 3 Nov 2004 20:31:28 +0000
Subject: a new idea for whitespace minimization in definition lists

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2805 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 70 +++++++++++++++++++++++++++------------------
 1 file changed, 42 insertions(+), 28 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index d4400c863..c3fb7584d 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -317,7 +317,7 @@ current Enthought code (from lib/cp/fluids/gassmann.py)::
 The docstring is 24 lines long.
 
 Rather than using subsections, field lists (which exist now) can save
-5 lines::
+6 lines::
 
     def max_gas(temperature, pressure, api, specific_gravity=.56):
         """
@@ -336,13 +336,15 @@ Rather than using subsections, field lists (which exist now) can save
         :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).
+        :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...
 
+As with the "Description" field above, field bodies may begin on the
+same line as the field name, which also saves space.
+
 The output for field lists is typically a table structure.  For
 example:
 
@@ -371,24 +373,37 @@ Definition lists are currently defined as::
     term : classifier
         definition
 
-Where the classifier part is optional.
+Where the classifier part is optional.  Ideas for improvements:
+
+1. We could allow multiple classifiers::
+
+       term : classifier one : two : three ...
+           definition
+
+2. We could allow the definition on the same line as the term.
+
+   * "--" could be used, but only in limited and well-known contexts::
 
-* We could allow multiple classifiers::
+         term -- definition
 
-      term : classifier one : two : three ...
-          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 (or would it?).  That context
+     would be: in docstrings, within a field list, perhaps only with
+     certain well-defined field names (parameters, returns).
 
-* We could allow the definition on the same line as the term, but only
-  in limited and well-known contexts::
+   * The "constrained context" above isn't really enough to make the
+     ambiguity acceptable.  Instead, a slightly more verbose but far
+     less ambiguous syntax is possible::
 
-      term -- definition
+         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).
+     This syntax has advantages.  Equals signs lend themselves to the
+     connotation of "definition".  And whereas one or two equals signs
+     are commonly used in program code, three equals signs in a row
+     have no conflicting meanings that I know of.
 
 
 Recommendation
@@ -402,20 +417,19 @@ Combining these ideas, the function definition becomes::
         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
+            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).
+            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
+The docstring is reduced to 14 lines, from the original 24.  For
 longer docstrings with many parameters and return values, the
 difference would be more significant.
-- 
cgit v1.2.1


From e9dfe607c9272e5672166280bd59cef4c68aae86 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 3 Nov 2004 20:36:03 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2806 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index c3fb7584d..38d865605 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -294,7 +294,7 @@ current Enthought code (from lib/cp/fluids/gassmann.py)::
         ----------
         temperature : sequence
             Temperature in degrees Celsius
-        pressure: sequence
+        pressure : sequence
             Pressure in MPa
         api : sequence
             Stock tank oil API
@@ -327,7 +327,7 @@ Rather than using subsections, field lists (which exist now) can save
         :Parameters:
             temperature : sequence
                 Temperature in degrees Celsius
-            pressure: sequence
+            pressure : sequence
                 Pressure in MPa
             api : sequence
                 Stock tank oil API
@@ -351,7 +351,7 @@ example:
     :Parameters:
         temperature : sequence
             Temperature in degrees Celsius
-        pressure: sequence
+        pressure : sequence
             Pressure in MPa
         api : sequence
             Stock tank oil API
@@ -418,7 +418,7 @@ Combining these ideas, the function definition becomes::
 
         :Parameters:
             temperature : sequence === Temperature in degrees Celsius
-            pressure: sequence === Pressure in MPa
+            pressure : sequence === Pressure in MPa
             api : sequence === Stock tank oil API
             specific_gravity : sequence === Specific gravity of gas at
                 STP, default is .56
-- 
cgit v1.2.1


From 4bc20118dae38fa68bc2fbfaa6f59698e1393ee3 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sat, 6 Nov 2004 17:13:44 +0000
Subject: "Class" directive now allows multiple class names. Added "Rationale
 for Class Attribute Value Conversion".

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2809 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 51 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 43 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index a58c82bbc..49ce3e97e 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1210,17 +1210,19 @@ Class
 
 :Directive Type: "class"
 :Doctree Element: pending
-:Directive Arguments: One, required (class name / attribute value).
+:Directive Arguments: One or more, required (class names / attribute
+                      values).
 :Directive Options: None.
 :Directive Content: None.
 
 The "class" directive sets a "class" attribute value on the first
 immediately following non-comment element [#]_.  For details of the
 "class" attribute, see `its entry`__ in `The Docutils Document Tree`_.
-The "class" attribute value is converted to lowercase and all
-non-alphanumeric characters are converted to hyphens in order to match
-this regular expression: ``[a-z](-?[a-z0-9]+)*``.  See the docstring
-from ``docutils.nodes.make_id`` for the rationale.
+The directive argument consists of one or more space-separated class
+names, which are converted to lowercase and all non-alphanumeric
+characters are converted to hyphens.  (For the rationale, see below.)
+
+__ ../doctree.html#class
 
 Examples::
 
@@ -1228,7 +1230,7 @@ Examples::
 
     This is a "special" paragraph.
 
-    .. class:: exceptional
+    .. class:: exceptional remarkable
 
     An Exceptional Section
     ======================
@@ -1239,7 +1241,7 @@ The text above is parsed and transformed into this doctree fragment::
 
     
         This is a "special" paragraph.
-    
    
+    
    
         
             An Exceptional Section
         <paragraph>
@@ -1258,7 +1260,40 @@ The text above is parsed and transformed into this doctree fragment::
    the block quote text would be interpreted as the "class"
    directive's content, and the parser would complain.
 
-__ ../doctree.html#class
+.. topic:: Rationale for Class Attribute Value Conversion
+
+    Docutils identifiers are converted to conform to the regular
+    expression ``[a-z](-?[a-z0-9]+)*``.  For CSS compatibility,
+    identifiers (the "class" and "id" attributes) should have no
+    underscores, colons, or periods.  Hyphens may be used.
+
+    - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
+
+          ID and NAME tokens must begin with a letter ([A-Za-z]) and
+          may be followed by any number of letters, digits ([0-9]),
+          hyphens ("-"), underscores ("_"), colons (":"), and periods
+          (".").
+
+    - However the `CSS1 spec`_ defines identifiers based on the "name"
+      token, a tighter interpretation ("flex" tokenizer notation
+      below; "latin1" and "escape" 8-bit characters have been replaced
+      with entities)::
+
+          unicode     \\[0-9a-f]{1,4}
+          latin1      [¡-ÿ]
+          escape      {unicode}|\\[ -~¡-ÿ]
+          nmchar      [-a-z0-9]|{latin1}|{escape}
+          name        {nmchar}+
+
+    The CSS1 "nmchar" rule does not include underscores ("_"), colons
+    (":"), or periods ("."), therefore "class" and "id" attributes
+    should not contain these characters.  They should be replaced with
+    hyphens ("-").  Combined with HTML's requirements (the first
+    character must be a letter; no "unicode", "latin1", or "escape"
+    characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern.
+
+    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
+    .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
 
 
 .. _role:
-- 
cgit v1.2.1


From ef518f2f9721f4e329b5d46b02ba81875c57702f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 19:51:17 +0000
Subject: Added warning about "raw" overuse/abuse

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2813 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 49ce3e97e..0684f0d73 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1067,6 +1067,19 @@ Raw Data Pass-Through
 :Directive Content: Stored verbatim, uninterpreted.  None (empty) if a
                     "file" or "url" option given.
 
+.. WARNING::
+
+   The "raw" directive is a stop-gap measure allowing the author to
+   bypass reStructuredText's markup.  It is a "power-user" feature
+   that should not be overused or abused.  The use of "raw" ties
+   documents to specific output formats and makes them less portable.
+
+   If you often need to use the "raw" directive or a "raw"-derived
+   interpreted text role, that is a sign either of overuse/abuse or
+   that functionality may be missing from reStructuredText.  Please
+   describe your situation in email to
+   docutils-users@lists.sourceforge.net.
+
 The "raw" directive indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  The names of the output formats are
 given in the directive arguments.  The interpretation of the raw data
@@ -1303,7 +1316,7 @@ Custom Interpreted Text Roles
 
 :Directive Type: "role"
 :Doctree Element: None; affects subsequent parsing.
-:Directive Arguments: Two; one required (role name), one optional
+:Directive Arguments: Two; one required (new role name), one optional
                       (base role name, in parentheses).
 :Directive Options: Possible (depends on base role).
 :Directive Content: depends on base role.
-- 
cgit v1.2.1


From d74ca66c1c0d32c7447bfcd10c3c02ad9ea40123 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 19:51:39 +0000
Subject: Added "raw" role

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2814 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/roles.txt | 66 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index 4aa6b0337..76bb87a19 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -50,16 +50,16 @@ Custom interpreted text roles may be defined in a document with the
 
 .. _class:
 
-The ``class`` option is recognized by the "role" directive for most
-interpreted text roles.  A description__ is provided by `"role"
+A ``class`` option is recognized by the "role" directive for most
+interpreted text roles.  A description__ is provided in the `"role"
 directive`_ documentation.
 
 __ directives.html#role-class
 
 
----------------------------------
- Standard Interpreted Text Roles
----------------------------------
+----------------
+ Standard Roles
+----------------
 
 ``:emphasis:``
 ==============
@@ -251,3 +251,59 @@ must be used to obtain a ``title_reference`` element.
 
 
 .. _pseudo-XML: ../doctree.html#pseudo-xml
+
+
+-------------------
+ Specialized Roles
+-------------------
+
+``raw``
+=======
+
+:Aliases: None
+:DTD Element: raw
+:Customization:
+    :Options: class_, format
+    :Content: None
+
+.. WARNING::
+
+   The "raw" role is a stop-gap measure allowing the author to bypass
+   reStructuredText's markup.  It is a "power-user" feature that
+   should not be overused or abused.  The use of "raw" ties documents
+   to specific output formats and makes them less portable.
+
+   If you often need to use "raw"-derived interpreted text roles or
+   the "raw" directive, that is a sign either of overuse/abuse or that
+   functionality may be missing from reStructuredText.  Please
+   describe your situation in email to
+   docutils-users@lists.sourceforge.net.
+
+The "raw" role indicates non-reStructuredText data that is to be
+passed untouched to the Writer.  It is the inline equivalent of the
+`"raw" directive`_; see its documentation for details on the
+semantics.
+
+.. _"raw" directive: directives.html#raw
+
+The "raw" role cannot be used directly.  The `"role" directive`_ must
+first be used to build custom roles based on the "raw" role.  One or
+more formats (Writer names) must be provided in a "format" option.
+
+For example, the following creates an HTML-specific "html" role::
+
+    .. role:: html(raw)
+       :format: html
+
+This role can now be used directly to pass data untouched to the HTML
+Writer.  For example::
+
+    If there just *has* to have a line break here,
+    :html:`<br />`
+    it can be accomplished with a "raw"-derived role.
+    But the line block syntax should be considered first.
+
+In addition to "class_", the following option is recognized:
+
+``format`` : text
+    One or more space-separated output format names (Writer names).
-- 
cgit v1.2.1


From 0ffddaffff2273f74c49350a1eba4088106c75b0 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 19:53:36 +0000
Subject: updated doc comment recommendation

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2819 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index 38d865605..f73342fa4 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -267,6 +267,14 @@ 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.
 
+On the other hand, the JavaDoc-comment style ("##" on the first line
+only, "#" after that) is used in Fredrik Lundh's PythonDoc_.  It may
+be worthwhile to conform to this syntax, reinforcing it as a standard.
+PythonDoc does not support terse doc comments (text after "##" on the
+first line).
+
+.. _PythonDoc: http://effbot.org/zone/pythondoc.htm
+
 
 Update
 ``````
-- 
cgit v1.2.1


From 2297960e073dc03efdbe8a55ff3fa0cb3bed5297 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 20:06:37 +0000
Subject: clarified hack nature of "raw" a bit

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2820 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/roles.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index 76bb87a19..9327f1359 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -292,14 +292,14 @@ more formats (Writer names) must be provided in a "format" option.
 
 For example, the following creates an HTML-specific "html" role::
 
-    .. role:: html(raw)
+    .. role:: raw-html(raw)
        :format: html
 
 This role can now be used directly to pass data untouched to the HTML
 Writer.  For example::
 
     If there just *has* to have a line break here,
-    :html:`<br />`
+    :raw-html:`<br />`
     it can be accomplished with a "raw"-derived role.
     But the line block syntax should be considered first.
 
-- 
cgit v1.2.1


From 023826bace870713f61f613309b01e056b2c7fa0 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 20:21:40 +0000
Subject: further clarification of hack nature of "raw"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2821 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/roles.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index 9327f1359..562a6c8b0 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -290,7 +290,7 @@ The "raw" role cannot be used directly.  The `"role" directive`_ must
 first be used to build custom roles based on the "raw" role.  One or
 more formats (Writer names) must be provided in a "format" option.
 
-For example, the following creates an HTML-specific "html" role::
+For example, the following creates an HTML-specific "raw-html" role::
 
     .. role:: raw-html(raw)
        :format: html
@@ -303,6 +303,10 @@ Writer.  For example::
     it can be accomplished with a "raw"-derived role.
     But the line block syntax should be considered first.
 
+.. Tip:: Roles based on "raw" should clearly indicate their origin, so
+   they are not mistaken for reStructuredText markup.  Using a "raw-"
+   prefix for role names is recommended.
+
 In addition to "class_", the following option is recognized:
 
 ``format`` : text
-- 
cgit v1.2.1


From 10de3f2fff5c4d7d745cdd3240d9c59a1ea25b1c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 20:49:55 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2822 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/roles.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index 562a6c8b0..a911cf469 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -298,7 +298,7 @@ For example, the following creates an HTML-specific "raw-html" role::
 This role can now be used directly to pass data untouched to the HTML
 Writer.  For example::
 
-    If there just *has* to have a line break here,
+    If there just *has* to be a line break here,
     :raw-html:`<br />`
     it can be accomplished with a "raw"-derived role.
     But the line block syntax should be considered first.
-- 
cgit v1.2.1


From 4742d103e3cfbc8bc8995d5a05133a3761117c26 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 6 Nov 2004 21:01:56 +0000
Subject: added "raw" role

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2823 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/cheatsheet.txt | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs')

diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index b83b781c6..6a0172a59 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -111,6 +111,7 @@ emphasis          Equivalent to *emphasis*
 literal           Equivalent to ``literal`` but processes backslash escapes
 PEP               Reference to a numbered Python Enhancement Proposal
 RFC               Reference to a numbered Internet Request For Comments
+raw               For non-reST data; cannot be used directly (see docs) [0.3.6]
 strong            Equivalent to **strong**
 sub               Subscript
 sup               Superscript
-- 
cgit v1.2.1


From 5981748846d68dda006e8e553353e4569b7c3899 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 8 Nov 2004 17:22:33 +0000
Subject: updated doctree to match real behavior: list_items may be empty

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2833 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt  | 2 +-
 docs/ref/docutils.dtd | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 5a5154fe7..34784a2ed 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -2650,7 +2650,7 @@ Content Model
 
 .. parsed-literal::
 
-    (`%body.elements;`_)+
+    (`%body.elements;`_)*
 
 :Attributes:
     The ``list_item`` element contains only the `common attributes`_:
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 71636c152..6d0e947b3 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -310,7 +310,7 @@ Eventual replacement for docinfo? -->
     suffix    CDATA     #IMPLIED
     start     %number;  #IMPLIED>
 
-<!ELEMENT list_item (%body.elements;)+>
+<!ELEMENT list_item (%body.elements;)*>
 <!ATTLIST list_item %basic.atts;>
 
 <!ELEMENT definition_list (definition_list_item+)>
-- 
cgit v1.2.1


From 2fd771ad121a2311c5279955876e4c0ed6dad3bd Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 10 Nov 2004 15:46:34 +0000
Subject: added section descriptions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2841 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 02b916080..1c33c8522 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -14,6 +14,21 @@ originate with StructuredText or Setext, please see `Problems With
 StructuredText`_.  See the `reStructuredText Markup Specification`_
 for full details of the established syntax.
 
+The ideas are divided into sections:
+
+* Implemented_: already done.  The issues and alternatives are
+  recorded here for posterity.
+
+* `Not Implemented`_: these ideas won't be implemented.
+
+* Tabled_: these ideas should be revisited in the future.
+
+* `To Do`_: these ideas should be implemented.  They're just waiting
+  for a champion to resolve issues and get them done.
+
+* `... Or Not To Do?`_: possible but questionable.  These probably
+  won't be implemented, but you never know.
+
 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
 .. _StructuredText:
    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
-- 
cgit v1.2.1


From b6e0dfa4e0e3f2714560b69ad1c4a29b13f6aab6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 10 Nov 2004 18:28:25 +0000
Subject: removed to-do entry about compound paragraphs; has been implemented

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2842 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 57 -------------------------------------------------------
 1 file changed, 57 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index e12eb7adb..b3cd332ce 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1321,63 +1321,6 @@ when used in a document.
   - _`body.list-table`: See `List-Driven Tables
     <rst/alternatives.html#list-driven-tables>`_.
 
-  - _`body.compound` (working name only):
-
-    compound paragraph
-        A paragraph containing embedded block-level elements such as
-        simple paragraphs, literal blocks, tables, lists, etc.,
-        instead of directly containing text and inline elements.
-        Compound paragraphs are typically rendered as multiple
-        distinct text blocks.
-
-    simple paragraph
-        A paragraph which directly contains only text and inline
-        elements (like "emphasis").  Simple paragraphs can always be
-        rendered in a single contiguous text block.
-
-    When writing a paragraph, sometimes one wants to say something
-    like::
-
-        .. compound::
-
-           The 'rm' command is very dangerous.  If you are logged
-           in as root and enter these commands ::
-
-               cd /
-               rm -rf *
-
-           you will erase the entire contents of your file
-           system.
-
-    The literal block is essentially embedded in the middle of a
-    sentence, in a single "compound paragraph".  The second part of
-    the paragraph may be rendered differently than the first part
-    (e.g., no indentation of the first line).
-
-    The document model will need to be extended, probably like this::
-
-        <compound>
-            <paragraph>
-                This is a paragraph, containing an
-            <literal_block>
-                embedded literal block
-            <paragraph>
-                between segments.
-
-    The decision directive & element name has not been decided.  So
-    far, the contenders are:
-
-    * compound
-    * paragraph
-    * block
-
-    Looking at the DTD and at docs/ref/doctree.txt, there don't seem
-    to be any non-paragraph cases.  Every other element that directly
-    contains text is either inline (i.e., occurs within paragraphs) or
-    specialized and atomic (like literal blocks or titles) and would
-    never be "continued".  Paragraphs seem to be unique in this sense
-    among the elements.
-
   - _`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"
-- 
cgit v1.2.1


From e62360fd94318c825cdd35625f4a8f667371ba4d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 10 Nov 2004 19:17:45 +0000
Subject: added to-do list entry for :trim: option in reST section

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2843 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b3cd332ce..bcd821f2f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -608,6 +608,15 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Allow the _`:trim:` option for all directives when they occur in a
+  substitution definition, not only the unicode_ directive.
+
+  Allow other characters than spaces to be trimmed (e.g. ``:trim: -``
+  for trimming hyphens).
+
+  .. _unicode:
+     http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
+  
 * 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
-- 
cgit v1.2.1


From 6a4a31bd5ac2799bc92c5be4ed33baef8c111c9d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 11 Nov 2004 22:07:51 +0000
Subject: removed entry about trimming non-space characters

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2844 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index bcd821f2f..f6ad368c9 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -611,9 +611,6 @@ __ rst/alternatives.html#or-not-to-do
 * Allow the _`:trim:` option for all directives when they occur in a
   substitution definition, not only the unicode_ directive.
 
-  Allow other characters than spaces to be trimmed (e.g. ``:trim: -``
-  for trimming hyphens).
-
   .. _unicode:
      http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
   
-- 
cgit v1.2.1


From 690499295b4194af7f0a6ac915364f609dfb66ee Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 19 Nov 2004 20:48:55 +0000
Subject: Flushed my personal to-do list, because I currently don't have enough
 time for tackling the issues.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2865 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f6ad368c9..bdf340363 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -58,6 +58,23 @@ General
     checked for correctness and refactored.  I'm afraid it's a bit of
     a spaghetti mess now.
 
+* Configuration file handling needs discussion:
+
+  - There should be some error checking on the contents of config
+    files.  How much checking should be done?  How loudly should
+    Docutils complain if it encounters an error/problem?
+
+  - Docutils doesn't complain when it doesn't find a configuration
+    file supplied with the ``--config`` option.  Should it?  (If yes,
+    error or warning?)
+
+  - Is a system-wide configuration file (in ``/etc/docutils.conf``) a
+    good idea?
+
+  - ``~/.docutils`` does not work (because the tilde is only expanded
+    by the shell).  Is a user-specific configuration file really
+    necessary?  Maybe the name (``.docutils``) needs discussion, too.
+
 * Language modules: in accented languages it may be useful to have
   both accented and unaccented entries in the ``bibliographic_fields``
   mapping for versatility.
@@ -428,7 +445,9 @@ Documentation
 User Docs
 ---------
 
-What else is needed?
+* Add a FAQ entry about using Docutils (with reStructuredText) on a
+  server and that it's terribly slow.  See the first paragraphs in
+  <http://article.gmane.org/gmane.text.docutils.user/1584>.
 
 
 Developer Docs
@@ -608,6 +627,9 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Add (functional) tests for the "raw" role, its class attribute, and
+  the other roles as well.
+
 * Allow the _`:trim:` option for all directives when they occur in a
   substitution definition, not only the unicode_ directive.
 
-- 
cgit v1.2.1


From a673ffc183e5c83b090e28ef45019639adc851f7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 24 Nov 2004 15:54:55 +0000
Subject: removed bug about ~/.docutils (was wrong)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2867 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index bdf340363..51c7e5405 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -71,8 +71,7 @@ General
   - Is a system-wide configuration file (in ``/etc/docutils.conf``) a
     good idea?
 
-  - ``~/.docutils`` does not work (because the tilde is only expanded
-    by the shell).  Is a user-specific configuration file really
+  - Is a user-specific configuration file (``~/.docutils``) really
     necessary?  Maybe the name (``.docutils``) needs discussion, too.
 
 * Language modules: in accented languages it may be useful to have
-- 
cgit v1.2.1


From dbd944e80a6f67bea3f3b0e332a3b0c34ee618f5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 25 Nov 2004 11:26:34 +0000
Subject: removed no_random option; SF's Python doesn't seem to be broken
 anymore

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2868 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 6 ------
 1 file changed, 6 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 5fe169011..07fa26460 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -590,12 +590,6 @@ The PEP/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
 "[html4css1 writer]" section is processed before "[pep_html writer]".
 
-_`no_random`
-    Workaround for platforms which core-dump on "``import random``".
-
-    Default: random enabled (None).  Options: ``--no-random``
-    (hidden).
-
 _`pep_home`
     Home URL prefix for PEPs.
 
-- 
cgit v1.2.1


From a33879a926ba9d3beffcc35e5f8c45cb62e85ce4 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Nov 2004 09:27:55 +0000
Subject: allow empty sections and documents

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2870 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt  | 20 ++++++++------------
 docs/ref/docutils.dtd |  2 +-
 2 files changed, 9 insertions(+), 13 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 34784a2ed..fc8e9ae3a 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -4806,18 +4806,14 @@ Entity definition:
     ( ( (`%body.elements;`_ | topic_ | sidebar_)+,
         (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*,
         ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
-    | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) ) ">
-
-Each document_ or section_ contains either:
-
-- multiple body elements, topics, and/or sidebars, optionally
-  interspersed with transitions (but transitions cannot occur at the
-  beginning or end, nor may there be two transitions in a row),
-  followed by zero or more sections optionally interspersed with
-  transitions; or
-
-- one or more sections (whose contents are recursively the same as
-  this model) optionally interspersed with transitions.
+    | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) )? ">
+
+Each document_ or section_ contains zero or more body elements,
+topics, and/or sidebars, optionally interspersed with transitions (but
+transitions cannot occur at the beginning or end, nor may there be two
+transitions in a row), followed by zero or more sections (whose
+contents are recursively the same as this model) optionally
+interspersed with transitions.
 
 The `%structure.model;`_ parameter entity is directly employed in the
 content models of the document_ and section_ elements.
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 6d0e947b3..3d3ae4956 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -144,7 +144,7 @@ resolve to either an internal or external reference.
    " ( ( (%body.elements; | topic | sidebar)+,
          (transition, (%body.elements; | topic | sidebar)+ )*,
          ( (%section.elements;), (transition?, (%section.elements;) )* )? )
-     | ( (%section.elements;), (transition?, (%section.elements;) )* ) ) ">
+     | ( (%section.elements;), (transition?, (%section.elements;) )* ) )? ">
 
 <!ENTITY % text.model
   " (#PCDATA | %inline.elements;)* ">
-- 
cgit v1.2.1


From c27c1ce9f7115bf7b69580be3b3d873ecc06afe1 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Nov 2004 15:42:37 +0000
Subject: simplified structure model and clarified restrictions on transitions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2872 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt  | 29 ++++++++++++++++++++---------
 docs/ref/docutils.dtd |  7 +++----
 2 files changed, 23 insertions(+), 13 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index fc8e9ae3a..43ce91d33 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -4803,17 +4803,28 @@ Entity definition:
 
 .. parsed-literal::
 
-    ( ( (`%body.elements;`_ | topic_ | sidebar_)+,
-        (transition_, (`%body.elements;`_ | topic_ | sidebar_)+ )*,
-        ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
-    | ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* ) )? ">
+   ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
+     ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
 
 Each document_ or section_ contains zero or more body elements,
-topics, and/or sidebars, optionally interspersed with transitions (but
-transitions cannot occur at the beginning or end, nor may there be two
-transitions in a row), followed by zero or more sections (whose
-contents are recursively the same as this model) optionally
-interspersed with transitions.
+topics, and/or sidebars, optionally interspersed with single
+transitions, followed by zero or more sections (whose contents are
+recursively the same as this model) optionally interspersed with
+transitions.
+
+The following restrictions are imposed by this model:
+
+* Transitions must be separated by other elements (body elements,
+  sections, etc.).  In other words, a transition may not be
+  immediately adjacent to another transition.
+
+* A transition may not occur at the beginning of a document or
+  section.
+
+An additional restriction, which cannot be expressed in the language
+of DTDs, is imposed by software:
+
+* A transition may not occur at the end of a document or section.
 
 The `%structure.model;`_ parameter entity is directly employed in the
 content models of the document_ and section_ elements.
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 3d3ae4956..a18eae36b 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -140,11 +140,10 @@ resolve to either an internal or external reference.
 <!-- Element Content Models
 ================================================================== -->
 
+<!-- The structure model may not end with a transition. -->
 <!ENTITY % structure.model
-   " ( ( (%body.elements; | topic | sidebar)+,
-         (transition, (%body.elements; | topic | sidebar)+ )*,
-         ( (%section.elements;), (transition?, (%section.elements;) )* )? )
-     | ( (%section.elements;), (transition?, (%section.elements;) )* ) )? ">
+   " ( ( (%body.elements; | topic | sidebar)+, transition? )*,
+       ( (%section.elements;), (transition?, (%section.elements;) )* )? )">
 
 <!ENTITY % text.model
   " (#PCDATA | %inline.elements;)* ">
-- 
cgit v1.2.1


From 661282ce7201379c56ead73b874cf5213ca8d16f Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 23 Dec 2004 17:42:28 +0000
Subject: updated text about "Address" field, because the line block directive
 will be gone soon

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2892 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index a5cd99745..a7841ac63 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -896,9 +896,8 @@ single name is interpreted as an "Author".  If a single name contains
 a comma, end it with a semicolon to disambiguate: ":Authors: Doe,
 Jane;".
 
-The "Address" field is for a multi-line surface mailing address.  A
-specialized form of line block`_ (see `reStructuredText Directives`_),
-newlines and whitespace will be preserved.
+The "Address" field is for a multi-line surface mailing address.
+Newlines and whitespace will be preserved.
 
 The "Dedication" and "Abstract" fields may contain arbitrary body
 elements.  Only one of each is allowed.  They become topic elements
-- 
cgit v1.2.1


From 7b2e20cb23718a2193843c8969a6591c3f1d0d65 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 23 Dec 2004 21:02:15 +0000
Subject: added target for information about file release system

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2893 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 39ab2f471..7187a873a 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -83,8 +83,8 @@
 
 11. Log in to the SourceForge web interface.
 
-12. Access the file release system on SourceForge (Admin interface).
-    Fill in the fields:
+12. 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>
-- 
cgit v1.2.1


From 80af2e1d0332485531d35a433d680279ff82b047 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 24 Dec 2004 00:19:35 +0000
Subject: changed release day; added history entries for David's patch

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2899 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 7187a873a..24c1fb6f6 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -120,9 +120,9 @@
           find -name test -type d -prune -o -name \*.css -print0 \
               -o -name \*.html -print0 -o -name \*.txt -print0 \
               | tar -cjvf docutils-docs.tar.bz2 -T - --null
-          scp docutils-docs.tar.bz2 <username>@docutils.sourceforge.net:
+          scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
 
-      Now log in to docutils.sourceforge.net and::
+      Now log in to shell.sourceforge.net and::
 
           cd /home/groups/d/do/docutils/htdocs/
           mkdir -m g+rwxs X.Y.Z
-- 
cgit v1.2.1


From 3aadcdf74d7120c67fbc88d37a60a8e7d269fe43 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 24 Dec 2004 15:57:25 +0000
Subject: added links for registering at FreshMeat

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2906 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 24c1fb6f6..26f152d5f 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -146,7 +146,11 @@
 19. Register
 
     * with PyPI (``python setup.py register``)
-    * with FreshMeat
+    * with FreshMeat (add a `new release`__ for the `Docutils
+      project`__)
+
+    __ http://freshmeat.net/add-release/48702/
+    __ http://freshmeat.net/projects/docutils/
 
 
 ..
-- 
cgit v1.2.1


From cdf16c8aa7e33fc078bb388ae6304221e6cf7222 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 24 Dec 2004 17:31:08 +0000
Subject: updated release procedure to match what is currently being done; made
 entries not covered by release.sh boldface

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2908 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt | 204 +++++++++++++++++++++++++--------------------------
 1 file changed, 102 insertions(+), 102 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 26f152d5f..3082f775b 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -1,7 +1,7 @@
 =============================
  Docutils_ Release Procedure
 =============================
-:Author: David Goodger; open to all Docutils developers
+:Author: David Goodger; Felix Wiemann; open to all Docutils developers
 :Contact: goodger@python.org
 :Date: $Date$
 :Revision: $Revision$
@@ -10,148 +10,148 @@
 .. _Docutils: http://docutils.sourceforge.net/
 
 
-1. Announce a checkin freeze on Docutils-develop.
+(Steps in boldface text are *not* covered by the release script at
+sandbox/felixwiemann/release.sh.  "Not covered" means that you aren't
+even reminded of them.)
 
-2. Bump the version number in the following files:
+* **Announce a checkin freeze on Docutils-develop.  Post a list of
+  major changes since the last release and ask for additions.**
 
-   * docutils/setup.py
-   * docutils/HISTORY.txt
-   * docutils/docutils/__init__.py
+  .. _CHANGES.txt:
 
-3. Run ``test/test_functional.py``.  If it fails (due to the bumped
-   version number), update the files in ``test/functional/expected/``.
+  **You may want to save this list of changes in a file
+  (e.g. CHANGES.txt) to have it at hand when you need it for posting
+  announcements or pasting it into forms.**
 
-4. Run the test suite: ``cd test ; python alltests.py``.  Do this for
-   all supported Python versions.
+* Bump the _`version number` in the following files:
 
-5. Isolate from outside influence:
+  + docutils/setup.py
+  + docutils/docutils/__init__.py
+  + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z")
 
-   (a) Remove the old installation from site-packages (including
-       roman.py, and optparse.py, textwrap.py for pre-2.3
-       installations).
+* Close the "Changes Since ..." section in docutils/HISTORY.txt.
 
-   (b) Clear/unset the PYTHONPATH environment variable.
+* Clear/unset the PYTHONPATH environment variable.
    
-6. Create the release tarball:
+* Create the release tarball:
 
-   (a) Create a new empty directory and ``cd`` into it.
+  (a) Create a new empty directory and ``cd`` into it.
 
-   (b) Get a clean snapshot of the CVS files::
+  (b) Get a clean snapshot of the CVS files::
 
-           cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \
-               export -rHEAD docutils
+          cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \
+              export -rHEAD docutils
 
-   (c) Use Distutils to create the release tarball::
+  (c) Use Distutils to create the release tarball::
 
-           cd docutils
-           python setup.py sdist
+          cd docutils
+          python setup.py sdist
 
-7. Expand and install the release tarball **in isolation** (as per
-   step 5 above):
+* Expand and _`install` the release tarball in isolation:
 
-   (a) Expand the tarball in a new location, not over any existing
-       files.
+  (a) Expand the tarball in a new location, not over any existing
+      files.
 
-   (b) Install from expanded directory::
+  (b) Remove the old installation from site-packages (including
+      roman.py, and optparse.py, textwrap.py).
 
-           cd docutils-X.Y.Z
-           python setup.py install
+      Install from expanded directory::
 
-       The "install" command may require root permissions.
+          cd docutils-X.Y.Z
+          python setup.py install
 
-8. Run the test suite from the expanded archive directory with all
-   supported Python versions: ``cd test ; python alltests.py``.
+      The "install" command may require root permissions.
 
-9. Run ``cd tools ; buildhtml.py ..`` to confirm that there are no
-   unexpected issues with the docs.
+  (c) Repeat step b) for all supported Python versions.
 
-10. Upload the release tarball::
+* Run the _`test suite` from the expanded archive directory with all
+  supported Python versions: ``cd test ; python -u alltests.py``.
 
-        $ 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
+* Add a directory X.Y.Z (where X.Y.Z is the current version number
+  of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
+  Put all documentation files into it::
 
-11. Log in to the SourceForge web interface.
+      cd docutils-X.Y.Z
+      rm -rf build
+      cd tools/
+      ./buildhtml.py ..
+      cd ..
+      find -name test -type d -prune -o -name \*.css -print0 \
+          -o -name \*.html -print0 -o -name \*.txt -print0 \
+          | tar -cjvf docutils-docs.tar.bz2 -T - --null
+      scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
 
-12. Access the _`file release system` on SourceForge (Admin
-    interface).  Fill in the fields:
+  Now log in to shell.sourceforge.net and::
 
-        :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>
+      cd /home/groups/d/do/docutils/htdocs/
+      mkdir -m g+rwxs X.Y.Z
+      cd X.Y.Z
+      tar -xjvf ~/docutils-docs.tar.bz2
+      rm ~/docutils-docs.tar.bz2
 
-        Also check the "Preserve my pre-formatted text" box.
+* Upload the release tarball::
 
-13. Wait up to 30 minutes for the file to become available on
-    SourceForge.
+      $ 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 docutils-X.Y.Z.tar.gz
 
-14. Download the release tarball and verify its integrity by walking
-    through an installation, as outlined above (steps 7, 8, & 9).
+* Access the _`file release system` on SourceForge (Admin
+  interface).  Fill in the fields:
 
-15. Update the web page:
+      :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 CHANGES.txt_>
 
-    * web/index.txt; afterwards run docutils-update on the server.
-    
-    * Add a directory X.Y.Z (where X.Y.Z is the current version number
-      of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
-      Put all documentation files into it::
+      Also check the "Preserve my pre-formatted text" box.
 
-          cd docutils-X.Y.Z
-          rm -rf build
-          cd tools/
-          ./buildhtml.py ..
-          cd ..
-          find -name test -type d -prune -o -name \*.css -print0 \
-              -o -name \*.html -print0 -o -name \*.txt -print0 \
-              | tar -cjvf docutils-docs.tar.bz2 -T - --null
-          scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
+* For verifying the integrity of the release, download the release
+  tarball (you may need to wait up to 30 minutes), install_ it, and
+  re-run the `test suite`_.
 
-      Now log in to shell.sourceforge.net and::
+* Register with PyPI (``python setup.py register``).
 
-          cd /home/groups/d/do/docutils/htdocs/
-          mkdir -m g+rwxs X.Y.Z
-          cd X.Y.Z
-          tar -xjvf ~/docutils-docs.tar.bz2
+* Bump the `version number`_ again.
 
-16. Bump the version number again (as per step 2) and update the files
-    in ``test/functional/expected/``.
+* Add a new empty section "Changes Since ..." in HISTORY.txt.
 
-17. Send announcement email to:
+* Update the web page (web/index.txt).
 
-    * docutils-develop@lists.sourceforge.net (also announcing the end
-      of the checkin freeze)
-    * docutils-users@lists.sourceforge.net
-    * doc-sig@python.org
-    * python-announce@python.org
+* Run docutils-update on the server.
+    
+* **Send announcement email to:**
 
-18. Add a SourceForge News item, with title "Docutils X.Y.Z released"
-    and containing the release tarball's download URL.
+  * docutils-develop@lists.sourceforge.net (also announcing the end
+    of the checkin freeze)
+  * docutils-users@lists.sourceforge.net
+  * doc-sig@python.org
+  * python-announce@python.org
 
-19. Register
+* **Add a SourceForge News item, with title "Docutils X.Y.Z released"
+  and containing the release tarball's download URL.**
 
-    * with PyPI (``python setup.py register``)
-    * with FreshMeat (add a `new release`__ for the `Docutils
-      project`__)
+* **Register with FreshMeat.** (Add a `new release`__ for the
+  `Docutils project`__).
 
-    __ http://freshmeat.net/add-release/48702/
-    __ http://freshmeat.net/projects/docutils/
+  __ http://freshmeat.net/add-release/48702/
+  __ http://freshmeat.net/projects/docutils/
 
+    
 
 ..
    Local Variables:
-- 
cgit v1.2.1


From 1ad0b81c3591c9d3c085dc5ae873a08f26e70297 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 1 Jan 2005 15:54:45 +0000
Subject: added link to examples.py

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2920 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 95bf4d62e..b018bbe90 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -37,7 +37,7 @@ handles everything else.  There are five convenience functions in the
   Useful when only portions of the processed document are desired.
   Currently only implemented for the HTML Writer.
 
-  There are examples in the ``docutils/examples.py`` module.
+  There are examples in the `docutils/examples.py`_ module.
 
 * ``publish_programmatically``: for custom programmatic use.  This
   function implements common code and is used by ``publish_file``,
@@ -45,6 +45,7 @@ handles everything else.  There are five convenience functions in the
   the encoded string output and the Publisher object.
 
 .. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
+.. _docutils/examples.py: ../../docutils/examples.py
 
 
 Configuration
-- 
cgit v1.2.1


From 92a15c9177df09569b1e0cfa266754134746d4f5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 2 Jan 2005 19:24:01 +0000
Subject: removed entry about testing of ``raw`` role, leaving note about
 testing of other roles; added entry about inclusion by URL, as suggested by
 Alan G Isaac

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2921 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 51c7e5405..175cfd652 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -626,8 +626,12 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
-* Add (functional) tests for the "raw" role, its class attribute, and
-  the other roles as well.
+* Add support for inclusion by URL::
+
+      .. include:: 
+         :url: http://etc/inclusion.txt
+
+* Add (functional) tests for untested roles.
 
 * Allow the _`:trim:` option for all directives when they occur in a
   substitution definition, not only the unicode_ directive.
-- 
cgit v1.2.1


From 56bfd2739cf86cc5e374dbd6fca935be8c2787cf Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 2 Jan 2005 19:48:29 +0000
Subject: improved URL; moved directive option items to "Directives" section

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2922 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 175cfd652..f21181c31 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -626,19 +626,8 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
-* Add support for inclusion by URL::
-
-      .. include:: 
-         :url: http://etc/inclusion.txt
-
 * Add (functional) tests for untested roles.
 
-* Allow the _`:trim:` option for all directives when they occur in a
-  substitution definition, not only the unicode_ directive.
-
-  .. _unicode:
-     http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
-  
 * 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
@@ -1175,6 +1164,17 @@ when used in a document.
   - _`misc.class`: @@@ Allow multiple classes (whitespace-separated)
     to be declared.
 
+  - _`misc.include`: Add support for inclusion by URL::
+
+        .. include:: 
+           :url: http://www.example.org/inclusion.txt
+
+  - Allow the _`:trim:` option for all directives when they occur in a
+    substitution definition, not only the unicode_ directive.
+
+    .. _unicode:
+       http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
+  
 * 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
-- 
cgit v1.2.1


From b7982eea2882cc24e8db71cddbc536bf2097b0e3 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 5 Jan 2005 18:40:25 +0000
Subject: added to-do list entry for removal of name attributes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2926 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f21181c31..f4079b8cb 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1662,6 +1662,13 @@ Unimplemented Transforms
 HTML Writer
 ===========
 
+* Test with modern browsers if it's possible to remove the "name"
+  attributes, which currently serve only for backwards-compatibility
+  to browsers which aren't XHTML compliant.
+
+  If all browsers support the "id" attribute, remove the "name"
+  attributes.
+
 * Add more support for <link> elements, especially for navigation
   bars.
 
-- 
cgit v1.2.1


From 3ea4d60d6bc3d3f35d92c37077fc8507cb85ae43 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 10 Jan 2005 14:58:54 +0000
Subject: added inline target to "whitespace in include file path" item; moved
 entry "support for inclusion by URL" to the existing misc.include section;
 added link to Python's ID-test

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2927 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f4079b8cb..76c16c621 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1119,7 +1119,7 @@ when used in a document.
 
   - _`misc.include`:
 
-    - @@@ Allow whitespace in paths (just not at line boundaries).
+    - @@@ Allow _`whitespace in paths` (just not at line boundaries).
 
     - "encoding" option?  Take default from runtime settings.  Use
       Input component to read it in?
@@ -1159,16 +1159,16 @@ when used in a document.
       Instead of C-include "<syntax>", perhaps a new "include-sys"
       directive?
 
+    - Add support for inclusion by URL::
+
+          .. include:: 
+             :url: http://www.example.org/inclusion.txt
+
   - _`misc.raw`: "encoding" option?
 
   - _`misc.class`: @@@ Allow multiple classes (whitespace-separated)
     to be declared.
 
-  - _`misc.include`: Add support for inclusion by URL::
-
-        .. include:: 
-           :url: http://www.example.org/inclusion.txt
-
   - Allow the _`:trim:` option for all directives when they occur in a
     substitution definition, not only the unicode_ directive.
 
@@ -1664,9 +1664,10 @@ HTML Writer
 
 * Test with modern browsers if it's possible to remove the "name"
   attributes, which currently serve only for backwards-compatibility
-  to browsers which aren't XHTML compliant.
+  to browsers which aren't XHTML compliant.  For a starting point, see
+  http://www.python.org/dev/doc/idtest.html.
 
-  If all browsers support the "id" attribute, remove the "name"
+  If enough browsers support the "id" attribute, remove the "name"
   attributes.
 
 * Add more support for <link> elements, especially for navigation
-- 
cgit v1.2.1


From 5f08c0c369fc0d6b818b02f9a8fa085dcdc0b457 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 10 Jan 2005 15:26:38 +0000
Subject: removed encoding-option entry for raw directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2928 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 --
 1 file changed, 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 76c16c621..3f26368d0 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1164,8 +1164,6 @@ when used in a document.
           .. include:: 
              :url: http://www.example.org/inclusion.txt
 
-  - _`misc.raw`: "encoding" option?
-
   - _`misc.class`: @@@ Allow multiple classes (whitespace-separated)
     to be declared.
 
-- 
cgit v1.2.1


From f2a65fc9c2429b381aa5326e04aa4e87cd89e791 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 17 Jan 2005 15:26:35 +0000
Subject: changed website documentation: docutils-update isn't run by a cron
 job

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2941 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/website.txt | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/website.txt b/docs/dev/website.txt
index 73ef8b10f..0fe2aaf58 100644
--- a/docs/dev/website.txt
+++ b/docs/dev/website.txt
@@ -1,6 +1,7 @@
 ===================
  Docutils Web Site
 ===================
+
 :Author: David Goodger; open to all Docutils developers
 :Contact: goodger@python.org
 :Date: $Date$
@@ -8,20 +9,24 @@
 :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 ::
+maintained by the ``docutils-update`` script.  The script used to run
+as a cron job, but since mid-2004, cron isn't working on
+SourceForge.net, so you will have to run it manually.  It 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 ``<username>@shell.sourceforge.net`` and ::
 
     touch filename.html
     chmod g+w filename.html
     sleep 1
     touch filename.txt
+    /home/groups/d/do/docutils/snapshots/sandbox/davidg/infrastructure/docutils-update -p
 
-The script will take care of the rest within an hour.  Thereafter
+The ``docutils-update`` script will retrieve the most current version
+of the .txt file from CVS and generate the .html file.  Thereafter
 whenever the .txt file is modified (checked in to CVS), the .html will
-be regenerated automatically.
+be regenerated when ``docutils-update`` is run.
 
 After adding directories to CVS, allow the script to run once to
 create the directories in the filesystem before preparing for HTML
-- 
cgit v1.2.1


From 7d277961d1463b6d29a878e34c8c0e7ffc6a672d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 11 Feb 2005 10:10:07 +0000
Subject: added to-do list entry for access control

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2956 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 3f26368d0..6794ad2c3 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -49,6 +49,9 @@ Priorities
 General
 =======
 
+* Add option for file (and URL) access restriction to make Docutils
+  usable in Wikis and similar applications.
+
 * Refactor
 
   - Rename methods & variables according to the `Python coding
-- 
cgit v1.2.1


From d8d6d6c30cfcfc02de5a3b05844b5ea1f319d635 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 11 Feb 2005 15:39:59 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2962 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 6794ad2c3..0cec3d715 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -440,6 +440,8 @@ General
   other one to ``None`` as a side effect.  See discussion on
   docutils-develop from 2004-07-03.
 
+* Add support for _`plugins`.
+
 
 Documentation
 =============
-- 
cgit v1.2.1


From dd317b4e446e8c3666bf6e30e13ebf3a39e168f3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 11 Feb 2005 15:49:20 +0000
Subject: Added "list-table" directive.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt |  4 ++-
 docs/ref/rst/directives.txt   | 59 +++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 60 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 1c33c8522..08ef5297b 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -2165,7 +2165,9 @@ orientation (by column or by row), the presence of row headers, etc.
 
 Alternatives:
 
-1. Bullet-list-tables might look like this::
+1. (Implemented in Docutils 0.3.8).
+
+   Bullet-list-tables might look like this::
 
        .. list-table::
 
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 0684f0d73..bd7c921e1 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -722,8 +722,8 @@ The following options are recognized:
     class_ directive below.
 
 ``widths`` : integer [, integer...]
-    A comma-separated list of relative column widths.  The default is
-    equal-width columns (100%/#columns).
+    A comma- or space-separated list of relative column widths.  The
+    default is equal-width columns (100%/#columns).
 
 ``header-rows`` : integer
     The number of rows of CSV data to use in the table header.
@@ -768,6 +768,61 @@ The following options are recognized:
        the default case?
 
 
+.. _list-table:
+
+List Table
+==========
+
+:Directive Type: "list-table"
+:Doctree Element: table
+:Directive Arguments: 1, optional (table title).
+:Directive Options: Possible.
+:Directive Content: A uniform two-level bullet list.
+
+(New in Docutils 0.3.8.  This is an initial implementation; `further
+ideas`__ may be implemented in the future.)
+
+__ http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables
+
+The "list-table" directive is used to create a table from data in a
+uniform two-level bullet list.  "Uniform" means that each sublist
+(second-level list) must contain the same number of list items.
+
+Example::
+
+    .. list-table:: Frozen Delights!
+       :widths: 15 10 30
+       :header-rows: 1
+
+       * - Treat
+         - Quantity
+         - Description
+       * - Albatross
+         - 2.99
+         - On a stick!
+       * - Crunchy Frog
+         - 1.49
+         - If we took the bones out, it wouldn\'t be
+           crunchy, now would it?
+       * - Gannet Ripple
+         - 1.99
+         - On a stick!
+
+The following options are recognized:
+
+``class`` : text
+    Set a "class" attribute value on the table element.  See the
+    class_ directive below.
+
+``widths`` : integer [integer...]
+    A comma- or space-separated list of relative column widths.  The
+    default is equal-width columns (100%/#columns).
+
+``header-rows`` : integer
+    The number of rows of list data to use in the table header.
+    Defaults to 0.
+
+
 ----------------
  Document Parts
 ----------------
-- 
cgit v1.2.1


From 971b36c33e884ab47a2069ba556a87bf9a9093c6 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 11 Feb 2005 15:51:06 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2964 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/cheatsheet.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 6a0172a59..469480999 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -86,8 +86,8 @@ highlights        Block quote with class="highlights"
 pull-quote        Block quote with class="pull-quote"
 compound          Compound paragraphs [0.3.6]
 table             Create a titled table [0.3.1]
-csv-table         Create a titled table from CSV data (requires Python 2.3+)
-                  [0.3.4]
+list-table        Create a table from a uniform two-level bullet list [0.3.8] 
+csv-table         Create a table from CSV data (requires Python 2.3+) [0.3.4]
 contents          Generate a table of contents
 sectnum           Automatically number sections, subsections, etc.
 target-notes      Create an explicit footnote for each external target
-- 
cgit v1.2.1


From f68980b0781f68739a35aa0fd58d5c9dc6961875 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Feb 2005 02:36:17 +0000
Subject: clarified & extended

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2982 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/runtime-settings.txt | 47 +++++++++++++++++++++++++------------------
 1 file changed, 27 insertions(+), 20 deletions(-)

(limited to 'docs')

diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt
index 4f87c48de..d6b8997cd 100644
--- a/docs/api/runtime-settings.txt
+++ b/docs/api/runtime-settings.txt
@@ -37,16 +37,22 @@ Next, several _`convenience function parameters` are also significant
 (described in the ``docutils.core.publish_programmatically`` function
 docstring):
 
-* ``settings``, if present, is assumed to be complete and no further
-  runtime settings processing is done.
-
-* ``settings_spec`` is treated as a fourth component (after the
-  Parser, Reader, and Writer).
+* The ``settings`` parameter is a runtime settings
+  (``docutils.frontend.Values``) object which, if present, is assumed
+  to be complete (it must include all runtime settings).  Also, if the
+  ``settings`` parameter is present, no further runtime settings
+  processing is done.  In other words, the other parameters, described
+  below, will have no effect.
+
+* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
+  treated like a fourth component (after the Parser, Reader, and
+  Writer).  In other words, it's the settings specification for the
+  "Application" itself.
 
 * ``settings_overrides`` is a dictionary which will override the
-  defaults of the components.
+  defaults of the components (from their settings specs).
 
-* ``config_section`` sets or overrides an application-specific
+* ``config_section`` specifies the name of an application-specific
   configuration file section.
 
 
@@ -57,7 +63,7 @@ Runtime Settings Processing for Command-Line Tools
 
 Following along with the actual code is recommended.  The
 ``docutils/__init__.py``, ``docutils/core.py``, and
-``docutils.frontend`` modules are described.
+``docutils.frontend.py`` modules are described.
 
 1. A command-line front-end tool imports and calls
    ``docutils.core.publish_cmdline``.  The relevant `convenience
@@ -163,21 +169,22 @@ Following along with the actual code is recommended.  The
 Runtime Settings Processing From Applications
 =============================================
 
-Applications process runtime settings in a significantly different way
-than `command-line tools`_ do.  Instead of calling
-``publish_cmdline``, the application calls one of ``publish_file``,
-``publish_string``, or ``publish_parts``.  These in turn call
-``publish_programmatically``, which implements a generic programmatic
-interface.  Although an application may also call
-``publish_programmatically`` directly, it is not recommended (if it
-does seem to be necessary, please write to the `Docutils-Develop
-mailing list`_).
+Applications process runtime settings in a different way than
+`command-line tools`_ do.  Instead of calling ``publish_cmdline``, the
+application calls one of ``publish_file``, ``publish_string``, or
+``publish_parts``.  These in turn call ``publish_programmatically``,
+which implements a generic programmatic interface.  Although an
+application may also call ``publish_programmatically`` directly, it is
+not recommended (if it does seem to be necessary, please write to the
+`Docutils-Develop mailing list`_).
 
 ``publish_programmatically`` accepts the same `convenience function
 parameters`_ as ``publish_cmdline``.  Where things differ is that
-programmatic use does not
-
-TO BE COMPLETED.
+programmatic use does no command-line processing.  Instead of calling
+``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
+does, via ``docutils.Publisher.publish``),
+``docutils.Publisher.process_programmatic_settings`` is called to set
+up the runtime settings.
 
 .. copy & modify the list from command-line tools?
 
-- 
cgit v1.2.1


From 26be35634ec3071982211cfe13e1c0b48d3aeb5f Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 5 Mar 2005 16:52:14 +0000
Subject: relocate internal targets only in front of sections, doctitles and
 subtitles

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3008 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index f5c045bb7..db4d3c426 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -28,6 +28,8 @@ misc.class                      "class" (d/p)                 210
 
 references.Substitutions        standalone (r), pep (r)       220
 
+references.SectionTargets       standalone (r), pep (r)       260
+
 frontmatter.DocTitle            standalone (r)                320
 
 frontmatter.DocInfo             standalone (r)                340
-- 
cgit v1.2.1


From 537dbfeded131e247d07ca40d5f880a694631896 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 5 Mar 2005 18:02:17 +0000
Subject: codify my personal bias against functional constructs & "from
 __future__ import"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3015 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index bd76ea19f..116529994 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -56,8 +56,7 @@ 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):
+Conventions`_ PEPs, with the following clarifications and extensions:
 
 * 4 spaces per indentation level.  No tabs.
 
@@ -81,6 +80,12 @@ least important):
   "note_explicit_target", "explicit_target").  If in doubt, use
   underscores.
 
+* Avoid functional constructs (lambda, filter, map, etc.).  Use list
+  comprehensions instead.
+
+* Avoid ``from __future__ import`` constructs; we don't want them in
+  production code.
+
 * Use 'single quotes' for string literals, and """triple double
   quotes""" for docstrings.
 
-- 
cgit v1.2.1


From b17334d09de7211955e834b0243695d6cb637d84 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 5 Mar 2005 18:32:47 +0000
Subject: Allowed whitespace in paths and URLs (targets; "image", "figure", &
 "include" directive args; ":file:" & ":url:" directive options).

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3018 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/rst-directives.txt | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt
index 9689b6849..a891fe96d 100644
--- a/docs/howto/rst-directives.txt
+++ b/docs/howto/rst-directives.txt
@@ -156,8 +156,7 @@ value ``None``.  Three directive function attributes are recognized:
     empty string ("") if no argument is found.
 
   - ``path``: Returns the path argument unwrapped (with newlines
-    removed).  Raises ``ValueError`` if no argument is found or if the
-    path contains internal whitespace.
+    removed).  Raises ``ValueError`` if no argument is found.
 
   - ``nonnegative_int``: Checks for a nonnegative integer argument,
     and raises ``ValueError`` if not.
@@ -289,12 +288,6 @@ early version of the image directive function::
     def image(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
         reference = ''.join(arguments[0].split('\n'))
-        if reference.find(' ') != -1:
-            error = state_machine.reporter.error(
-                  'Image URI contains whitespace.', '',
-                  nodes.literal_block(block_text, block_text),
-                  line=lineno)
-            return [error]
         options['uri'] = reference
         image_node = nodes.image(block_text, **options)
         return [image_node]
@@ -312,8 +305,7 @@ Several things are noteworthy in the code above:
    to contain whitespace (see the argument spec above,
    ``image.arguments = (1, 0, 1)``).  This is to allow for long URLs
    which may span multiple lines.  The first line of the ``image``
-   function joins the URL, discarding any embedded newlines.  Then the
-   result is checked for embedded spaces, which are *not* allowed.
+   function joins the URL, discarding any embedded newlines.
 
 2. The reference is added to the ``options`` dictionary under the
    "uri" key; this becomes an attribute of the ``nodes.image`` element
-- 
cgit v1.2.1


From 736a7d126b4fd529ff22bea338afc62b95fca3b2 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 5 Mar 2005 23:03:30 +0000
Subject: removed some to-do list entries which are already implemented

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3024 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 -------
 1 file changed, 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 0cec3d715..b55a5152d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -646,8 +646,6 @@ __ rst/alternatives.html#or-not-to-do
 
 * 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
@@ -1124,8 +1122,6 @@ when used in a document.
 
   - _`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?
 
@@ -1169,9 +1165,6 @@ when used in a document.
           .. include:: 
              :url: http://www.example.org/inclusion.txt
 
-  - _`misc.class`: @@@ Allow multiple classes (whitespace-separated)
-    to be declared.
-
   - Allow the _`:trim:` option for all directives when they occur in a
     substitution definition, not only the unicode_ directive.
 
-- 
cgit v1.2.1


From 4c757af54eabf7f37b89dcc53813b2d9da223e15 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 14 Mar 2005 16:45:09 +0000
Subject: re-added --no-random option of PEP writer for testing

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3039 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 07fa26460..458801347 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -590,6 +590,13 @@ The PEP/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
 "[html4css1 writer]" section is processed before "[pep_html writer]".
 
+_`no_random`
+    Do not use a random banner image.  Mainly used to get predictable
+    results when testing.
+
+    Default: random enabled (None).  Options: ``--no-random``
+    (hidden).
+
 _`pep_home`
     Home URL prefix for PEPs.
 
-- 
cgit v1.2.1


From 2913454311795655ccd224ad249d5ff6a30301c6 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 15 Mar 2005 00:33:59 +0000
Subject: Added "uri" directive option conversion function.  Added docstrings &
 documentation.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3045 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/rst-directives.txt | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt
index a891fe96d..6210940c8 100644
--- a/docs/howto/rst-directives.txt
+++ b/docs/howto/rst-directives.txt
@@ -158,6 +158,9 @@ value ``None``.  Three directive function attributes are recognized:
   - ``path``: Returns the path argument unwrapped (with newlines
     removed).  Raises ``ValueError`` if no argument is found.
 
+  - ``uri``: Returns the URI argument with whitespace removed.  Raises
+    ``ValueError`` if no argument is found.
+
   - ``nonnegative_int``: Checks for a nonnegative integer argument,
     and raises ``ValueError`` if not.
 
@@ -165,6 +168,26 @@ value ``None``.  Three directive function attributes are recognized:
     string and returns it.  Raises ``ValueError`` if no argument is
     found.
 
+  - ``unicode_code``: Convert a Unicode character code to a Unicode
+    character.
+
+  - ``single_char_or_unicode``: A single character is returned as-is.
+    Unicode characters codes are converted as in ``unicode_code``.
+
+  - ``single_char_or_whitespace_or_unicode``: As with
+    ``single_char_or_unicode``, but "tab" and "space" are also
+    supported.
+
+  - ``positive_int``: Converts the argument into an integer.  Raises
+    ValueError for negative, zero, or non-integer values.
+
+  - ``positive_int_list``: Converts a space- or comma-separated list
+    of integers into a Python list of integers.  Raises ValueError for
+    non-positive-integer values.
+
+  - ``encoding``: Verfies the encoding argument by lookup.  Raises
+    ValueError for unknown encodings.
+
   A further utility function, ``choice``, is supplied to enable
   options whose argument must be a member of a finite set of possible
   values.  A custom conversion function must be written to use it.
@@ -287,7 +310,7 @@ early version of the image directive function::
 
     def image(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
-        reference = ''.join(arguments[0].split('\n'))
+        reference = directives.uri(arguments[0])
         options['uri'] = reference
         image_node = nodes.image(block_text, **options)
         return [image_node]
@@ -305,7 +328,7 @@ Several things are noteworthy in the code above:
    to contain whitespace (see the argument spec above,
    ``image.arguments = (1, 0, 1)``).  This is to allow for long URLs
    which may span multiple lines.  The first line of the ``image``
-   function joins the URL, discarding any embedded newlines.
+   function joins the URL, discarding any embedded whitespace.
 
 2. The reference is added to the ``options`` dictionary under the
    "uri" key; this becomes an attribute of the ``nodes.image`` element
-- 
cgit v1.2.1


From 0a938a279683da492acd6512d0af6fa636c5a51c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 15 Mar 2005 00:37:51 +0000
Subject: differentiate between paths and URIs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3046 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index a7841ac63..e8109bc28 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1782,8 +1782,9 @@ indirect.
    explicit markup start and target name, or it may begin in an
    indented text block immediately following, with no intervening
    blank lines.  If there are multiple lines in the link block, they
-   are stripped of leading and trailing whitespace and concatenated.
-   The following external hyperlink targets are equivalent::
+   are concatenated.  Any whitespace is removed (whitespace is
+   permitted to allow for line wrapping).  The following external
+   hyperlink targets are equivalent::
 
        .. _one-liner: http://docutils.sourceforge.net/rst.html
 
-- 
cgit v1.2.1


From 415c3114d709d4631dc8f30314b7e5069caaadf5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 18 Mar 2005 14:44:01 +0000
Subject: added preliminary document about Subversion repository

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3057 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 135 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 docs/dev/repository.txt

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
new file mode 100644
index 000000000..208c1a45d
--- /dev/null
+++ b/docs/dev/repository.txt
@@ -0,0 +1,135 @@
+==========================
+ The Docutils_ Repository
+==========================
+
+:Author: Felix Wiemann
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+
+Docutils uses a Subversion_ repository located at ``svn.berlios.de``.
+Subversion is exhaustively documented in the `Subversion Book`_
+(svnbook).
+
+.. _Subversion: http://subversion.tigris.org/
+.. _Subversion Book: http://svnbook.red-bean.com/
+
+
+Accessing the Repository
+========================
+
+Anonymous Access
+----------------
+
+Anonymous (read-only) access is available at ``svn://svn.berlios.de/docutils/``.
+
+To check out the current main source tree of Docutils, type ::
+
+    svn checkout svn://svn.berlios.de/docutils/trunk/docutils
+
+To check out everything (main tree, sandboxes, and web site), type ::
+
+    svn checkout svn://svn.berlios.de/docutils/trunk docutils
+
+This will create a working copy of the whole trunk in a new directory
+called ``docutils``.
+
+Note that you should *never* check out
+``svn://svn.berlios.de/docutils`` (without "trunk"), because then
+you'd end up fetching the whole Docutils tree for every branch and tag
+over and over again, wasting your and BerliOS's bandwidth.
+
+To update your working copy later on, cd into the working copy and
+type ::
+
+    svn update
+
+
+Developer Access
+----------------
+
+If you are a developer, you get read-write access via
+``svn+ssh://username@svn.berlios.de/svnroot/repos/docutils/``, where
+``username`` is your BerliOS user name.  So to retrieve a working
+copy, type ::
+
+    svn checkout svn+ssh://username@svn.berlios.de/svnroot/repos/docutils/trunk docutils
+
+If you previously had an anonymous working copy and gained developer
+access, you can switch the URL associated with your working copy by
+typing ::
+
+    svn switch --relocate svn://svn.berlios.de/docutils/trunk/docutils \
+        svn+ssh://username@svn.berlios.de/svnroot/repos/docutils
+
+(``username`` is again your BerliOS user name.)
+
+
+Setting Up Your Subversion Client For Development
+`````````````````````````````````````````````````
+
+Before commiting changes to the repository, please ensure that the
+following lines are contained (and uncommented) in your
+~/.subversion/config file, so that new files are added with the
+correct properties set::
+
+    [miscellany]
+    # For your convenience:
+    global-ignores = ... *.pyc ...
+    # For correct properties:
+    enable-auto-props = yes
+
+    [auto-props]
+    *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
+    *.png = svn:mime-type=image/png
+
+
+Web Access
+----------
+
+The repository can be browsed and examined via the web at
+http://svn.berlios.de/viewcvs/docutils/.
+
+
+Repository Layout
+=================
+
+The following tree shows the repository layout::
+
+    docutils/
+    |-- branches/
+    |   |-- branch1/
+    |   |   |-- docutils/
+    |   |   |-- sandbox/
+    |   |   `-- web/
+    |   `-- branch2/
+    |       |-- docutils/
+    |       |-- sandbox/
+    |       `-- web/
+    |-- tags/
+    |   |-- tag1/
+    |   |   |-- docutils/
+    |   |   |-- sandbox/
+    |   |   `-- web/
+    |   `-- tag2/
+    |       |-- docutils/
+    |       |-- sandbox/
+    |       `-- web/
+    `-- trunk/
+        |-- docutils/
+        |-- sandbox/
+        `-- web/
+
+``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies
+of the whole trunk.
+
+The main source tree lives at ``docutils/trunk/docutils/``, next to
+the sandboxes (``docutils/trunk/sandbox/``) and the web site files
+(``docutils/trunk/web/``).
-- 
cgit v1.2.1


From d06b559d1082b9881e16d0278a65aca3b42ec5e2 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 21 Mar 2005 21:26:21 +0000
Subject: Added settings: ``file_insertion_enabled`` & ``raw_enabled``.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3071 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 458801347..0e74cc0b3 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -228,6 +228,17 @@ _`expose_internals`
     Default: don't (None).  Options: ``--expose-internal-attribute``
     (hidden, for development use only).
 
+_`file_insertion_enabled`
+    Enable or disable directives that insert the contents of external
+    files, such as the "include__" & "raw__".  A "warning" system
+    message (including the directive text) is inserted instead.
+
+    Default: enabled (1).  Options: ``--file-insertion-enabled,
+    --no-file-insertion``.
+
+    .. _include: ../ref/rst/directives.html#include
+    .. _raw: ../ref/rst/directives.html#raw
+
 _`footnote_backlinks`
     Enable or disable backlinks from footnotes and citations to their
     references.
@@ -309,6 +320,12 @@ _`output_encoding_error_handler`
     Default: "strict".  Options: ``--output-encoding-error-handler,
     --output-encoding, -o``.
 
+_`raw_enabled`
+    Enable or disable the "raw_" directive.  A "warning" system
+    message (including the directive text) is inserted instead.
+
+    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
+
 _`report_level`
     Verbosity threshold at or above which system messages are
     reported.
-- 
cgit v1.2.1


From 9d14cec8705e43ee8aeabb480ac47c18d7214a0d Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 21 Mar 2005 21:57:21 +0000
Subject: fix

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3072 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 0e74cc0b3..0fba204c1 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -230,7 +230,7 @@ _`expose_internals`
 
 _`file_insertion_enabled`
     Enable or disable directives that insert the contents of external
-    files, such as the "include__" & "raw__".  A "warning" system
+    files, such as the "include_" & "raw_".  A "warning" system
     message (including the directive text) is inserted instead.
 
     Default: enabled (1).  Options: ``--file-insertion-enabled,
-- 
cgit v1.2.1


From c10949efdbd30c1b4a54dc086a0b58aa3086a07c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 21 Mar 2005 22:03:40 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3073 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b55a5152d..a3934b34f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1130,7 +1130,7 @@ when used in a document.
     - Option to label lines?
 
     - Default directory for "built-in includes", using the C syntax
-      ``#include <name>``?
+      ``<name>`` (as in ``#include <name>``)?
 
           Use C-preprocessor semantics for locating include files?
           E.g., ``.. include:: file.txt`` will read another file into
-- 
cgit v1.2.1


From 7443f869361b418b846f773b53d47543ca1c980b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 21 Mar 2005 22:05:23 +0000
Subject: added security warnings for "raw" & "include"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3074 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index bd7c921e1..752c82c51 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1074,6 +1074,13 @@ Including an External Document Fragment
 :Directive Options: Possible.
 :Directive Content: None.
 
+.. WARNING::
+
+   The "include" directive represents a potential security hole.  It
+   can be disabled with the "file_insertion_enabled_" runtime setting.
+
+   .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
+
 The "include" directive reads a reStructuredText-formatted text file
 and parses it in the current document's context at the point of the
 directive.  The directive argument is the path to the file to be
@@ -1124,6 +1131,14 @@ Raw Data Pass-Through
 
 .. WARNING::
 
+   The "raw" directive represents a potential security hole.  It can
+   be disabled with the "raw_enabled_" or "file_insertion_enabled_"
+   runtime settings.
+
+   .. _raw_enabled: ../../user/config.html#raw-enabled
+
+.. Caution::
+
    The "raw" directive is a stop-gap measure allowing the author to
    bypass reStructuredText's markup.  It is a "power-user" feature
    that should not be overused or abused.  The use of "raw" ties
-- 
cgit v1.2.1


From 8f7b1981f1d0039afa2353594cc852281166924e Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 22 Mar 2005 19:12:40 +0000
Subject: documented the installation of SSH keys

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3082 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 208c1a45d..5311f9a1b 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -91,6 +91,55 @@ correct properties set::
     *.png = svn:mime-type=image/png
 
 
+Setting Up SSH Access
+`````````````````````
+
+With a public & private key pair, you can access the shell and
+Subversion servers without having to enter your password.  There are
+two places to add your SSH public key on BerliOS: your web account and
+your shell account.
+
+1. Adding your SSH key to your BerliOS web account:
+
+   * Log in on the web at https://developer.berlios.de/.  Create your
+     account first if necessary.  You should be taken to your "My
+     Personal Page" (https://developer.berlios.de/my/).
+
+   * Choose "Account Options" from the menu below the top banner.
+
+   * At the bottom of the "Account Maintenance" page
+     (https://developer.berlios.de/account/) you'll find a "Shell
+     Account Information" section; click on "[Edit Keys]".
+
+   * Copy and paste your SSH public key into the edit box on this page
+     (https://developer.berlios.de/account/editsshkeys.php).  Further
+     instructions are available on this page.
+
+2. Adding your SSH key to your BerliOS shell account:
+
+   * Log in to the BerliOS shell server::
+
+         ssh username@shell.berlios.de
+
+     You'll be asked for your password, which you set when you created
+     your account.
+
+   * Create a .ssh directory in your home directory, and remove
+     permissions for group & other::
+
+         mkdir .ssh
+         chmod og-rwx .ssh
+
+     Exit the SSH session.
+
+   * Copy your public key to the .ssh directory on BerliOS::
+
+         scp .ssh/id_dsa.pub username@shell.berlios.de:.ssh/authorized_keys
+
+   Now you should be able to start an SSH session without needing your
+   password.
+
+
 Web Access
 ----------
 
-- 
cgit v1.2.1


From b559771f98c67ca07b71c41dd947c2be6df75fee Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 22 Mar 2005 19:18:06 +0000
Subject: added csv-table directive support for the file_insertion_enabled
 setting

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3083 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 752c82c51..1b0ff108d 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -668,7 +668,13 @@ CSV Table
 :Directive Options: Possible.
 :Directive Content: A CSV (comma-separated values) table.
 
-.. Warning::
+.. WARNING::
+
+   The "csv-table" directive's ":file:" and ":url:" options represent
+   a potential security holes.  They can be disabled with the
+   "file_insertion_enabled_" runtime setting.
+
+.. Note::
 
    The "csv-table" directive requires the ``csv.py`` module of the
    Python standard library, which was added in Python 2.3.  It will
@@ -734,8 +740,11 @@ The following options are recognized:
     before any ``header-rows`` from the main CSV data.  Must use the
     same CSV format as the main CSV data.
 
-``file`` | ``url`` : path
-    Path or URL to CSV file.
+``file`` : string (newlines removed)
+    The local filesystem path to a CSV data file.
+
+``url`` : string (whitespace removed)
+    An Internet URL reference to a CSV data file.
 
 ``encoding`` : name of text encoding
     The text encoding of the external CSV data (file or URL).
@@ -1179,10 +1188,10 @@ example::
 
 The following options are recognized:
 
-``file`` : string
+``file`` : string (newlines removed)
     The local filesystem path of a raw data file to be included.
 
-``url`` : string
+``url`` : string (whitespace removed)
     An Internet URL reference to a raw data file to be included.
 
 ``encoding`` : name of text encoding
-- 
cgit v1.2.1


From d6bdfad432aefff981011677664713ef83bca27b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 23 Mar 2005 01:01:57 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index f5ce3b03d..230761c10 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -185,6 +185,7 @@ Docutils-general:
 * `Docutils Project Policies <dev/policies.html>`__
 * `Docutils Web Site <dev/website.html>`__
 * `Docutils Release Procedure <dev/release.html>`__
+* `The Docutils Repository <dev/repository.html>`__
 * `Docutils Testing <dev/testing.html>`__
 * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
 * `Python Source Reader <dev/pysource.html>`_ (incomplete)
-- 
cgit v1.2.1


From 99ff881b72893b53d7db2b7a6f3d8495668bb6c0 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 23 Mar 2005 16:47:14 +0000
Subject: updated to Subversion

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3097 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 98 +++++++++++++++++++++------------------------------
 docs/dev/release.txt  |  8 ++---
 2 files changed, 45 insertions(+), 61 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 116529994..5757c8013 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -101,9 +101,9 @@ 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.
+the project for inclusion (via Subversion, 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:
@@ -125,23 +125,25 @@ author(s) of the files should be willing to assign copyright to the
 PSF.
 
 
-CVS Check-ins
-=============
+Subversion Check-ins
+====================
 
-Instructions for CVS access can be found at
-http://sourceforge.net/cvs/?group_id=38414.  Anyone can access the CVS
+Please see the `repository documentation`_ for details on how to
+access Docutils' Subversion repository.  Anyone can access the
 repository anonymously.  Only project developers can make changes.
-See `Setting Up For Docutils Development`_ below for more info.
+Also see `Setting Up For Docutils Development`_ below for more info.
+
+.. _repository documentation: repository.html
 
 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
+Subversion commands to ``svn checkout``, ``svn commit``, and ``svn
+add``.  Do **NOT** use ``svn 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.
+repository tarball`_, set it up on your own machine, and experiment
+*there* first (but remove hooks/post-commit first).
 
-The `main source tree`_ ("docutils" CVS module) should always be kept
-in a stable state (usable and as problem-free as possible).  The
+The `main source tree`_ ("trunk/docutils" directory) 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:
 
@@ -188,7 +190,7 @@ applicable), with particular emphasis as follows:
   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
+* The `sandbox directory`_ is the place to put new, incomplete or
   experimental code.  See `Additions to Docutils`_ and `The Sandbox`_
   below.
 
@@ -203,24 +205,24 @@ 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.
+mistake is easy to fix.  That's what Subversion is for.
 
 .. _main source tree:
-   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/
+   http://svn.berlios.de/viewcvs/docutils/trunk/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
+.. _sandbox directory:
+   http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
+.. _nightly repository tarball:
+   http://svn.berlios.de/svndumps/docutils-repos.gz
 
 
 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
+in the `sandbox 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?
@@ -262,25 +264,6 @@ to completion.
 .. _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
 -----------------------------------
 
@@ -294,7 +277,7 @@ meaning.  There are two ways to keep the Docutils code accessible:
   up your local working copy of the code.  This is the recommended
   method.
 
-  For the bash shell and Docutils checked out from CVS in
+  For the bash shell and Docutils checked out from Subversion in
   ``~/projects/docutils/``, add this to your ``~/.profile``::
 
       PYTHONPATH=$HOME/projects/docutils/docutils
@@ -334,8 +317,8 @@ Developers should subscribe to the mailing lists:
   (email to Doc-SIG@python.org).
 * Docutils-develop__, for implementation discussions
   (email to docutils-develop@lists.sourceforge.net).
-* Docutils-checkins__, to monitor CVS checkin messages (automatically
-  generated; normally read-only).
+* Docutils-checkins__, to monitor Subversion check-in messages
+  (automatically generated; normally read-only).
 * Docutils-users__, to monitor and help out with usage issues and bug
   reports.
 
@@ -348,11 +331,11 @@ __ 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
+The `sandbox directory`_ is a place to play around, to try out and
+share ideas.  It's a part of the Subversion 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
+to the 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
@@ -406,13 +389,14 @@ 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.
+An official parallel project will have its own directory beside (or
+parallel to) the main ``docutils`` directory in the Subversion
+repository.  It can have its own web page in the
+docutils.sourceforge.net domain, its own file releases and
+downloadable 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:
diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 3082f775b..7ae12af88 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -12,7 +12,8 @@
 
 (Steps in boldface text are *not* covered by the release script at
 sandbox/felixwiemann/release.sh.  "Not covered" means that you aren't
-even reminded of them.)
+even reminded of them.  Note: The release.sh script needs to be
+updated to reflect the recent move to Subversion!)
 
 * **Announce a checkin freeze on Docutils-develop.  Post a list of
   major changes since the last release and ask for additions.**
@@ -37,10 +38,9 @@ even reminded of them.)
 
   (a) Create a new empty directory and ``cd`` into it.
 
-  (b) Get a clean snapshot of the CVS files::
+  (b) Get a clean snapshot of the main tree::
 
-          cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \
-              export -rHEAD docutils
+          svn export svn://svn.berlios.de/docutils/trunk/docutils
 
   (c) Use Distutils to create the release tarball::
 
-- 
cgit v1.2.1


From 0a02fc64c6dbe62a13fd6aa0902911c0c3e26cb4 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 24 Mar 2005 02:58:16 +0000
Subject: minor update

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3105 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/peps/pep-0258.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt
index 5ad1c9e26..4aaeecf3a 100644
--- a/docs/peps/pep-0258.txt
+++ b/docs/peps/pep-0258.txt
@@ -533,15 +533,16 @@ system messages:
 
 * Level-2, "WARNING": an issue that should be addressed.  If ignored,
   there may be minor problems with the output.  Typically level-2
-  system messages are reported but do not halt processing
+  system messages are reported but do not halt processing.
 
 * Level-3, "ERROR": a major issue that should be addressed.  If
   ignored, the output will contain unpredictable errors.  Typically
-  level-3 system messages are reported but do not halt processing
+  level-3 system messages are reported but do not halt processing.
 
 * Level-4, "SEVERE": a critical error that must be addressed.
   Typically level-4 system messages are turned into exceptions which
-  halt processing.  If ignored, the output will contain severe errors.
+  do halt processing.  If ignored, the output will contain severe
+  errors.
 
 Although the initial message levels were devised independently, they
 have a strong correspondence to `VMS error condition severity
-- 
cgit v1.2.1


From e31cbf8e64a41aae36cbaeed1d285ad942f703dd Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 24 Mar 2005 16:36:09 +0000
Subject: cover tricky indentation edge cases

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3111 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index e8109bc28..4a98a45f9 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1484,10 +1484,17 @@ An explicit markup block is a text block:
 - which ends before an unindented line.
 
 Explicit markup blocks are analogous to bullet list items, with ".."
-as the bullet.  The text immediately after the explicit markup start
-determines the indentation of the block body.  Blank lines are
-required between explicit markup blocks and other elements, but are
-optional between explicit markup blocks where unambiguous.
+as the bullet.  The text on the lines immediately after the explicit
+markup start determines the indentation of the block body.  The
+maximum common indentation is always removed from the second and
+subsequent lines of the block body.  Therefore if the first construct
+fits in one line, and the indentation of the first and second
+constructs should differ, the first construct should not begin on the
+same line as the explicit markup start.
+
+Blank lines are required between explicit markup blocks and other
+elements, but are optional between explicit markup blocks where
+unambiguous.
 
 The explicit markup syntax is used for footnotes, citations, hyperlink
 targets, directives, substitution definitions, and comments.
@@ -1512,13 +1519,16 @@ be:
 
 - a single "*" (denoting `auto-symbol footnotes`_).
 
-If the first body element within a footnote is a simple paragraph, it
-may begin on the same line as the footnote label.  Other elements must
-begin on a new line, consistently indented (by at least 3 spaces) and
-left-aligned.
+The footnote content (body elements) must be consistently indented (by
+at least 3 spaces) and left-aligned.  The first body element within a
+footnote may often begin on the same line as the footnote label.
+However, if the first element fits on one line and the indentation of
+the remaining elements differ, the first element must begin on the
+line after the footnote label.  Otherwise, the difference in
+indentation will not be detected.
 
 Footnotes may occur anywhere in the document, not only at the end.
-Where or how they appear in the processed output depends on the
+Where and how they appear in the processed output depends on the
 processing system.
 
 Here is a manually numbered footnote::
-- 
cgit v1.2.1


From 4567c6e3ac80ecbf0c32844499694b119b73c8e3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Mar 2005 02:36:17 +0000
Subject: added stdlib inclusion requirements

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3112 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index a3934b34f..2fb1a168b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -46,6 +46,39 @@ Priorities
 * `Nested inline markup`_.
 
 
+Minimum Requirements for Python Standard Library Candidacy
+==========================================================
+
+Below are action items that must be added and issues that must be
+addressed before Docutils can be considered suitable to be proposed
+for inclusion in the Python standard library.
+
+* Support for `document splitting`_.  May require some major code
+  rework.
+
+* Support for subdocuments (see `large documents`_).
+
+* `Object numbering and object references`_.
+
+* `Nested inline markup`_.
+
+* `Python Source Reader`_.
+
+* The HTML writer needs to be rewritten (or a second HTML writer
+  added) to allow for custom classes, and for arbitrary splitting
+  (stack-based?).
+
+* Documentation_ of the architecture.  Other docs too.
+
+* Plugin support.
+
+* A LaTeX writer making use of (La)TeX's power, so that the rendering
+  of the resulting documents is more easily customizable.  (Similar to
+  what you wrote about a new HTML Writer.)
+
+* Suitability for Python module documentation.
+
+
 General
 =======
 
-- 
cgit v1.2.1


From 7d76b140ee974b59e35f1f044949dc032630e15f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Mar 2005 03:02:32 +0000
Subject: added auto-enumerated list items

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3113 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 5 +++++
 docs/user/rst/cheatsheet.txt      | 1 +
 docs/user/rst/demo.txt            | 2 ++
 docs/user/rst/quickref.html       | 2 ++
 4 files changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 4a98a45f9..4ed975144 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -670,6 +670,11 @@ The following enumeration sequences are recognized:
 - uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
 - lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).
 
+In addition, the auto-enumerator, "#", may be used to automatically
+enumerate a list.  Auto-enumerated lists may begin with explicit
+enumeration, which sets the sequence.  Fully auto-enumerated lists use
+arabic numerals and begin with 1.
+
 The following formatting types are recognized:
 
 - suffixed with a period: "1.", "A.", "a.", "I.", "i.".
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 469480999..73f7d27e3 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -36,6 +36,7 @@ List Type         Examples
 ================  ============================================================
 Bullet list       * items begin with "-", "+", or "*"
 Enumerated list   1. items use any variation of "1.", "A)", and "(i)"
+                  #. also auto-enumerated
 Definition list   Term is flush-left : optional classifier
                       Definition is indented, no blank line between
 Field list        :field name: field body
diff --git a/docs/user/rst/demo.txt b/docs/user/rst/demo.txt
index 4a3211c7c..7e57b6bad 100644
--- a/docs/user/rst/demo.txt
+++ b/docs/user/rst/demo.txt
@@ -165,6 +165,8 @@ Enumerated Lists
 
    iv. iv
 
+#. List items may also be auto-enumerated.
+
 Definition Lists
 ----------------
 
diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html
index 64c7b6943..e391763c2 100644
--- a/docs/user/rst/quickref.html
+++ b/docs/user/rst/quickref.html
@@ -395,6 +395,7 @@
 <br><samp>   numbered, but need not start at 1</samp>
 <br><samp>   (although not all formatters will</samp>
 <br><samp>   honour the first index).</samp>
+<br><samp>#. This item is auto-enumerated</samp>
       <td>Enumerated lists:
         <ol type="1">
           <li value="3">This is the first item
@@ -404,6 +405,7 @@
           <li>List items should be sequentially numbered,
         but need not start at 1 (although not all
         formatters will honour the first index).
+          <li>This item is auto-enumerated
         </ol>
     </table>
 
-- 
cgit v1.2.1


From 09093f6b1c39dca2c86172dd146522b08a5a76ef Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Mar 2005 03:12:29 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3114 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 2fb1a168b..450d20a73 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -842,10 +842,6 @@ __ rst/alternatives.html#or-not-to-do
   A section titled "3. Conclusion" could then be referred to by
   "``Conclusion_``" (i.e., without the "3.").
 
-* 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`_.
-- 
cgit v1.2.1


From a18160f34ab7c9f9be7080543ca4ab42ce79d013 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Mar 2005 03:19:03 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3115 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 738 +++++++++++++++++++++---------------------
 1 file changed, 370 insertions(+), 368 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 08ef5297b..25732189f 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -1454,6 +1454,373 @@ updated to use the new internal representation, and its documentation
 will be updated to recommend the new syntax.
 
 
+List-Driven Tables
+==================
+
+The original idea came from Dylan Jay:
+
+    ... to use a two level bulleted list with something to
+    indicate it should be rendered as a table ...
+
+It's an interesting idea.  It could be implemented in as a directive
+which transforms a uniform two-level list into a table.  Using a
+directive would allow the author to explicitly set the table's
+orientation (by column or by row), the presence of row headers, etc.
+
+Alternatives:
+
+1. (Implemented in Docutils 0.3.8).
+
+   Bullet-list-tables might look like this::
+
+       .. list-table::
+
+          * - Treat
+            - Quantity
+            - Description
+          * - Albatross!
+            - 299
+            - On a stick!
+          * - Crunchy Frog!
+            - 1499
+            - If we took the bones out, it wouldn't be crunchy,
+              now would it?
+          * - Gannet Ripple!
+            - 199
+            - On a stick!
+
+   This list must be written in two levels.  This wouldn't work::
+
+       .. list-table::
+
+          * Treat
+          * Albatross!
+          * Gannet!
+          * Crunchy Frog!
+
+          * Quantity
+          * 299
+          * 199
+          * 1499
+
+          * Description
+          * On a stick!
+          * On a stick!
+          * If we took the bones out...
+
+   The above is a single list of 12 items.  The blank lines are not
+   significant to the markup.  We'd have to explicitly specify how
+   many columns or rows to use, which isn't a good idea.
+
+2. Beni Cherniavsky suggested a field list alternative.  It could look
+   like this::
+
+       .. field-list-table::
+          :headrows: 1
+
+          - :treat: Treat
+            :quantity: Quantity
+            :descr: Description
+
+          - :treat: Albatross!
+            :quantity: 299
+            :descr: On a stick!
+
+          - :treat: Crunchy Frog!
+            :quantity: 1499
+            :descr: If we took the bones out, it wouldn't be
+                    crunchy, now would it?
+
+   Column order is determined from the order of fields in the first
+   row.  Field order in all other rows is ignored.  As a side-effect,
+   this allows trivial re-arrangement of columns.  By using named
+   fields, it becomes possible to omit fields in some rows without
+   losing track of things, which is important for spans.
+
+3. An alternative to two-level bullet lists would be to use enumerated
+   lists for the table cells::
+
+       .. list-table::
+
+           * 1. Treat
+             2. Quantity
+             3. Description
+           * 1. Albatross!
+             2. 299
+             3. On a stick!
+           * 1. Crunchy Frog!
+             2. 1499
+             3. If we took the bones out, it wouldn't be crunchy,
+                now would it?
+
+   That provides better correspondence between cells in the same
+   column than does bullet-list syntax, but not as good as field list
+   syntax.  I think that were only field-list-tables available, a lot
+   of users would use the equivalent degenerate case::
+
+       .. field-list-table::
+           - :1: Treat
+             :2: Quantity
+             :3: Description
+           ...
+
+4. Another natural variant is to allow a description list with field
+   lists as descriptions::
+
+       .. list-table::
+           :headrows: 1
+
+           Treat
+               :quantity: Quantity
+               :descr: Description
+           Albatross!
+               :quantity: 299
+               :descr: On a stick!
+           Crunchy Frog!
+               :quantity: 1499
+               :descr: If we took the bones out, it wouldn't be
+                       crunchy, now would it?
+
+   This would make the whole first column a header column ("stub").
+   It's limited to a single column and a single paragraph fitting on
+   one source line.  Also it wouldn't allow for empty cells or row
+   spans in the first column.  But these are limitations that we could
+   live with, like those of simple tables.
+
+The List-driven table feature could be done in many ways.  Each user
+will have their preferred usage.  Perhaps a single "list-table"
+directive could handle them all, depending on which options and
+content are present.
+
+Issues:
+
+* How to indicate that there's 1 header row?  Perhaps two lists?  ::
+
+      .. list-table::
+
+         + - Treat
+           - Quantity
+           - Description
+
+         * - Albatross!
+           - 299
+           - On a stick!
+
+  This is probably too subtle though.  Better would be a directive
+  option, like ``:headrows: 1``.  An early suggestion for the header
+  row(s) was to use a directive option::
+
+      .. field-list-table::
+         :header:
+             - :treat: Treat
+               :quantity: Quantity
+               :descr: Description
+         - :treat: Albatross!
+           :quantity: 299
+           :descr: On a stick!
+
+  But the table data is at two levels and looks inconsistent.
+
+  In general, we cannot extract the header row from field lists' field
+  names because field names cannot contain everything one might put in
+  a table cell.  A separate header row also allows shorter field names
+  and doesn't force one to rewrite the whole table when the header
+  text changes.  But for simpler cases, we can offer a ":header:
+  fields" option, which does extract header cells from field names::
+
+      .. field-list-table::
+          :header: fields
+
+          - :Treat: Albatross!
+            :Quantity: 299
+            :Description: On a stick!
+
+* How to indicate the column widths?  A directive option? ::
+
+      .. list-table::
+         :widths: 15 10 35
+
+  Automatic defaults from the text used?
+
+* How to handle row and/or column spans?
+
+  In a field list, column-spans can be indicated by specifying the
+  first and last fields, separated by space-dash-space or ellipsis::
+
+      - :foo - baz: quuux
+      - :foo ... baz: quuux
+
+  Commas were proposed for column spans::
+
+      - :foo, bar: quux
+
+  But non-adjacent columns become problematic.  Should we report an
+  error, or duplicate the value into each span of adjacent columns (as
+  was suggested)?  The latter suggestion is appealing but may be too
+  clever.  Best perhaps to simply specify the two ends.
+
+  It was suggested that comma syntax should be allowed, too, in order
+  to allow the user to avoid trouble when changing the column order.
+  But changing the column order of a table with spans is not trivial;
+  we shouldn't make it easier to mess up.
+
+  One possible syntax for row-spans is to simply treat any row where a
+  field is missing as a row-span from the last row where it appeared.
+  Leaving a field empty would still be possible by writing a field
+  with empty content.  But this is too implicit.
+
+  Another way would be to require an explicit continuation marker
+  (``...``/``-"-``/``"``?) in all but the first row of a spanned
+  field.  Empty comments could work ("..").  If implemented, the same
+  marker could also be supported in simple tables, which lack
+  row-spanning abilities.
+
+  Explicit markup like ":rowspan:" and ":colspan:" was also suggested.
+
+  Sometimes in a table, the first header row contains spans.  It may
+  be necessary to provide a way to specify the column field names
+  independently of data rows.  A directive option would do it.
+
+* We could specify "column-wise" or "row-wise" ordering, with the same
+  markup structure.  For example, with definition data::
+
+      .. list-table::
+         :column-wise:
+
+         Treat
+             - Albatross!
+             - Crunchy Frog!
+         Quantity
+             - 299
+             - 1499
+         Description
+             - On a stick!
+             - If we took the bones out, it wouldn't be
+               crunchy, now would it?               
+
+* A syntax for stubs in ASCII-art tables is easy to imagine::
+
+      +------------------------++------------+----------+
+      | Header row, column 1   || Header 2   | Header 3 |
+      +========================++============+==========+
+      | body row 1, column 1   || column 2   | column 3 |
+      +------------------------++------------+----------+
+
+
+Auto-Enumerated Lists
+=====================
+
+Implemented 2005-03-24: combination of variation 1 & 2.
+
+The advantage of auto-numbered enumerated lists would be similar to
+that of auto-numbered footnotes: lists could be written and rearranged
+without having to manually renumber them.  The disadvantages are also
+the same: input and output wouldn't match exactly; the markup may be
+ugly or confusing (depending on which alternative is chosen).
+
+1. Use the "#" symbol.  Example::
+
+       #. Item 1.
+       #. Item 2.
+       #. Item 3.
+
+   Advantages: simple, explicit.  Disadvantage: enumeration sequence
+   cannot be specified (limited to arabic numerals); ugly.
+
+2. As a variation on #1, first initialize the enumeration sequence?
+   For example::
+
+       a) Item a.
+       #) Item b.
+       #) Item c.
+
+   Advantages: simple, explicit, any enumeration sequence possible.
+   Disadvantages: ugly; perhaps confusing with mixed concrete/abstract
+   enumerators.
+
+3. Alternative suggested by Fred Bremmer, from experience with MoinMoin::
+
+       1. Item 1.
+       1. Item 2.
+       1. Item 3.
+
+   Advantages: enumeration sequence is explicit (could be multiple
+   "a." or "(I)" tokens).  Disadvantages: perhaps confusing; otherwise
+   erroneous input (e.g., a duplicate item "1.") would pass silently,
+   either causing a problem later in the list (if no blank lines
+   between items) or creating two lists (with blanks).
+
+   Take this input for example::
+
+       1. Item 1.
+
+       1. Unintentional duplicate of item 1.
+
+       2. Item 2.
+
+   Currently the parser will produce two list, "1" and "1,2" (no
+   warnings, because of the presence of blank lines).  Using Fred's
+   notation, the current behavior is "1,1,2 -> 1 1,2" (without blank
+   lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2").  What
+   should the behavior be with auto-numbering?
+
+   Fred has produced a patch__, whose initial behavior is as follows::
+
+       1,1,1   -> 1,2,3
+       1,2,2   -> 1,2,3
+       3,3,3   -> 3,4,5
+       1,2,2,3 -> 1,2,3 [WARNING] 3
+       1,1,2   -> 1,2 [WARNING] 2
+
+   (After the "[WARNING]", the "3" would begin a new list.)
+
+   I have mixed feelings about adding this functionality to the spec &
+   parser.  It would certainly be useful to some users (myself
+   included; I often have to renumber lists).  Perhaps it's too
+   clever, asking the parser to guess too much.  What if you *do* want
+   three one-item lists in a row, each beginning with "1."?  You'd
+   have to use empty comments to force breaks.  Also, I question
+   whether "1,2,2 -> 1,2,3" is optimal behavior.
+
+   In response, Fred came up with "a stricter and more explicit rule
+   [which] would be to only auto-number silently if *all* the
+   enumerators of a list were identical".  In that case::
+
+       1,1,1   -> 1,2,3
+       1,2,2   -> 1,2 [WARNING] 2
+       3,3,3   -> 3,4,5
+       1,2,2,3 -> 1,2 [WARNING] 2,3
+       1,1,2   -> 1,2 [WARNING] 2
+
+   Should any start-value be allowed ("3,3,3"), or should
+   auto-numbered lists be limited to begin with ordinal-1 ("1", "A",
+   "a", "I", or "i")?
+
+   __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802
+      &group_id=38414&atid=422032
+
+4. Alternative proposed by Tony Ibbs::
+
+       #1. First item.
+       #3. Aha - I edited this in later.
+       #2. Second item.
+
+   The initial proposal required unique enumerators within a list, but
+   this limits the convenience of a feature of already limited
+   applicability and convenience.  Not a useful requirement; dropped.
+
+   Instead, simply prepend a "#" to a standard list enumerator to
+   indicate auto-enumeration.  The numbers (or letters) of the
+   enumerators themselves are not significant, except:
+
+   - as a sequence indicator (arabic, roman, alphabetic; upper/lower),
+
+   - and perhaps as a start value (first list item).
+
+   Advantages: explicit, any enumeration sequence possible.
+   Disadvantages: a bit ugly.
+
+
 -----------------
  Not Implemented
 -----------------
@@ -1906,121 +2273,9 @@ deprecation warnings.  I'm not sure the benefit is worth the cost.
 For now, we'll treat this as an unresolved legacy issue.
 
 
--------
- To Do
--------
-
-Auto-Enumerated Lists
-=====================
-
-The advantage of auto-numbered enumerated lists would be similar to
-that of auto-numbered footnotes: lists could be written and rearranged
-without having to manually renumber them.  The disadvantages are also
-the same: input and output wouldn't match exactly; the markup may be
-ugly or confusing (depending on which alternative is chosen).
-
-1. Use the "#" symbol.  Example::
-
-       #. Item 1.
-       #. Item 2.
-       #. Item 3.
-
-   Advantages: simple, explicit.  Disadvantage: enumeration sequence
-   cannot be specified (limited to arabic numerals); ugly.
-
-2. As a variation on #1, first initialize the enumeration sequence?
-   For example::
-
-       a) Item a.
-       #) Item b.
-       #) Item c.
-
-   Advantages: simple, explicit, any enumeration sequence possible.
-   Disadvantages: ugly; perhaps confusing with mixed concrete/abstract
-   enumerators.
-
-3. Alternative suggested by Fred Bremmer, from experience with MoinMoin::
-
-       1. Item 1.
-       1. Item 2.
-       1. Item 3.
-
-   Advantages: enumeration sequence is explicit (could be multiple
-   "a." or "(I)" tokens).  Disadvantages: perhaps confusing; otherwise
-   erroneous input (e.g., a duplicate item "1.") would pass silently,
-   either causing a problem later in the list (if no blank lines
-   between items) or creating two lists (with blanks).
-
-   Take this input for example::
-
-       1. Item 1.
-
-       1. Unintentional duplicate of item 1.
-
-       2. Item 2.
-
-   Currently the parser will produce two list, "1" and "1,2" (no
-   warnings, because of the presence of blank lines).  Using Fred's
-   notation, the current behavior is "1,1,2 -> 1 1,2" (without blank
-   lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2").  What
-   should the behavior be with auto-numbering?
-
-   Fred has produced a patch__, whose initial behavior is as follows::
-
-       1,1,1   -> 1,2,3
-       1,2,2   -> 1,2,3
-       3,3,3   -> 3,4,5
-       1,2,2,3 -> 1,2,3 [WARNING] 3
-       1,1,2   -> 1,2 [WARNING] 2
-
-   (After the "[WARNING]", the "3" would begin a new list.)
-
-   I have mixed feelings about adding this functionality to the spec &
-   parser.  It would certainly be useful to some users (myself
-   included; I often have to renumber lists).  Perhaps it's too
-   clever, asking the parser to guess too much.  What if you *do* want
-   three one-item lists in a row, each beginning with "1."?  You'd
-   have to use empty comments to force breaks.  Also, I question
-   whether "1,2,2 -> 1,2,3" is optimal behavior.
-
-   In response, Fred came up with "a stricter and more explicit rule
-   [which] would be to only auto-number silently if *all* the
-   enumerators of a list were identical".  In that case::
-
-       1,1,1   -> 1,2,3
-       1,2,2   -> 1,2 [WARNING] 2
-       3,3,3   -> 3,4,5
-       1,2,2,3 -> 1,2 [WARNING] 2,3
-       1,1,2   -> 1,2 [WARNING] 2
-
-   Should any start-value be allowed ("3,3,3"), or should
-   auto-numbered lists be limited to begin with ordinal-1 ("1", "A",
-   "a", "I", or "i")?
-
-   __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802
-      &group_id=38414&atid=422032
-
-4. Alternative proposed by Tony Ibbs::
-
-       #1. First item.
-       #3. Aha - I edited this in later.
-       #2. Second item.
-
-   The initial proposal required unique enumerators within a list, but
-   this limits the convenience of a feature of already limited
-   applicability and convenience.  Not a useful requirement; dropped.
-
-   Instead, simply prepend a "#" to a standard list enumerator to
-   indicate auto-enumeration.  The numbers (or letters) of the
-   enumerators themselves are not significant, except:
-
-   - as a sequence indicator (arabic, roman, alphabetic; upper/lower),
-
-   - and perhaps as a start value (first list item).
-
-   Advantages: explicit, any enumeration sequence possible.
-   Disadvantages: a bit ugly.
-
+-------
+ To Do
+-------
 
 Nested Inline Markup
 ====================
@@ -2150,259 +2405,6 @@ unambiguous::
 IOW, the parser ought to be as permissive as possible.
 
 
-List-Driven Tables
-==================
-
-The original idea came from Dylan Jay:
-
-    ... to use a two level bulleted list with something to
-    indicate it should be rendered as a table ...
-
-It's an interesting idea.  It could be implemented in as a directive
-which transforms a uniform two-level list into a table.  Using a
-directive would allow the author to explicitly set the table's
-orientation (by column or by row), the presence of row headers, etc.
-
-Alternatives:
-
-1. (Implemented in Docutils 0.3.8).
-
-   Bullet-list-tables might look like this::
-
-       .. list-table::
-
-          * - Treat
-            - Quantity
-            - Description
-          * - Albatross!
-            - 299
-            - On a stick!
-          * - Crunchy Frog!
-            - 1499
-            - If we took the bones out, it wouldn't be crunchy,
-              now would it?
-          * - Gannet Ripple!
-            - 199
-            - On a stick!
-
-   This list must be written in two levels.  This wouldn't work::
-
-       .. list-table::
-
-          * Treat
-          * Albatross!
-          * Gannet!
-          * Crunchy Frog!
-
-          * Quantity
-          * 299
-          * 199
-          * 1499
-
-          * Description
-          * On a stick!
-          * On a stick!
-          * If we took the bones out...
-
-   The above is a single list of 12 items.  The blank lines are not
-   significant to the markup.  We'd have to explicitly specify how
-   many columns or rows to use, which isn't a good idea.
-
-2. Beni Cherniavsky suggested a field list alternative.  It could look
-   like this::
-
-       .. field-list-table::
-          :headrows: 1
-
-          - :treat: Treat
-            :quantity: Quantity
-            :descr: Description
-
-          - :treat: Albatross!
-            :quantity: 299
-            :descr: On a stick!
-
-          - :treat: Crunchy Frog!
-            :quantity: 1499
-            :descr: If we took the bones out, it wouldn't be
-                    crunchy, now would it?
-
-   Column order is determined from the order of fields in the first
-   row.  Field order in all other rows is ignored.  As a side-effect,
-   this allows trivial re-arrangement of columns.  By using named
-   fields, it becomes possible to omit fields in some rows without
-   losing track of things, which is important for spans.
-
-3. An alternative to two-level bullet lists would be to use enumerated
-   lists for the table cells::
-
-       .. list-table::
-
-           * 1. Treat
-             2. Quantity
-             3. Description
-           * 1. Albatross!
-             2. 299
-             3. On a stick!
-           * 1. Crunchy Frog!
-             2. 1499
-             3. If we took the bones out, it wouldn't be crunchy,
-                now would it?
-
-   That provides better correspondence between cells in the same
-   column than does bullet-list syntax, but not as good as field list
-   syntax.  I think that were only field-list-tables available, a lot
-   of users would use the equivalent degenerate case::
-
-       .. field-list-table::
-           - :1: Treat
-             :2: Quantity
-             :3: Description
-           ...
-
-4. Another natural variant is to allow a description list with field
-   lists as descriptions::
-
-       .. list-table::
-           :headrows: 1
-
-           Treat
-               :quantity: Quantity
-               :descr: Description
-           Albatross!
-               :quantity: 299
-               :descr: On a stick!
-           Crunchy Frog!
-               :quantity: 1499
-               :descr: If we took the bones out, it wouldn't be
-                       crunchy, now would it?
-
-   This would make the whole first column a header column ("stub").
-   It's limited to a single column and a single paragraph fitting on
-   one source line.  Also it wouldn't allow for empty cells or row
-   spans in the first column.  But these are limitations that we could
-   live with, like those of simple tables.
-
-The List-driven table feature could be done in many ways.  Each user
-will have their preferred usage.  Perhaps a single "list-table"
-directive could handle them all, depending on which options and
-content are present.
-
-Issues:
-
-* How to indicate that there's 1 header row?  Perhaps two lists?  ::
-
-      .. list-table::
-
-         + - Treat
-           - Quantity
-           - Description
-
-         * - Albatross!
-           - 299
-           - On a stick!
-
-  This is probably too subtle though.  Better would be a directive
-  option, like ``:headrows: 1``.  An early suggestion for the header
-  row(s) was to use a directive option::
-
-      .. field-list-table::
-         :header:
-             - :treat: Treat
-               :quantity: Quantity
-               :descr: Description
-         - :treat: Albatross!
-           :quantity: 299
-           :descr: On a stick!
-
-  But the table data is at two levels and looks inconsistent.
-
-  In general, we cannot extract the header row from field lists' field
-  names because field names cannot contain everything one might put in
-  a table cell.  A separate header row also allows shorter field names
-  and doesn't force one to rewrite the whole table when the header
-  text changes.  But for simpler cases, we can offer a ":header:
-  fields" option, which does extract header cells from field names::
-
-      .. field-list-table::
-          :header: fields
-
-          - :Treat: Albatross!
-            :Quantity: 299
-            :Description: On a stick!
-
-* How to indicate the column widths?  A directive option? ::
-
-      .. list-table::
-         :widths: 15 10 35
-
-  Automatic defaults from the text used?
-
-* How to handle row and/or column spans?
-
-  In a field list, column-spans can be indicated by specifying the
-  first and last fields, separated by space-dash-space or ellipsis::
-
-      - :foo - baz: quuux
-      - :foo ... baz: quuux
-
-  Commas were proposed for column spans::
-
-      - :foo, bar: quux
-
-  But non-adjacent columns become problematic.  Should we report an
-  error, or duplicate the value into each span of adjacent columns (as
-  was suggested)?  The latter suggestion is appealing but may be too
-  clever.  Best perhaps to simply specify the two ends.
-
-  It was suggested that comma syntax should be allowed, too, in order
-  to allow the user to avoid trouble when changing the column order.
-  But changing the column order of a table with spans is not trivial;
-  we shouldn't make it easier to mess up.
-
-  One possible syntax for row-spans is to simply treat any row where a
-  field is missing as a row-span from the last row where it appeared.
-  Leaving a field empty would still be possible by writing a field
-  with empty content.  But this is too implicit.
-
-  Another way would be to require an explicit continuation marker
-  (``...``/``-"-``/``"``?) in all but the first row of a spanned
-  field.  Empty comments could work ("..").  If implemented, the same
-  marker could also be supported in simple tables, which lack
-  row-spanning abilities.
-
-  Explicit markup like ":rowspan:" and ":colspan:" was also suggested.
-
-  Sometimes in a table, the first header row contains spans.  It may
-  be necessary to provide a way to specify the column field names
-  independently of data rows.  A directive option would do it.
-
-* We could specify "column-wise" or "row-wise" ordering, with the same
-  markup structure.  For example, with definition data::
-
-      .. list-table::
-         :column-wise:
-
-         Treat
-             - Albatross!
-             - Crunchy Frog!
-         Quantity
-             - 299
-             - 1499
-         Description
-             - On a stick!
-             - If we took the bones out, it wouldn't be
-               crunchy, now would it?               
-
-* A syntax for stubs in ASCII-art tables is easy to imagine::
-
-      +------------------------++------------+----------+
-      | Header row, column 1   || Header 2   | Header 3 |
-      +========================++============+==========+
-      | body row 1, column 1   || column 2   | column 3 |
-      +------------------------++------------+----------+
-
-
 Index Entries & Indexes
 =======================
 
-- 
cgit v1.2.1


From 9dbc2adead008935245a396eab10bb7bcb11b226 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 26 Mar 2005 16:21:28 +0000
Subject: merged rev. 3094:3101 and 3102:HEAD from branches/multiple-ids to
 trunk

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3129 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt |  8 ++++----
 docs/ref/doctree.txt          | 44 +++++++++++++++++++++----------------------
 docs/ref/transforms.txt       |  4 +---
 3 files changed, 27 insertions(+), 29 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 25732189f..08c94bbbb 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -1165,7 +1165,7 @@ start of a new "division".  Before implementation, the parsed document
 tree would be::
 
     <document>
-        <section name="document">
+        <section names="document">
             <title>
                 Document
             <paragraph>
@@ -1181,7 +1181,7 @@ There are several possibilities for the implementation:
    try at an implementation looked like this::
 
        <document>
-           <section name="document">
+           <section names="document">
                <title>
                    Document
                <paragraph>
@@ -1199,7 +1199,7 @@ There are several possibilities for the implementation:
    possibility::
 
        <document>
-           <section name="document">
+           <section names="document">
                <title>
                    Document
                <division>
@@ -1220,7 +1220,7 @@ There are several possibilities for the implementation:
 3. Implement them as "transitions", empty elements::
 
        <document>
-           <section name="document">
+           <section names="document">
                <title>
                    Document
                <paragraph>
diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 43ce91d33..dc19bdff3 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -264,7 +264,7 @@ following subsections:
   - Real XML::
 
         <document>
-        <section id="a-title" name="a title">
+        <section ids="a-title" names="a title">
         <title>A Title
         A paragraph.
         
    
@@ -273,7 +273,7 @@ following subsections:
   - Pseudo-XML::
 
         
-            
    
+            
    
                 
                     A Title
                 <paragraph>
@@ -359,7 +359,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -559,7 +559,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -625,7 +625,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -1016,7 +1016,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -1082,7 +1082,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -1210,7 +1210,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -1617,7 +1617,7 @@ into a ``docinfo`` element and its children by a transform.  Source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="docinfo-example" name="docinfo example">
+    <document ids="docinfo-example" names="docinfo example">
         <title>
             Docinfo Example
         <docinfo>
@@ -1794,7 +1794,7 @@ reStructuredText_ source::
 Complete pseudo-XML_ result from simple parsing::
 
     <document>
-        <section id="a-title" name="a title">
+        <section ids="a-title" names="a title">
             <title>
                 A Title
             <paragraph>
@@ -1803,7 +1803,7 @@ Complete pseudo-XML_ result from simple parsing::
 After applying transforms, the section title is promoted to become the
 document title::
 
-    <document id="a-title" name="a title">
+    <document ids="a-title" names="a title">
         <title>
             A Title
         <paragraph>
@@ -3221,7 +3221,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -3371,7 +3371,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -3479,22 +3479,22 @@ reStructuredText_ source::
 Complete pseudo-XML_ result after parsing::
 
     <document>
-        <section id="title-1" name="title 1">
+        <section ids="title-1" names="title 1">
             <title>
                 Title 1
             <paragraph>
                 Paragraph 1.
-            <section id="title-2" name="title 2">
+            <section ids="title-2" names="title 2">
                 <title>
                     Title 2
                 <paragraph>
                     Paragraph 2.
-        <section id="title-3" name="title 3">
+        <section ids="title-3" names="title 3">
             <title>
                 Title 3
             <paragraph>
                 Paragraph 3.
-            <section id="title-4" name="title 4">
+            <section ids="title-4" names="title 4">
                 <title>
                     Title 4
                 <paragraph>
@@ -3638,7 +3638,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
@@ -3728,10 +3728,10 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="title" name="title">
+    <document ids="title" names="title">
         <title>
             Title
-        <subtitle id="subtitle" name="subtitle">
+        <subtitle ids="subtitle" names="subtitle">
             Subtitle
         <paragraph>
             A paragraph.
@@ -3946,7 +3946,7 @@ reStructuredText_ source::
 
 Pseudo-XML_ fragment from simple parsing::
 
-    <section id="a-title" name="a title">
+    <section ids="a-title" names="a title">
         <title>
             A Title
         <paragraph>
@@ -4170,7 +4170,7 @@ reStructuredText_ source::
 
 Complete pseudo-XML_ result after parsing and applying transforms::
 
-    <document id="document-title" name="document title">
+    <document ids="document-title" names="document title">
         <title>
             Document Title
         <docinfo>
diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index db4d3c426..9e4687a72 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -28,7 +28,7 @@ misc.class                      "class" (d/p)                 210
 
 references.Substitutions        standalone (r), pep (r)       220
 
-references.SectionTargets       standalone (r), pep (r)       260
+references.PropagateTargets     standalone (r), pep (r)       260
 
 frontmatter.DocTitle            standalone (r)                320
 
@@ -38,8 +38,6 @@ peps.Headers                    pep (r)                       360
 
 peps.Contents                   pep (r)                       380
 
-references.ChainedTargets       standalone (r), pep (r)       420
-
 references.AnonymousHyperlinks  standalone (r), pep (r)       440
 
 references.IndirectHyperlinks   standalone (r), pep (r)       460
-- 
cgit v1.2.1


From bf160723971d1fd68ad8db3466fbd1676c3988a7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 30 Mar 2005 19:20:35 +0000
Subject: removed "list-table" target which was redundant and caused the TOC
 link to point to #id4 instead of #list-table

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3148 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 2 --
 1 file changed, 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 1b0ff108d..ff5862680 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -777,8 +777,6 @@ The following options are recognized:
        the default case?
 
 
-.. _list-table:
-
 List Table
 ==========
 
-- 
cgit v1.2.1


From 2149d14d2dce1fde4ee9fc12d50d9552d57721db Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 2 Apr 2005 21:32:12 +0000
Subject: removed to-do list entried already implemented

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3154 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ------
 1 file changed, 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 450d20a73..5e1c5db9b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -371,9 +371,6 @@ General
   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?
@@ -1374,9 +1371,6 @@ when used in a document.
     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"
-- 
cgit v1.2.1


From bca2f72bbb3174d4a96673ae89c76d4e5a8bb371 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 2 Apr 2005 22:26:16 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3157 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5e1c5db9b..0c3da55d3 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -85,6 +85,10 @@ General
 * Add option for file (and URL) access restriction to make Docutils
   usable in Wikis and similar applications.
 
+  2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
+  settings.  These partially solve the problem, allowing or disabling
+  **all** file accesses, but not limited access.
+
 * Refactor
 
   - Rename methods & variables according to the `Python coding
-- 
cgit v1.2.1


From f50fddc9910ce8f558f45a51b4c0a8ff06ec2878 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 2 Apr 2005 22:39:59 +0000
Subject: protected some backslashes; added entry about unnecessary backslashes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3158 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 0c3da55d3..0f0f07e2c 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -665,6 +665,11 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Create ``info``-level system messages for unnecessarily
+  backslash-escaped characters (as in ``"\something"``, rendered as
+  "something") to allow checking for errors which silently slipped
+  through.
+
 * Add (functional) tests for untested roles.
 
 * The parser doesn't know anything about double-width characters such
@@ -890,9 +895,9 @@ __ rst/alternatives.html#or-not-to-do
   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.
+  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
+  (^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
@@ -923,10 +928,10 @@ __ rst/alternatives.html#or-not-to-do
 
 * 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")?
+  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
+  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
@@ -939,8 +944,8 @@ __ rst/alternatives.html#or-not-to-do
   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 "\";
+  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
-- 
cgit v1.2.1


From f1da7eb10858e31b6e69f96bf9c7f3e46801f50f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 4 Apr 2005 17:05:37 +0000
Subject: added the "field_name_limit" setting, test & docs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3164 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 0fba204c1..fdc05842a 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -228,6 +228,14 @@ _`expose_internals`
     Default: don't (None).  Options: ``--expose-internal-attribute``
     (hidden, for development use only).
 
+_`field_name_limit`
+
+    The maximum width (in characters) for one-column field names.
+    Longer field names will span the entire row.  0 indicates "no
+    limit".
+
+    Default: 14 characters.  Option: ``--field-name-limit``.
+
 _`file_insertion_enabled`
     Enable or disable directives that insert the contents of external
     files, such as the "include_" & "raw_".  A "warning" system
-- 
cgit v1.2.1


From dc3284ca85006e72f0e3b2c4ffbe078aa9148f76 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 02:55:06 +0000
Subject: added "stub-columns" options to "csv-table" and "list-table"
 directives, plus support, docs, and tests

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd       | 4 +++-
 docs/ref/rst/directives.txt | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index a18eae36b..d9a76ce2e 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -166,7 +166,9 @@ http://www.oasis-open.org/html/tm9901.htm).
 <!ENTITY % tbl.tgroup.att       " %basic.atts; ">
 <!ENTITY % tbl.thead.att        " %basic.atts; ">
 <!ENTITY % tbl.tbody.att        " %basic.atts; ">
-<!ENTITY % tbl.colspec.att      " %basic.atts; ">
+<!ENTITY % tbl.colspec.att
+  " %basic.atts;
+    stub      %yesorno; #IMPLIED ">
 <!ENTITY % tbl.row.att          " %basic.atts; ">
 <!ENTITY % tbl.entry.mdl        " (%body.elements;)* ">
 <!ENTITY % tbl.entry.att
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index ff5862680..8be376eb6 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -735,6 +735,10 @@ The following options are recognized:
     The number of rows of CSV data to use in the table header.
     Defaults to 0.
 
+``stub-columns`` : integer
+    The number of table columns to use as stubs (row titles, on the
+    left).  Defaults to 0.
+
 ``header`` : CSV data
     Supplemental data for the table header, added independently of and
     before any ``header-rows`` from the main CSV data.  Must use the
@@ -829,6 +833,10 @@ The following options are recognized:
     The number of rows of list data to use in the table header.
     Defaults to 0.
 
+``stub-columns`` : integer
+    The number of table columns to use as stubs (row titles, on the
+    left).  Defaults to 0.
+
 
 ----------------
  Document Parts
-- 
cgit v1.2.1


From d6ab28097870eadae43ea8975d984a27a2ee0379 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 03:29:10 +0000
Subject: fixed mistaken indentation

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3168 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 8be376eb6..3de9832db 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -486,6 +486,8 @@ Rubric
 :Directive Options: Possible.
 :Directive Content: None.
 
+..
+
      rubric n. 1. a title, heading, or the like, in a manuscript,
      book, statute, etc., written or printed in red or otherwise
      distinguished from the rest of the text. ...
-- 
cgit v1.2.1


From 8cc8a7b68db6775d44db53403e23a72111f2e4bf Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 03:39:52 +0000
Subject: added syntax idea for table stubs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3169 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 08c94bbbb..50b13392b 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -1696,7 +1696,7 @@ Issues:
          Description
              - On a stick!
              - If we took the bones out, it wouldn't be
-               crunchy, now would it?               
+               crunchy, now would it?
 
 * A syntax for stubs in ASCII-art tables is easy to imagine::
 
@@ -1706,6 +1706,16 @@ Issues:
       | body row 1, column 1   || column 2   | column 3 |
       +------------------------++------------+----------+
 
+  Or this idea from Nick Moffitt::
+
+      +-----+---+---+
+      | XOR # T | F |
+      +=====+===+===+
+      |   T # F | T |
+      +-----+---+---+
+      |   F # T | F |
+      +-----+---+---+
+
 
 Auto-Enumerated Lists
 =====================
@@ -2102,7 +2112,7 @@ __ http://thread.gmane.org/gmane.text.docutils.devel/1386
 
 1. References and targets take this form::
 
-       targetname_   
+       targetname_
 
        .. _targetname: stuff
 
@@ -2203,7 +2213,7 @@ __ http://thread.gmane.org/gmane.text.docutils.devel/1386
    ".. comment::" would violate that.  The goals of reStructuredText
    are many, and they conflict.  Determining the right set of goals
    and finding solutions that best fit is done on a case-by-case
-   basis.  
+   basis.
 
    Even readability is has two aspects.  Being readable without any
    prior knowledge is one.  Being as easily read in raw form as in
-- 
cgit v1.2.1


From 729bd558dd73911547be889a6c8c991870e65b5f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 04:06:56 +0000
Subject: added new idea for compact definition lists

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3170 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 52 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 44 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index f73342fa4..e37bb0ded 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -388,7 +388,8 @@ Where the classifier part is optional.  Ideas for improvements:
        term : classifier one : two : three ...
            definition
 
-2. We could allow the definition on the same line as the term.
+2. We could allow the definition on the same line as the term, using
+   some embedded/inline markup:
 
    * "--" could be used, but only in limited and well-known contexts::
 
@@ -411,7 +412,42 @@ Where the classifier part is optional.  Ideas for improvements:
      This syntax has advantages.  Equals signs lend themselves to the
      connotation of "definition".  And whereas one or two equals signs
      are commonly used in program code, three equals signs in a row
-     have no conflicting meanings that I know of.
+     have no conflicting meanings that I know of.  (Update: there
+     *are* uses out there.)
+
+   The problem with this approach is that using inline markup for
+   structure is inherently ambiguous in reStructuredText.  For
+   example, writing *about* definition lists would be difficult::
+
+       ``term === definition`` is an example of a compact definition list item
+
+   The parser checks for structural markup before it does inline
+   markup processing.  But the "===" should be protected by its inline
+   literal context.
+
+3. We could allow the definition on the same line as the term, using
+   structural markup.  A variation on bullet lists would work well::
+
+       : term :: definition
+       : another term :: and a definition that
+         wraps across lines
+
+   Some ambiguity remains::
+
+       : term ``containing :: double colons`` :: definition
+
+   But the likelihood of such cases is negligible, and they can be
+   covered in the documentation.
+
+   Other possibilities for the definition delimiter include::
+
+       : term : classifier -- definition
+       : term : classifier --- definition
+       : term : classifier : : definition
+       : term : classifier === definition
+
+The third idea currently has the best chance of being adopted and
+implemented.
 
 
 Recommendation
@@ -425,13 +461,13 @@ Combining these ideas, the function definition becomes::
         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
+            : 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
+            : 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).
-- 
cgit v1.2.1


From 260212205f6acb893a305d3575d76f493a68b724 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 21:04:04 +0000
Subject: removed unnecessary backslash

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3173 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 3de9832db..d0f6cd453 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -815,7 +815,7 @@ Example::
          - On a stick!
        * - Crunchy Frog
          - 1.49
-         - If we took the bones out, it wouldn\'t be
+         - If we took the bones out, it wouldn't be
            crunchy, now would it?
        * - Gannet Ripple
          - 1.99
-- 
cgit v1.2.1


From 5b2787e17e9dc54537136f376fc2a499a7b90b66 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 21:52:48 +0000
Subject: added links for image and meta directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3174 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 4ed975144..c32e48db6 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -807,7 +807,7 @@ processing.  They may also be used for two-column table-like
 structures resembling database records (label & data pairs).
 Applications of reStructuredText may recognize field names and
 transform fields or field bodies in certain contexts.  For examples,
-see `Bibliographic Fields`_ below, or the "image" and "meta"
+see `Bibliographic Fields`_ below, or the "image_" and "meta_"
 directives in `reStructuredText Directives`_.
 
 Field lists are mappings from field names to field bodies, modeled on
@@ -2814,6 +2814,8 @@ Markup errors are handled according to the specification in `PEP
 .. _World Wide Web Consortium: http://www.w3.org/
 .. _HTML Techniques for Web Content Accessibility Guidelines:
    http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
+.. _image: directives.html#image
+.. _meta: directives.html#meta
 .. _reStructuredText Directives: directives.html
 .. _reStructuredText Interpreted Text Roles: roles.html
 .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt
-- 
cgit v1.2.1


From 0e2d41b9ac2cd4c2fd17ece211048d9727685af6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Apr 2005 21:59:20 +0000
Subject: added some more links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3175 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index c32e48db6..57362c5db 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1927,17 +1927,17 @@ Directives`_ document, and are always available.  Any other directives
 are domain-specific, and may require special action to make them
 available when processing the document.
 
-For example, here's how an image may be placed::
+For example, here's how an image_ may be placed::
 
     .. image:: mylogo.jpeg
 
-A figure (a graphic with a caption) may placed like this::
+A figure_ (a graphic with a caption) may placed like this::
 
     .. figure:: larch.png
 
        The larch.
 
-An admonition (note, caution, etc.) contains other body elements::
+An admonition_ (note, caution, etc.) contains other body elements::
 
     .. note:: This is a paragraph
 
@@ -2028,7 +2028,7 @@ Substitution definitions are indicated by an explicit markup start
 vertical bar, whitespace, and the definition block.  Substitution text
 may not begin or end with whitespace.  A substitution definition block
 contains an embedded inline-compatible directive (without the leading
-".. "), such as an image.  For example::
+".. "), such as an image_.  For example::
 
     The |biohazard| symbol must be used on containers used to
     dispose of medical waste.
@@ -2133,7 +2133,7 @@ Images
         .. |-><-| image:: discord.png
         .. _POEE: http://www.poee.org/
 
-    The "image" directive has been implemented.
+    The "image_" directive has been implemented.
 
 Styles [#]_
     Substitution references may be used to associate inline text with
@@ -2816,6 +2816,8 @@ Markup errors are handled according to the specification in `PEP
    http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
 .. _image: directives.html#image
 .. _meta: directives.html#meta
+.. _figure: directives.html#figure
+.. _admonition: directives.html#admonitions
 .. _reStructuredText Directives: directives.html
 .. _reStructuredText Interpreted Text Roles: roles.html
 .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt
-- 
cgit v1.2.1


From d9aa90d0084ff873108c7ede8854fed0803eab95 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 6 Apr 2005 16:11:47 +0000
Subject: added some directive ideas

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3177 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 0f0f07e2c..3d6c910ac 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1095,6 +1095,12 @@ when used in a document.
   - All directives that produce titled elements should grow implicit
     reference names based on the titles.
 
+  - Allow the _`:trim:` option for all directives when they occur in a
+    substitution definition, not only the unicode_ directive.
+
+    .. _unicode:
+       http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
+
   - _`images.image`: "border"?
 
     _`Units of measure`?  (See `docutils-users, 2003-03-02
@@ -1155,6 +1161,10 @@ when used in a document.
     Add an option to include topics in the TOC?  Another for sidebars?
     See docutils-develop 2003-01-29.
 
+  - _`parts.header` & _`parts.footer`: Add "header" and "footer"
+    directives to specify document-specific contents for header and
+    footer?
+
   - _`misc.include`:
 
     - "encoding" option?  Take default from runtime settings.  Use
@@ -1200,11 +1210,15 @@ when used in a document.
           .. include:: 
              :url: http://www.example.org/inclusion.txt
 
-  - Allow the _`:trim:` option for all directives when they occur in a
-    substitution definition, not only the unicode_ directive.
+  - _`misc.raw`: add a "destination" option to the "raw" directive? ::
 
-    .. _unicode:
-       http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
+        .. raw:: html
+           :destination: head
+
+           <link ...>
+
+    It needs thought & discussion though, to come up with a consistent
+    set of destination labels and consistent behavior.
   
 * Implement directives.  Each of the list items below begins with an
   identifier of the form, "module_name.directive_function_name".  The
-- 
cgit v1.2.1


From 57b9447562a8e3717e751ebc0512eaa525667747 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 6 Apr 2005 18:55:30 +0000
Subject: added some more auto-props

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3178 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 5311f9a1b..842e5b694 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -87,6 +87,9 @@ correct properties set::
     [auto-props]
     *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision
     *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision
     *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
     *.png = svn:mime-type=image/png
 
-- 
cgit v1.2.1


From dc47ace1b81b477ae3383ac48e13faab201e66dd Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 6 Apr 2005 19:38:32 +0000
Subject: reworked instructions as enumerated list

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3179 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 842e5b694..ade960c12 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -102,32 +102,32 @@ Subversion servers without having to enter your password.  There are
 two places to add your SSH public key on BerliOS: your web account and
 your shell account.
 
-1. Adding your SSH key to your BerliOS web account:
+* Adding your SSH key to your BerliOS web account:
 
-   * Log in on the web at https://developer.berlios.de/.  Create your
+  1. Log in on the web at https://developer.berlios.de/.  Create your
      account first if necessary.  You should be taken to your "My
      Personal Page" (https://developer.berlios.de/my/).
 
-   * Choose "Account Options" from the menu below the top banner.
+  2. Choose "Account Options" from the menu below the top banner.
 
-   * At the bottom of the "Account Maintenance" page
+  3. At the bottom of the "Account Maintenance" page
      (https://developer.berlios.de/account/) you'll find a "Shell
      Account Information" section; click on "[Edit Keys]".
 
-   * Copy and paste your SSH public key into the edit box on this page
+  4. Copy and paste your SSH public key into the edit box on this page
      (https://developer.berlios.de/account/editsshkeys.php).  Further
      instructions are available on this page.
 
-2. Adding your SSH key to your BerliOS shell account:
+* Adding your SSH key to your BerliOS shell account:
 
-   * Log in to the BerliOS shell server::
+  1. Log in to the BerliOS shell server::
 
          ssh username@shell.berlios.de
 
      You'll be asked for your password, which you set when you created
      your account.
 
-   * Create a .ssh directory in your home directory, and remove
+  2. Create a .ssh directory in your home directory, and remove
      permissions for group & other::
 
          mkdir .ssh
@@ -135,12 +135,12 @@ your shell account.
 
      Exit the SSH session.
 
-   * Copy your public key to the .ssh directory on BerliOS::
+  3. Copy your public key to the .ssh directory on BerliOS::
 
          scp .ssh/id_dsa.pub username@shell.berlios.de:.ssh/authorized_keys
 
-   Now you should be able to start an SSH session without needing your
-   password.
+  Now you should be able to start an SSH session without needing your
+  password.
 
 
 Web Access
-- 
cgit v1.2.1


From 7aacd6e6d0db8e988b1718dd6fd52703223fda52 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 03:07:14 +0000
Subject: moved descriptions to the correct sections

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3180 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 50 +++++++++++++++++++++++++-------------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index fdc05842a..26f4a24f8 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -228,25 +228,6 @@ _`expose_internals`
     Default: don't (None).  Options: ``--expose-internal-attribute``
     (hidden, for development use only).
 
-_`field_name_limit`
-
-    The maximum width (in characters) for one-column field names.
-    Longer field names will span the entire row.  0 indicates "no
-    limit".
-
-    Default: 14 characters.  Option: ``--field-name-limit``.
-
-_`file_insertion_enabled`
-    Enable or disable directives that insert the contents of external
-    files, such as the "include_" & "raw_".  A "warning" system
-    message (including the directive text) is inserted instead.
-
-    Default: enabled (1).  Options: ``--file-insertion-enabled,
-    --no-file-insertion``.
-
-    .. _include: ../ref/rst/directives.html#include
-    .. _raw: ../ref/rst/directives.html#raw
-
 _`footnote_backlinks`
     Enable or disable backlinks from footnotes and citations to their
     references.
@@ -328,12 +309,6 @@ _`output_encoding_error_handler`
     Default: "strict".  Options: ``--output-encoding-error-handler,
     --output-encoding, -o``.
 
-_`raw_enabled`
-    Enable or disable the "raw_" directive.  A "warning" system
-    message (including the directive text) is inserted instead.
-
-    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
-
 _`report_level`
     Verbosity threshold at or above which system messages are
     reported.
@@ -412,6 +387,17 @@ Docutils currently supports only one parser, for reStructuredText.
 [restructuredtext parser]
 `````````````````````````
 
+_`file_insertion_enabled`
+    Enable or disable directives that insert the contents of external
+    files, such as the "include_" & "raw_".  A "warning" system
+    message (including the directive text) is inserted instead.
+
+    Default: enabled (1).  Options: ``--file-insertion-enabled,
+    --no-file-insertion``.
+
+    .. _include: ../ref/rst/directives.html#include
+    .. _raw: ../ref/rst/directives.html#raw
+
 _`pep_references`
     Recognize and link to standalone PEP references (like "PEP 258").
 
@@ -424,6 +410,12 @@ _`pep_base_url`
     Default: "http://www.python.org/peps/".  Option:
     ``--pep-base-url``.
 
+_`raw_enabled`
+    Enable or disable the "raw_" directive.  A "warning" system
+    message (including the directive text) is inserted instead.
+
+    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
+
 _`rfc_references`
     Recognize and link to standalone RFC references (like "RFC 822").
 
@@ -550,6 +542,14 @@ _`embed_stylesheet`
     Default: link, don't embed (None).  Options: ``--embed-stylesheet,
     --link-stylesheet``.
 
+_`field_name_limit`
+
+    The maximum width (in characters) for one-column field names.
+    Longer field names will span the entire row.  0 indicates "no
+    limit".
+
+    Default: 14 characters.  Option: ``--field-name-limit``.
+
 .. _footnote_references [html4css1 writer]:
 
 footnote_references
-- 
cgit v1.2.1


From 4cd2bcbe53510b93a2ab547c9b315a55eeda301b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 03:13:31 +0000
Subject: added the "option_limit" setting & docs; clarified "field_name_limit"
 docs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3181 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 26f4a24f8..7e93626a1 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -543,10 +543,9 @@ _`embed_stylesheet`
     --link-stylesheet``.
 
 _`field_name_limit`
-
     The maximum width (in characters) for one-column field names.
-    Longer field names will span the entire row.  0 indicates "no
-    limit".
+    Longer field names will span an entire row of the table used to
+    render the field list.  0 indicates "no limit".
 
     Default: 14 characters.  Option: ``--field-name-limit``.
 
@@ -571,6 +570,13 @@ _`initial_header_level`
 
 .. _stylesheet [html4css1 writer]:
 
+_`option_limit`
+    The maximum width (in characters) for options in option lists.
+    Longer options will span an entire row of the table used to render
+    the option list.  0 indicates "no limit".
+
+    Default: 14 characters.  Option: ``--option-limit``.
+
 stylesheet
     CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
     [#override]_.
-- 
cgit v1.2.1


From 46507a14aebfe22b79a1564e28c73aa063e508a0 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 16:02:49 +0000
Subject: moved directive idea (they're *new*)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3182 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 3d6c910ac..f4a77b94b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1161,10 +1161,6 @@ when used in a document.
     Add an option to include topics in the TOC?  Another for sidebars?
     See docutils-develop 2003-01-29.
 
-  - _`parts.header` & _`parts.footer`: Add "header" and "footer"
-    directives to specify document-specific contents for header and
-    footer?
-
   - _`misc.include`:
 
     - "encoding" option?  Take default from runtime settings.  Use
@@ -1472,6 +1468,10 @@ when used in a document.
     either by running it at the command line with a ``--help`` option
     or through an exposed API.  [Suggestion for Optik.]
 
+  - _`parts.header` & _`parts.footer`: Add "header" and "footer"
+    directives to specify document-specific contents for header and
+    footer?
+
 
 Interpreted Text
 ----------------
-- 
cgit v1.2.1


From 71532b70cb8661bee0e5cb6cdf823c6902eb80bf Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 16:22:05 +0000
Subject: updated & added some ideas

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3183 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 36 ++++++++++++++++--------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 5757c8013..99eade2e7 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -10,9 +10,10 @@
 
 .. 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:
+Docutils is a meritocracy based on code contribution and lots of
+discussion [#bcs]_.  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.
@@ -35,7 +36,7 @@ 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.
+used as a source of improvement.  Feedback and criticism is welcome.
 
 As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
 originators of Ogg Vorbis) put it well when he said:
@@ -43,6 +44,9 @@ 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.
 
+.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion
+   project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__.
+
 
 Python Coding Conventions
 =========================
@@ -153,16 +157,16 @@ applicable), with particular emphasis as follows:
       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
+  Docutils currently supports Python 2.1 [#py21]_ or later, with some
+  things only working (and being tested) on Python 2.3+.  Therefore,
+  you should actually have Pythons 2.1 [#py21]_, 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
+  .. [#py21] 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.
 
@@ -174,18 +178,10 @@ applicable), with particular emphasis as follows:
   * `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/doc/2.3.5/whatsnew/whatsnew23.html
+  __ http://www.python.org/doc/2.4.1/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!
-- 
cgit v1.2.1


From dcc80f043243f34d0373a3150bacfff20b3212ae Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 19:36:11 +0000
Subject: added "header" & "footer" directives, tests, docs, support, and some
 tweaks

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3184 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt         | 71 ++++++++++++++++++++++++++++----------------
 docs/ref/docutils.dtd        |  7 +++--
 docs/ref/rst/directives.txt  | 41 ++++++++++++++++++++++---
 docs/user/rst/cheatsheet.txt |  3 +-
 4 files changed, 88 insertions(+), 34 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index dc19bdff3..912789239 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -62,7 +62,7 @@ one-to-many relationships; sections may contain (sub)sections, tables
 contain further body elements, etc. ::
 
   +--------------------------------------------------------------------+
-  | document  [may begin with a title, subtitle, docinfo, decoration]  |
+  | document  [may begin with a title, subtitle, decoration, docinfo]  |
   |                             +--------------------------------------+
   |                             | sections  [each begins with a title] |
   +-----------------------------+-------------------------+------------+
@@ -112,7 +112,7 @@ Structural subelements are child elements of structural elements.
 Simple structuctural subelements (title_, subtitle_) contain text
 data; the others are compound and do not directly contain text data.
 
-Category members: title_, subtitle_, docinfo_, decoration_,
+Category members: title_, subtitle_, decoration_, docinfo_,
 transition_
 
 
@@ -146,7 +146,7 @@ body elements.  There are two subcategories of body elements: simple
 and compound.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, comment_, danger_, definition_list_,
+caution_, citation_, comment_, compound_, danger_, definition_list_,
 doctest_block_, enumerated_list_, error_, field_list_, figure_,
 footnote_, hint_, image_, important_, line_block_, literal_block_,
 note_, option_list_, paragraph_, pending_, raw_, rubric_,
@@ -173,9 +173,10 @@ Compound body elements contain local substructure (body subelements)
 and further body elements.  They do not directly contain text data.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, danger_, definition_list_, enumerated_list_,
-error_, field_list_, figure_, footnote_, hint_, important_, note_,
-option_list_, system_message_, table_, tip_, warning_
+caution_, citation_, compound_, danger_, definition_list_,
+enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
+important_, note_, option_list_, system_message_, table_, tip_,
+warning_
 
 
 Body Subelements
@@ -959,6 +960,12 @@ Pseudo-XML_ fragment from simple parsing::
 `To be completed`_.
 
 
+``compound``
+============
+
+`To be completed`_.
+
+
 ``contact``
 ===========
 
@@ -1251,6 +1258,7 @@ Details
 :Processing:
     See the individual `decorative elements`_.
 
+
 Content Model
 -------------
 
@@ -1758,20 +1766,21 @@ Content Model
 
 .. parsed-literal::
 
-    ((title_,
-      subtitle_?)?,
-     docinfo_?,
-     decoration_?,
-     `%structure.model;`_)
+    ( (title_, subtitle_?)?,
+      decoration_?,
+      (docinfo_, transition_?)?,
+      `%structure.model;`_ )
 
 Depending on the source of the data and the stage of processing, the
 "document" may not initially contain a "title".  A document title is
 not directly representable in reStructuredText_.  Instead, a lone
 top-level section may have its title promoted to become the document
 title_, and similarly for a lone second-level (sub)section's title to
-become the document subtitle_.  The "docinfo_" may be transformed from
-an initial field_list_, and "decoration_" is usually constructed
-programmatically.
+become the document subtitle_.
+
+The contents of "decoration_" may be specified in a document,
+constructed programmatically, or both.  The "docinfo_" may be
+transformed from an initial field_list_.
 
 See the `%structure.model;`_ parameter entity for details of the body
 of a ``document``.
@@ -2314,7 +2323,7 @@ section numbers inserted by the "sectnum" directive.
 
 The ``header`` element is a container element whose contents are meant
 to appear at the top of a web page, or at the top of every printed
-page.  Docutils does not yet make use of the ``header`` element.
+page.
 
 
 Details
@@ -2350,7 +2359,17 @@ Content Model
 Examples
 --------
 
-None.
+reStructuredText source fragment::
+
+    .. header:: This space for rent.
+
+Pseudo-XML_ fragment from simple parsing::
+
+    <document>
+        <decoration>
+            <header>
+                <paragraph>
+                    This space for rent.
 
 
 ``hint``
@@ -4611,14 +4630,14 @@ Entity definition:
 
 .. parsed-literal::
 
-    paragraph_ | literal_block_ | doctest_block_ | line_block_
-    | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_
-    | rubric_
+    paragraph_ | compound_ | literal_block_ | doctest_block_
+    | line_block_ | block_quote_
+    | table_ | figure_ | image_ | footnote_ | citation_ | rubric_
     | bullet_list_ | enumerated_list_ | definition_list_ | field_list_
     | option_list_
-    | attention_ | caution_ | danger_ | error_ | hint_ | important_
-    | note_ | tip_ | warning_ | admonition_
-    | target_ | substitution_definition_ | comment_ | pending_
+    | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_
+    | tip_ | warning_ | admonition_
+    | reference_ | target_ | substitution_definition_ | comment_ | pending_
     | system_message_ | raw_
     %additional.body.elements;
 
@@ -4627,10 +4646,10 @@ wrapper DTDs to extend ``%body.elements;``.
 
 The ``%body.elements;`` parameter entity is directly employed in the
 content models of the following elements: admonition_, attention_,
-block_quote_, caution_, citation_, danger_, definition_, description_,
-entry_, error_, field_body_, footer_, footnote_, header_, hint_,
-important_, legend_, list_item_, note_, sidebar_, system_message_,
-tip_, topic_, warning_
+block_quote_, caution_, citation_, compound_, danger_, definition_,
+description_, entry_, error_, field_body_, footer_, footnote_,
+header_, hint_, important_, legend_, list_item_, note_, sidebar_,
+system_message_, tip_, topic_, warning_
 
 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
 indirectly employed in the content models of the document_ and
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index d9a76ce2e..0c0a55003 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -183,9 +183,10 @@ http://www.oasis-open.org/html/tm9901.htm).
 
 <!-- Optional elements may be generated by internal processing. -->
 <!ELEMENT document
-    ((title, subtitle?)?,
-    ((docinfo, decoration?, transition?) | decoration?),
-    %structure.model;)>
+    ( (title, subtitle?)?,
+      decoration?,
+      (docinfo, transition?)?,
+      %structure.model; )>
 <!ATTLIST document %basic.atts;>
 
 <!--
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index d0f6cd453..5af9987e7 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -464,11 +464,10 @@ For example, all the element names in this content model are links::
 
     .. parsed-literal::
 
-        ((title_,
-          subtitle_?)?,
-         docinfo_?,
+       ( (title_, subtitle_?)?,
          decoration_?,
-         `%structure.model;`_)
+         (docinfo_, transition_?)?,
+         `%structure.model;`_ )
 
 The following option is recognized:
 
@@ -958,6 +957,40 @@ The following options are recognized:
     default is 1.
 
 
+.. _header:
+.. _footer:
+
+Document Header & Footer
+========================
+
+:Directive Types: "header" and "footer"
+:Doctree Elements: decoration, header, footer
+:Directive Arguments: None.
+:Directive Options: None.
+:Directive Content: Interpreted as body elements.
+
+(New in Docutils 0.3.8)
+
+The "header" and "footer" directives create document decorations,
+useful for page navigation, notes, time/datestamp, etc.  For example::
+
+    .. header:: This space for rent.
+
+This will add a paragraph to the document header, which will appear at
+the top of the generated web page or at the top of every printed page.
+
+These directives may be used multiple times, cumulatively.  There is
+currently support for only one header and footer.
+
+In addition to the use of these directives to populate header and
+footer content, content may also be added automatically by the
+processing system.  For example, if certain runtime settings are
+enabled, the document footer is populated with processing information
+such as a datestamp, a link to `the Docutils website`_, etc.
+
+.. _the Docutils website: http://docutils.sourceforge.net
+
+
 ------------
  References
 ------------
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 73f7d27e3..03eddf814 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -87,10 +87,11 @@ highlights        Block quote with class="highlights"
 pull-quote        Block quote with class="pull-quote"
 compound          Compound paragraphs [0.3.6]
 table             Create a titled table [0.3.1]
-list-table        Create a table from a uniform two-level bullet list [0.3.8] 
+list-table        Create a table from a uniform two-level bullet list [0.3.8]
 csv-table         Create a table from CSV data (requires Python 2.3+) [0.3.4]
 contents          Generate a table of contents
 sectnum           Automatically number sections, subsections, etc.
+header, footer    Create document decorations [0.3.8]
 target-notes      Create an explicit footnote for each external target
 meta              HTML-specific metadata
 include           Read an external reST file as if it were inline
-- 
cgit v1.2.1


From 4c3442a63e090ec8a2414df48f2beadd80339b69 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 19:54:30 +0000
Subject: one done

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3187 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f4a77b94b..bbbeab92a 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1468,10 +1468,6 @@ when used in a document.
     either by running it at the command line with a ``--help`` option
     or through an exposed API.  [Suggestion for Optik.]
 
-  - _`parts.header` & _`parts.footer`: Add "header" and "footer"
-    directives to specify document-specific contents for header and
-    footer?
-
 
 Interpreted Text
 ----------------
-- 
cgit v1.2.1


From 9588a08dd3e57f2ffba9ee15441e32bd8c357f0b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Apr 2005 20:38:42 +0000
Subject: added some ideas

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3188 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index bbbeab92a..0cb24fdbe 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -476,6 +476,10 @@ General
 
 * Add support for _`plugins`.
 
+* Add support for document decorations other than headers & footers?
+  For example, top/bottom/side navigation bars for web pages.  Generic
+  decorations?
+
 
 Documentation
 =============
@@ -1161,6 +1165,10 @@ when used in a document.
     Add an option to include topics in the TOC?  Another for sidebars?
     See docutils-develop 2003-01-29.
 
+  - _`parts.header` & _`parts.footer`: Support multiple, named headers
+    & footers?  For example, separate headers & footers for odd, even,
+    and the first page of a document.
+
   - _`misc.include`:
 
     - "encoding" option?  Take default from runtime settings.  Use
-- 
cgit v1.2.1


From 7e297f36f3c1d3ebf5f26a60dcec7613efa63ba5 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Apr 2005 18:42:33 +0000
Subject: moved implementation description out of the docs into the code;
 whitespace

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 5af9987e7..5e07ba449 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -854,21 +854,15 @@ Table of Contents
 :Directive Options: Possible.
 :Directive Content: None.
 
-The "contents" directive inserts a table of contents (TOC) in two
-passes: initial parse and transform.  During the initial parse, a
-"pending" element is generated which acts as a placeholder, storing
-the TOC title and any options internally.  At a later stage in the
-processing, the "pending" element is replaced by a "topic" element, a
-title and the table of contents proper.
-
-The directive in its simplest form::
+The "contents" directive generates a table of contents (TOC).  Here's
+the directive in its simplest form::
 
     .. contents::
 
 Language-dependent boilerplate text will be used for the title.  The
 English default title text is "Contents".
 
-An explicit title, may be specified::
+An explicit title may be specified::
 
     .. contents:: Table of Contents
 
-- 
cgit v1.2.1


From be2f10a55253e7feb5047f15f505141bfe1d82e8 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Apr 2005 18:43:33 +0000
Subject: moved idea for existing sidebar directive into the correct position;
 updated idea with "?"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3194 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 0cb24fdbe..977c33270 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1091,7 +1091,7 @@ when used in a document.
 * Change directive functions to directive classes?  Superclass'
   ``__init__()`` could handle all the bookkeeping.
 
-* Implement options on existing directives:
+* Implement options or features on existing directives:
 
   - Add a "name" option to directives, to set an author-supplied
     identifier?
@@ -1211,7 +1211,7 @@ when used in a document.
 
     - Add support for inclusion by URL::
 
-          .. include:: 
+          .. include::
              :url: http://www.example.org/inclusion.txt
 
   - _`misc.raw`: add a "destination" option to the "raw" directive? ::
@@ -1223,7 +1223,10 @@ when used in a document.
 
     It needs thought & discussion though, to come up with a consistent
     set of destination labels and consistent behavior.
-  
+
+  - _`body.sidebar`: Allow internal section structure?  Adornment
+    styles would be independent of the main document.
+
 * 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
@@ -1394,10 +1397,6 @@ when used in a document.
 
     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.
-
   - _`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"
-- 
cgit v1.2.1


From 8876767b0b70633c00649879ce4404e2cdd3a431 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Apr 2005 19:44:19 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3196 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 977c33270..cdfb1a2af 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1163,7 +1163,9 @@ when used in a document.
     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.
+    The "topic" directive could have a "contents" option, or the
+    "contents" directive" could have an "include-topics" option.  See
+    docutils-develop 2003-01-29.
 
   - _`parts.header` & _`parts.footer`: Support multiple, named headers
     & footers?  For example, separate headers & footers for odd, even,
-- 
cgit v1.2.1


From 51a18532eab6031187426e26bb8f409b0fc25599 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Apr 2005 23:26:35 +0000
Subject: added "HTML SlideShow Writer" section

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3197 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 180 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index cdfb1a2af..5a4f23abe 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1751,6 +1751,186 @@ LaTeX writer
 * Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option.
 
 
+HTML SlideShow Writer
+=====================
+
+Add a Writer for presentations, derivative of the HTML Writer.  Given
+an input document containing one section per slide, the output would
+consist of a master document for the speaker, and a slide file (or set
+of filess, one (or more) for each slide).  Each slide would contain
+the slide text (large, stylesheet-controlled) and images, plus "next"
+and "previous" links in consistent places.  The speaker's master
+document would contain a small version of the slide text with
+speaker's notes interspersed.  The master document could use
+``target="whatever"`` to direct links to a separate window on a second
+monitor (e.g., a projector).
+
+Ideas:
+
+* Base the output on `S5 <http://www.meyerweb.com/eric/tools/s5/>`_.
+
+Below, "[S5?]" indicates that S5 already implements (or may implement)
+part of the feature.
+
+Features & issues:
+
+* [S5?]  Incremental slides, where each slide adds to the one before
+  (ticking off items in a list, delaying display of later items).  The
+  speaker's master document would list each transition in the TOC and
+  provide links in the content.
+
+  Have special support for this, or just copy slide text?  Could use
+  transitions to separate stages, or a special directive.  Problem
+  with transitions is that they can't be used everywhere -- not, for
+  example, within a list (see the example below).  A directive
+  (possible names: pause, delay, break, cut, continue, suspend, hold,
+  stay, stop) seems like a better solution.  Should the directive be
+  available in all contexts (and ineffectual in all but SlideShow
+  context), or added at runtime by the SlideShow Writer?
+
+  The directive could accept text content, which would be rendered
+  while paused but would disappear when the slide is continued (the
+  text could also be a link to the next slide).  In the speaker's
+  master document, the text "paused:" could appear, prefixed to the
+  directive text.
+
+* Speaker's notes -- how to intersperse?  Could use reST comments
+  (".."), but make them visible in the speaker's master document.  If
+  structure is necessary, we could use a "comment" directive (to avoid
+  nonsensical DTD changes, the "comment" directive could produce an
+  untitled topic element).
+
+  The speaker's notes would be separate from S5's handout content.
+
+* Speaker's master document could use frames for easy navigation: TOC
+  on the left, content on the right.
+
+  - It would be nice if clicking in the TOC frame simultaneously
+    linked to both the speaker's notes frame and to the slide window,
+    synchronizing both.  Needs JavaScript?
+
+  - TOC would have to be tightly formatted -- minimal indentation.
+
+  - TOC auto-generated, as in the PEP Reader.  (What if there already
+    is a "contents" directive in the document?)
+
+  - There could be another frame on the left (top-left or bottom-left)
+    containing a single "Next" link, always pointing to the next slide
+    (synchronized, of course).  Also "Previous" link?  FF/Rew go to
+    the beginning of the next/current parent section?  First/Last
+    also?  Tape-player-style buttons like ``|<<  <<  <  >  >>  >>|``?
+
+* [S5?]  Need to support templating of some kind, for uniform slide
+  layout.  Or build in support for limited features?  E.g., top/bottom
+  or left/right banners, images on each page, background color and/or
+  image, etc.
+
+* [S5?]  One layout for all slides, or allow some variation?
+
+* For nested sections, do we show the section's ancestry on each
+  slide?  Optional?  No -- leave the implementation to someone who
+  wants it.
+
+* [S5?]  Stylesheets for slides:
+
+  - Tweaked for different resolutions, 1024x768 etc.
+  - Some layout elements have fixed positions.
+  - Text must be quite large.
+  - Allow 10 lines of text per slide?  15?
+  - Title styles vary by level, but not so much?
+
+* [S5?]  Need a transform to number slides for output filenames?, and
+  for hyperlinks?
+
+* Directive to begin a new, untitled (blank) slide?
+
+* Directive to begin a new slide, continuation, using the same title
+  as the previous slide?
+
+Here's an example that I was hoping to show at PyCon DC 2005::
+
+    ========================
+     The Docutils SlideShow
+    ========================
+
+    Welcome To The Docutils SlideShow!
+    ==================================
+
+    .. pause::
+
+    David Goodger
+
+    goodger@python.org
+
+    http://python.net/~goodger
+
+    .. (introduce yourself)
+
+       Hi, I'm David Goodger from Montreal, Canada.
+
+       I've been working on Docutils since 2000.
+       Time flies!
+
+    .. pause::
+
+    Docutils
+
+    http://docutils.sourceforge.net
+
+    .. I also volunteer as a Python Enhancement Proposal (or PEP)
+       editor.
+
+    .. SlideShow is a new feature of Docutils.  This presentation was
+       written using the Docutils SlideShow system.  The slides you
+       are seeing are HTML, rendered by a standard Mozilla Firefox
+       browser.
+
+
+    The Docutils SlideShow System
+    =============================
+
+    .. The Docutils SlideShow System provides
+
+    Easy and open presentations.
+
+
+    Features
+    ========
+
+    * reStructuredText-based input files.
+
+      .. reStructuredText is a what-you-see-is-what-you-get
+         plaintext format.  Easy to read & write, non-proprietary,
+         editable in your favourite text editor.
+
+      .. Parsers for other markup languages can be added to Docutils.
+         In the future, I hope some are.
+
+      .. pause:: ...
+
+    * Stylesheet-driven HTML output.
+
+      .. The format of all elements of the output slides are
+         controlled by CSS (cascading stylesheets).
+
+      .. pause:: ...
+
+    * Works with any modern browser.
+
+      .. that supports CSS, frames, and JavaScript.
+         Tested with Mozilla Firefox.
+
+      .. pause:: ...
+
+    * Works on any OS.
+
+
+    Etc.
+    ====
+
+    That's as far as I got, but you get the idea...
+
+
 Front-End Tools
 ===============
 
-- 
cgit v1.2.1


From 914a483a4eb5e5ad9bc36a56b284f2c2336f9063 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Apr 2005 23:28:53 +0000
Subject: added link to Chris Liechti's work

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3198 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5a4f23abe..b7e43a710 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1769,6 +1769,9 @@ Ideas:
 
 * Base the output on `S5 <http://www.meyerweb.com/eric/tools/s5/>`_.
 
+  Chris Liechti has `integrated S5 with the HTML writer
+  <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__.
+
 Below, "[S5?]" indicates that S5 already implements (or may implement)
 part of the feature.
 
-- 
cgit v1.2.1


From a65d49465f32f45cc8152ccfdd0ee4d26c398353 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 9 Apr 2005 01:32:29 +0000
Subject: allow topics within sidebars; no topics within body elements

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3199 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt        |  9 +++++----
 docs/ref/docutils.dtd       |  2 +-
 docs/ref/rst/directives.txt | 10 +++++++---
 3 files changed, 13 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 912789239..b5458017b 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -3550,7 +3550,7 @@ Details
 
 :Children:
     ``sidebar`` elements begin with a title_ and an optional subtitle_
-    and contain `body elements`_.
+    and contain `body elements`_ and topic_ elements.
 
 :Analogues:
     ``sidebar`` is analogous to the DocBook "sidebar" element.
@@ -3568,7 +3568,7 @@ Content Model
 .. parsed-literal::
 
     (title_, subtitle_?,
-     (`%body.elements;`_)+)
+     (`%body.elements;`_ | topic_)+)
 
 :Attributes:
     The ``sidebar`` element contains only the `common attributes`_:
@@ -3985,7 +3985,7 @@ The ``topic`` element is a nonrecursive section_-like construct which
 may occur at the top level of a section_ wherever a body element
 (list, table, etc.) is allowed.  In other words, ``topic`` elements
 cannot nest inside body elements, so you can't have a ``topic`` inside
-a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_).
+a ``table`` or a ``list``, or inside another ``topic``.
 
 
 Details
@@ -3995,7 +3995,8 @@ Details
     `Structural Elements`_
 
 :Parents:
-    The following elements may contain ``topic``: document_, section_
+    The following elements may contain ``topic``: document_, section_,
+    sidebar_
 
 :Children:
     ``topic`` elements begin with a title_ and may contain `body
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 0c0a55003..357703f04 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -279,7 +279,7 @@ Eventual replacement for docinfo? -->
 <!ELEMENT topic (title?, (%body.elements;)+)>
 <!ATTLIST topic %basic.atts;>
 
-<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)>
+<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)>
 <!ATTLIST sidebar %basic.atts;>
 
 <!ELEMENT transition EMPTY>
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 5e07ba449..859d32487 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -331,7 +331,7 @@ A topic is like a block quote with a title, or a self-contained
 section with no subsections.  Use the "topic" directive to indicate a
 self-contained idea that is separate from the flow of the document.
 Topics may occur anywhere a section or transition may occur.  Body
-elements (including topics) may not contain nested topics.
+elements and topics may not contain nested topics.
 
 The directive's sole argument is interpreted as the topic title; the
 next line must be blank.  All subsequent lines make up the topic body,
@@ -854,8 +854,12 @@ Table of Contents
 :Directive Options: Possible.
 :Directive Content: None.
 
-The "contents" directive generates a table of contents (TOC).  Here's
-the directive in its simplest form::
+The "contents" directive generates a table of contents (TOC) in a
+topic_.  Topics, and therefore tables of contents, may occur anywhere
+a section or transition may occur.  Body elements and topics may not
+contain tables of contents.
+
+Here's the directive in its simplest form::
 
     .. contents::
 
-- 
cgit v1.2.1


From 0d09d08b1b3bb856aaff320d99fc93faa3d50fa4 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 9 Apr 2005 21:13:28 +0000
Subject: added note about misuse of header and footer directives

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3200 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 859d32487..737cbe97a 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -980,6 +980,20 @@ the top of the generated web page or at the top of every printed page.
 These directives may be used multiple times, cumulatively.  There is
 currently support for only one header and footer.
 
+.. note::
+
+   While it is possible to use the "header" and "footer" directives to
+   create navigational elements for web pages, you should be aware
+   that Docutils is meant to be used for *document* processing, and
+   that a navigation bar is not typically part of a document.
+
+   Thus, you may soon find Docutils' abilities to be insufficient for
+   these purposes.  At that time, you should consider using a
+   templating system (like ht2html_) rather than the "header" and
+   "footer" directives.
+
+   .. _ht2html: http://ht2html.sourceforge.net/
+
 In addition to the use of these directives to populate header and
 footer content, content may also be added automatically by the
 processing system.  For example, if certain runtime settings are
-- 
cgit v1.2.1


From 2dfdc12dbaa20c84a7365bfe37686b4e33ebf4df Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 10 Apr 2005 00:08:40 +0000
Subject: leet typographical tweak

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3202 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b7e43a710..c61f2b14d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1767,11 +1767,14 @@ monitor (e.g., a projector).
 
 Ideas:
 
-* Base the output on `S5 <http://www.meyerweb.com/eric/tools/s5/>`_.
+* Base the output on |S5|_.
 
   Chris Liechti has `integrated S5 with the HTML writer
   <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__.
 
+  .. |S5| replace:: S\ :sup:`5`
+  .. _S5: http://www.meyerweb.com/eric/tools/s5/
+
 Below, "[S5?]" indicates that S5 already implements (or may implement)
 part of the feature.
 
-- 
cgit v1.2.1


From 900f0119a0c17fef3d368e56c971834982e85e0a Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 10 Apr 2005 00:09:24 +0000
Subject: another tweak

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3203 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c61f2b14d..ea28b506d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1775,8 +1775,8 @@ Ideas:
   .. |S5| replace:: S\ :sup:`5`
   .. _S5: http://www.meyerweb.com/eric/tools/s5/
 
-Below, "[S5?]" indicates that S5 already implements (or may implement)
-part of the feature.
+Below, "[S5?]" indicates that |S5| already implements (or may
+implement) part of the feature.
 
 Features & issues:
 
-- 
cgit v1.2.1


From aaa2e23c448f54a7cf9d50d600481c06bde8829c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 11 Apr 2005 23:15:21 +0000
Subject: updated slideshow ideas

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3205 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 85 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 57 insertions(+), 28 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index ea28b506d..b08b82477 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1767,7 +1767,9 @@ monitor (e.g., a projector).
 
 Ideas:
 
-* Base the output on |S5|_.
+* Base the output on |S5|_.  I discovered |S5| a few weeks before it
+  appeared on Slashdot, after writing most of this section.  It turns
+  out that |S5| does most of what I wanted.
 
   Chris Liechti has `integrated S5 with the HTML writer
   <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__.
@@ -1775,30 +1777,47 @@ Ideas:
   .. |S5| replace:: S\ :sup:`5`
   .. _S5: http://www.meyerweb.com/eric/tools/s5/
 
-Below, "[S5?]" indicates that |S5| already implements (or may
-implement) part of the feature.
+Below, "[S5]" indicates that |S5| already implements the feature or
+may implement all or part of the feature.  "[S5 1.1]" indicates that
+|S5| version 1.1 implements the feature (a preview of the 1.1 beta is
+available in the `S5 testbed`_).
+
+.. _S5 testbed: http://meyerweb.com/eric/tools/s5/testbed/
 
 Features & issues:
 
-* [S5?]  Incremental slides, where each slide adds to the one before
+* [S5 1.1] Incremental slides, where each slide adds to the one before
   (ticking off items in a list, delaying display of later items).  The
   speaker's master document would list each transition in the TOC and
   provide links in the content.
 
-  Have special support for this, or just copy slide text?  Could use
-  transitions to separate stages, or a special directive.  Problem
-  with transitions is that they can't be used everywhere -- not, for
-  example, within a list (see the example below).  A directive
-  (possible names: pause, delay, break, cut, continue, suspend, hold,
-  stay, stop) seems like a better solution.  Should the directive be
-  available in all contexts (and ineffectual in all but SlideShow
-  context), or added at runtime by the SlideShow Writer?
-
-  The directive could accept text content, which would be rendered
-  while paused but would disappear when the slide is continued (the
-  text could also be a link to the next slide).  In the speaker's
-  master document, the text "paused:" could appear, prefixed to the
-  directive text.
+  * Use transitions to separate stages.  Problem with transitions is
+    that they can't be used everywhere -- not, for example, within a
+    list (see the example below).
+
+  * Use a special directive to separate stages.  Possible names:
+    pause, delay, break, cut, continue, suspend, hold, stay, stop.
+    Should the directive be available in all contexts (and ineffectual
+    in all but SlideShow context), or added at runtime by the
+    SlideShow Writer?
+
+    The directive could accept text content, which would be rendered
+    while paused but would disappear when the slide is continued (the
+    text could also be a link to the next slide).  In the speaker's
+    master document, the text "paused:" could appear, prefixed to the
+    directive text.
+
+  * Use a special directive or class to declare incremental content.
+    This works best with the S5 ideas.  For example::
+
+        Slide Title
+        ===========
+
+        .. incremental::
+
+           * item one
+           * item two
+           * item three
 
 * Speaker's notes -- how to intersperse?  Could use reST comments
   (".."), but make them visible in the speaker's master document.  If
@@ -1806,10 +1825,11 @@ Features & issues:
   nonsensical DTD changes, the "comment" directive could produce an
   untitled topic element).
 
-  The speaker's notes would be separate from S5's handout content.
+  The speaker's notes could (should?) be separate from S5's handout
+  content.
 
-* Speaker's master document could use frames for easy navigation: TOC
-  on the left, content on the right.
+* The speaker's master document could use frames for easy navigation:
+  TOC on the left, content on the right.
 
   - It would be nice if clicking in the TOC frame simultaneously
     linked to both the speaker's notes frame and to the slide window,
@@ -1826,18 +1846,27 @@ Features & issues:
     the beginning of the next/current parent section?  First/Last
     also?  Tape-player-style buttons like ``|<<  <<  <  >  >>  >>|``?
 
-* [S5?]  Need to support templating of some kind, for uniform slide
-  layout.  Or build in support for limited features?  E.g., top/bottom
-  or left/right banners, images on each page, background color and/or
+* [S5]  Need to support templating of some kind, for uniform slide
+  layout.  S5 handles this via CSS.
+
+  Build in support for limited features?  E.g., top/bottom or
+  left/right banners, images on each page, background color and/or
   image, etc.
 
 * [S5?]  One layout for all slides, or allow some variation?
 
+      While S5 seems to support only one style per HTML file, it's
+      pretty easy to split a presentation in different files and
+      insert a hyperlink to the last slide of the first part and load
+      the second part by a click on it.
+
+      -- Chris Liechti
+
 * For nested sections, do we show the section's ancestry on each
   slide?  Optional?  No -- leave the implementation to someone who
   wants it.
 
-* [S5?]  Stylesheets for slides:
+* [S5]  Stylesheets for slides:
 
   - Tweaked for different resolutions, 1024x768 etc.
   - Some layout elements have fixed positions.
@@ -1845,13 +1874,13 @@ Features & issues:
   - Allow 10 lines of text per slide?  15?
   - Title styles vary by level, but not so much?
 
-* [S5?]  Need a transform to number slides for output filenames?, and
-  for hyperlinks?
+* [not required with S5.]  Need a transform to number slides for
+  output filenames?, and for hyperlinks?
 
 * Directive to begin a new, untitled (blank) slide?
 
 * Directive to begin a new slide, continuation, using the same title
-  as the previous slide?
+  as the previous slide?  (Unnecessary?)
 
 Here's an example that I was hoping to show at PyCon DC 2005::
 
-- 
cgit v1.2.1


From 2969f919b08ef2becf68428aeca78c695225c695 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 12 Apr 2005 10:35:12 +0000
Subject: added my objections to more document decorations

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3208 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b08b82477..f8cb68d5e 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -480,6 +480,9 @@ General
   For example, top/bottom/side navigation bars for web pages.  Generic
   decorations?
 
+  Seems like a bad idea as long as it isn't independent from the ouput
+  format (for example, navigation bars are only useful for web pages).
+
 
 Documentation
 =============
-- 
cgit v1.2.1


From e99a08422249d679f7f4ba9d943214290c7fba32 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 12 Apr 2005 10:35:43 +0000
Subject: removed already implemented to-do list entry

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3209 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f8cb68d5e..5b14fb77c 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -470,10 +470,6 @@ General
   directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
   *not* be converted to HTML).
 
-* stylesheet & stylesheet_path settings: either one should set the
-  other one to ``None`` as a side effect.  See discussion on
-  docutils-develop from 2004-07-03.
-
 * Add support for _`plugins`.
 
 * Add support for document decorations other than headers & footers?
-- 
cgit v1.2.1


From ad9b5e34aa316c7883797ec4a4f0efec2c6b5c90 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 12 Apr 2005 10:43:33 +0000
Subject: added my ideas about slide shows

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3210 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5b14fb77c..5554d5132 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1798,7 +1798,10 @@ Features & issues:
     pause, delay, break, cut, continue, suspend, hold, stay, stop.
     Should the directive be available in all contexts (and ineffectual
     in all but SlideShow context), or added at runtime by the
-    SlideShow Writer?
+    SlideShow Writer?  Probably such a "pause" directive should only
+    be available for slide shows; slide shows are too much of a
+    special case to justify adding a directive (and node?) to the
+    core.
 
     The directive could accept text content, which would be rendered
     while paused but would disappear when the slide is continued (the
@@ -1818,6 +1821,8 @@ Features & issues:
            * item two
            * item three
 
+    Add an option to make all bullet lists implicitly incremental?
+
 * Speaker's notes -- how to intersperse?  Could use reST comments
   (".."), but make them visible in the speaker's master document.  If
   structure is necessary, we could use a "comment" directive (to avoid
-- 
cgit v1.2.1


From 80f50583a15744360806e435c9dabd965f6cac8c Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 12 Apr 2005 17:12:46 +0000
Subject: updated "Web Site" document to BerliOS and Subversion; cron job is
 set up again

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3212 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/website.txt | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/website.txt b/docs/dev/website.txt
index 0fe2aaf58..e54acb802 100644
--- a/docs/dev/website.txt
+++ b/docs/dev/website.txt
@@ -9,30 +9,29 @@
 :Copyright: This document has been placed in the public domain.
 
 The Docutils web site, <http://docutils.sourceforge.net/>, is
-maintained by the ``docutils-update`` script.  The script used to run
-as a cron job, but since mid-2004, cron isn't working on
-SourceForge.net, so you will have to run it manually.  It 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 ``<username>@shell.sourceforge.net`` and ::
-
+maintained automatically by the ``docutils-update`` script, run as an
+hourly cron job on shell.berlios.de (by user "felixwiemann").  The
+script will process any .txt file which is newer than the
+corresponding .html file in the project's web directory on
+shell.berlios.de (``/home/groups/docutils/htdocs/aux/htdocs/``) and
+upload the changes to the web site at SourceForge.  For a new .txt
+file, just SSH to ``<username>@shell.berlios.de`` and ::
+
+    cd /home/groups/docutils/htdocs/aux/htdocs/
     touch filename.html
     chmod g+w filename.html
     sleep 1
     touch filename.txt
-    /home/groups/d/do/docutils/snapshots/sandbox/davidg/infrastructure/docutils-update -p
 
-The ``docutils-update`` script will retrieve the most current version
-of the .txt file from CVS and generate the .html file.  Thereafter
-whenever the .txt file is modified (checked in to CVS), the .html will
-be regenerated when ``docutils-update`` is run.
+The script will take care of the rest within an hour.  Thereafter
+whenever the .txt file is modified (checked in to SVN), the .html will
+be regenerated automatically.
 
-After adding directories to CVS, allow the script to run once to
+After adding directories to SVN, 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
+The docutils-update__ script is located as
 ``sandbox/davidg/infrastructure/docutils-update``.
 
 __ http://docutils.sf.net/sandbox/davidg/infrastructure/docutils-update
-- 
cgit v1.2.1


From 8524aa921c1e97daf41b2d263f15fe38039bc763 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Apr 2005 20:00:30 +0000
Subject: added a syntax idea for parameterized interpreted text

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3214 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 50b13392b..51930be3a 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -2764,6 +2764,18 @@ text, analogous to function calls.  Ideas:
    Do angle brackets connote URLs too much for this to be acceptable?
    How about the "tag" connotation -- does it save them or doom them?
 
+3. `Nested inline markup`_ could prove useful here::
+
+       `CSS :def:`Cascading Style Sheets``:acronym: is used for HTML,
+       and `CSS :def:`Content Scrambling System``:acronym: is used for
+       DVDs.
+
+   Inline markup roles could even define the default roles of nested
+   inline markup, allowing this cleaner syntax::
+
+       `CSS `Cascading Style Sheets``:acronym: is used for HTML, and
+       `CSS `Content Scrambling System``:acronym: is used for DVDs.
+
 Does this push inline markup too far?  Readability becomes a serious
 issue.  Substitutions may provide a better alternative (at the expense
 of verbosity and duplication) by pulling the details out of the text
-- 
cgit v1.2.1


From ff6a81eb833aa1f58fa481a6fe3992575a7736e9 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Apr 2005 20:01:12 +0000
Subject: updated adaptable file extensions idea

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3215 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5554d5132..4c064e1aa 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -704,21 +704,35 @@ __ rst/alternatives.html#or-not-to-do
   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
+  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"]?)
+  What is to be done for output formats that don't *have* hyperlinks?
+  For example, LaTeX targeted at print.  Hyperlinks may be "called
+  out", as footnotes with explicit URLs.
 
-  This may not be just a parser issue though; it may need framework
-  support.
+  But then there's also LaTeX targeted at PDFs, which *can* have
+  links.  Perhaps a runtime setting for "*" could explicitly provide
+  the extension, defaulting to the output file's extension.
 
-  Mailing list thread: `Images in both HTML and LaTeX`__
+  Should the system check for existing files?  No, not practical.
+
+  Handle documents only, or objects (images, etc.) also?
+
+  If this handles images also, how to differentiate between document
+  and image links?  Element context (within "image")?  Which image
+  extension to use for which document format?  Again, a runtime
+  setting would suffice.
+
+  This may not be just a parser issue; it may need framework support.
+
+  Mailing list threads: `Images in both HTML and LaTeX`__,
+  `more-universal links?`__
 
   __ http://thread.gmane.org/gmane.text.docutils.user/1239
+  __ http://thread.gmane.org/gmane.text.docutils.user/1915
 
 * Implement the header row separator modification to table.el.  (Wrote
   to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
-- 
cgit v1.2.1


From 1ba990451695b1544ab0535c84fdcd92323174ad Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Apr 2005 20:04:26 +0000
Subject: removed completed item; removed outdated "@" markers

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3216 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 4c064e1aa..40510eddc 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -142,9 +142,9 @@ General
   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 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.)?
@@ -496,8 +496,8 @@ Developer Docs
 
 * Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
 
-* @@@ Improve the internal module documentation (docstrings in the
-  code).  Specific deficiencies listed below.
+* 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).
@@ -743,11 +743,11 @@ __ rst/alternatives.html#or-not-to-do
   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?)
+* 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
+* 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
@@ -2031,9 +2031,6 @@ Front-End Tools
 
 * 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?
 
-- 
cgit v1.2.1


From bd559044426b3f80dd1e7cc9b2d3a25c61bb952f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 21 Apr 2005 14:52:41 +0000
Subject: "image" directive: added checks for valid values of "align" option,
 depending on context.  "figure" directive: added specialized "align" option
 and attribute on "figure" element.  Added HTML support for ``align``
 attribute on ``figure`` elements.  Updated docs & tests.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3231 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd       | 8 ++++++++
 docs/ref/rst/directives.txt | 5 +++++
 2 files changed, 13 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 357703f04..f3a7d37ca 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -97,6 +97,12 @@ resolve to either an internal or external reference.
 <!ENTITY % fixedspace.att
   " xml:space (default | preserve) #FIXED 'preserve' ">
 
+<!ENTITY % align-h.att
+  " align     (left | center | right) #IMPLIED ">
+
+<!ENTITY % align-hv.att
+  " align     (top | middle | bottom | left | center | right) #IMPLIED ">
+
 
 <!-- Element OR-Lists
 ============================================================= -->
@@ -465,12 +471,14 @@ or " ") or the text between option arguments (typically either "," or
 <!ELEMENT figure (image, ((caption, legend?) | legend)) >
 <!ATTLIST figure
     %basic.atts;
+    %align-h.att;
     width     %number;  #IMPLIED>
 
 <!-- Also an inline element. -->
 <!ELEMENT image EMPTY>
 <!ATTLIST image
     %basic.atts;
+    %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
     height    %number;  #IMPLIED
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 737cbe97a..f888ef556 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -309,6 +309,11 @@ options are recognized:
     Set a "class" attribute value on the figure element.  See the
     class_ directive below.
 
+``align`` : "left", "center", or "right"
+    The horizontal alignment of the figure, allowing the image to
+    float and have the text flow around it.  The specific behavior
+    depends upon the browser or rendering software used.
+
 .. [#PIL] `Python Imaging Library`_.
 
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
-- 
cgit v1.2.1


From df9f154b022a494b353fb6df0bbc04dc374d9ae5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 21 Apr 2005 19:02:28 +0000
Subject: added note about using "compound" as a block-level container

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3238 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index f888ef556..130f0d154 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -605,6 +605,16 @@ example::
 In the example above, a literal block is "embedded" within a sentence
 that begins in one physical paragraph and ends in another.
 
+.. note::
+
+   The "compound" directive is *not* a generic block-level container
+   like HTML's ``<div>`` element.  Do not use it only to group a
+   sequence of elements, or you may get unexpected results.
+
+   If you happen to need a generic block-level container, please
+   describe your use-case in an email to
+   docutils-users@lists.sourceforge.net.
+
 Compound paragraphs are typically rendered as multiple distinct text
 blocks, with the possibility of variations to emphasize their logical
 unity:
-- 
cgit v1.2.1


From 5582f0c0893cae4661d8e16449e69e75a49bbe04 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 21 Apr 2005 21:59:05 +0000
Subject: added link to Felix's objections of adaptable file extension syntax

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3241 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 40510eddc..79d124a21 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -728,10 +728,11 @@ __ rst/alternatives.html#or-not-to-do
 
   This may not be just a parser issue; it may need framework support.
 
-  Mailing list threads: `Images in both HTML and LaTeX`__,
-  `more-universal links?`__
+  Mailing list threads: `Images in both HTML and LaTeX`__ (especially
+  `this summary of Felix's objections`__), `more-universal links?`__
 
   __ http://thread.gmane.org/gmane.text.docutils.user/1239
+  __ http://article.gmane.org/gmane.text.docutils.user/1278
   __ http://thread.gmane.org/gmane.text.docutils.user/1915
 
 * Implement the header row separator modification to table.el.  (Wrote
-- 
cgit v1.2.1


From 18bd99c8f3343501694e159080192f47eb16c34c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 22 Apr 2005 23:57:18 +0000
Subject: Added "cloak_email_addresses" setting & support; updated test & docs.
  Thanks to Barry Warsaw & Ned Batchelder for the idea and initial patch.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3243 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 7e93626a1..ebff78289 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -527,6 +527,19 @@ attribution
 
     __ `attribution [latex2e writer]`_
 
+_`cloak_email_addresses`
+    Scramble email addresses to confuse harvesters.  In the visible
+    text of an email address, the "@" will be replaced by "at", and
+    all periods (".") will be replaced by "dot", with spaces added.
+    In the reference URI, the address will be replaced by %-escapes.
+    For example, "abc@example.org" will be output as::
+
+        <a class="reference"
+         href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
+        abc at example dot org</a>
+
+    Default: don't cloak (None).  Option: ``--cloak-email``.
+
 _`compact_lists`
     Remove extra vertical whitespace between items of bullet lists and
     enumerated lists, when list items are "simple" (i.e., all items
-- 
cgit v1.2.1


From 5cc9857610e2efed8396e58ded7509fc3288edf0 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 23 Apr 2005 19:23:00 +0000
Subject: added link

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3245 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 79d124a21..4e24efe4e 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -76,7 +76,8 @@ for inclusion in the Python standard library.
   of the resulting documents is more easily customizable.  (Similar to
   what you wrote about a new HTML Writer.)
 
-* Suitability for Python module documentation.
+* Suitability for `Python module documentation
+  <http://docutils.sf.net/sandbox/README.html#documenting-python>`_.
 
 
 General
-- 
cgit v1.2.1


From 873ff59a77fea8390df56adc5aec025a3d766584 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 24 Apr 2005 03:01:33 +0000
Subject: updated footer descriptions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3248 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index b5458017b..2ae37b9f5 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -1233,9 +1233,7 @@ context.
 
 The ``decoration`` element is a container for header_ and footer_
 elements and potential future extensions.  These elements are used for
-page navigation, notes, time/datestamp, etc.  Currently only the
-footer_ element is implemented, populated with processing information
-(datestamp, a link to Docutils_, etc.).
+notes, time/datestamp, processing information, etc.
 
 
 Details
@@ -2242,8 +2240,9 @@ See the examples for the field_list_ and docinfo_ elements.
 
 The ``footer`` element is a container element whose contents are meant
 to appear at the bottom of a web page, or repeated at the bottom of
-every printed page.  Currently the ``footer`` element may contain
-processing information (datestamp, a link to Docutils_, etc.).
+every printed page.  The ``footer`` element may contain processing
+information (datestamp, a link to Docutils_, etc.) as well as custom
+content.
 
 
 Details
-- 
cgit v1.2.1


From 09c84f6a848fd546d06e4b8f80094c02c06a0122 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 24 Apr 2005 15:30:03 +0000
Subject: corrected option

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3250 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index ebff78289..e3e052aaf 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -538,7 +538,7 @@ _`cloak_email_addresses`
          href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
         abc at example dot org</a>
 
-    Default: don't cloak (None).  Option: ``--cloak-email``.
+    Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 
 _`compact_lists`
     Remove extra vertical whitespace between items of bullet lists and
-- 
cgit v1.2.1


From 03da26f3c9d0d99ea4afd99cf5330fe307ce3bb3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 24 Apr 2005 23:21:48 +0000
Subject: Added ``html_body``, ``html_title``, & ``html_subtitle`` to HTML
 writer parts dictionary exposed by ``docutils.core.publish_parts``; updated
 tests.  Added "``publish_parts`` Details" section to docs/api/publish.txt.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3251 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 83 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index b018bbe90..5d793f003 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -35,9 +35,9 @@ handles everything else.  There are five convenience functions in the
   dictionary of document parts.  Dictionary keys are the names of
   parts, and values are Unicode strings; encoding is up to the client.
   Useful when only portions of the processed document are desired.
-  Currently only implemented for the HTML Writer.
+  See `publish_parts Details`_ below.
 
-  There are examples in the `docutils/examples.py`_ module.
+  There are usage examples in the `docutils/examples.py`_ module.
 
 * ``publish_programmatically``: for custom programmatic use.  This
   function implements common code and is used by ``publish_file``,
@@ -74,7 +74,82 @@ Encodings
 The default output encoding of Docutils is UTF-8.  If you have any
 non-ASCII in your input text, you may have to do a bit more setup.
 Docutils may introduce some non-ASCII text if you use
-symbol-footnotes_.
+`auto-symbol footnotes`_ or the `"contents" directive`_.
 
-.. _symbol-footnotes:
+.. _auto-symbol footnotes:
    ../ref/rst/restructuredtext.html#auto-symbol-footnotes
+.. _"contents" directive:
+   ../ref/rst/directives.html#table-of-contents
+
+
+``publish_parts`` Details
+=========================
+
+The ``docutils.core.publish_parts`` convenience function returns a
+dictionary of document parts.  Dictionary keys are the names of parts,
+and values are Unicode strings.
+
+Each Writer component may publish a different set of document parts,
+described below.  Currently only the HTML Writer implements more than
+the "whole" part.
+
+
+Parts Provided By All Writers
+-----------------------------
+
+whole
+    ``parts['whole']`` contains the entire formatted document.
+
+
+Parts Provided By the HTML Writer
+---------------------------------
+
+body
+    ``parts['body']`` is equivalent to ``parts['fragment']``.
+
+docinfo
+    ``parts['docinfo']`` contains the document bibliographic data.
+
+footer
+    ``parts['footer']`` contains the document footer content, meant to
+    appear at the bottom of a web page, or repeated at the bottom of
+    every printed page.
+
+fragment
+    ``parts['fragment']`` contains the document body (*not* the HTML
+    ``<body>``).  In other words, it contains the entire document,
+    less the document title, subtitle, docinfo, header, and footer.
+
+header
+    ``parts['header']`` contains the document header content, meant to
+    appear at the top of a web page, or repeated at the top of every
+    printed page.
+
+html_body
+    ``parts['html_body']`` contains the HTML ``<body>`` content, less
+    the ``<body>`` and ``</body>`` tags themselves.
+
+html_subtitle
+    ``parts['html_subtitle']`` contains the document subtitle,
+    including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
+    tags.
+
+html_title
+    ``parts['html_title']`` contains the document title, including the
+    enclosing ``<h1 class="title">`` & ``</h1>`` tags.
+
+meta
+    ``parts['meta']`` contains all ``<meta ... />`` tags.
+
+stylesheet
+    ``parts['stylesheet']`` contains the document stylesheet link.
+
+subtitle
+    ``parts['subtitle']`` contains the document subtitle text and any
+    inline markup.  It does not include the enclosing ``<h2>`` &
+    ``</h2>`` tags.
+
+title
+    ``parts['title']`` contains the document title text and any inline
+    markup.  It does not include the enclosing ``<h1>`` & ``</h1>``
+    tags.
-- 
cgit v1.2.1


From 93102bb86e422b933a96346a97e8adeed8d7e83f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 25 Apr 2005 19:24:28 +0000
Subject: expanded ``node[x]`` entry with link to thread

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3254 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 4e24efe4e..cba560dca 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -445,10 +445,11 @@ General
 
   .. _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]``?
+* Simplify the docutils.nodes.Element implementation?  ``node[x]`` is
+  convenient but can be considered ambiguous (different results if
+  ``x`` is a string or an integer).  Replace with ``node[int]`` and
+  ``node.attributes[string]``?  See
+  <http://thread.gmane.org/gmane.text.docutils.devel/2844>.
 
 * Add file-specific settings support to config files, like::
 
-- 
cgit v1.2.1


From df86c29341bb830c87ee468323c1e3afa9d32a03 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 26 Apr 2005 03:57:00 +0000
Subject: Added ``html_prolog`` & ``html_head`` to HTML writer parts dictionary
 exposed by ``docutils.core.publish_parts``; updated tests & docs.  At the
 request of Marcelo Huerta.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3257 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 5d793f003..55883f1ae 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -129,6 +129,15 @@ html_body
     ``parts['html_body']`` contains the HTML ``<body>`` content, less
     the ``<body>`` and ``</body>`` tags themselves.
 
+html_head
+    ``parts['html_head']`` contains the HTML ``<head>`` content, less
+    the stylesheet link and the ``<head>`` and ``</head>`` tags
+    themselves.
+
+html_prolog
+    ``parts['html_prolog]`` contains the XML declaration and the
+    doctype declaration.
+
 html_subtitle
     ``parts['html_subtitle']`` contains the document subtitle,
     including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
-- 
cgit v1.2.1


From ce727c88d8d89f9f86275c0d3fca3ae2be392cec Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 27 Apr 2005 21:04:03 +0000
Subject: fixed encoding/charset values in "html_prolog" & "html_head" parts,
 which should not have been interpolated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 55883f1ae..66aaa06fb 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -132,11 +132,21 @@ html_body
 html_head
     ``parts['html_head']`` contains the HTML ``<head>`` content, less
     the stylesheet link and the ``<head>`` and ``</head>`` tags
-    themselves.
+    themselves.  The "Content-Type" meta tag's "charset" value is left
+    unresolved, as "%s"::
+
+        <meta http-equiv="Content-Type" content="text/html; charset=%s" />
+
+    The interpolation should be done by client code.
 
 html_prolog
     ``parts['html_prolog]`` contains the XML declaration and the
-    doctype declaration.
+    doctype declaration.  The XML declaration's "encoding" attribute's
+    value is left unresolved, as "%s"::
+
+        <?xml version="1.0" encoding="%s" ?>
+
+    The interpolation should be done by client code.
 
 html_subtitle
     ``parts['html_subtitle']`` contains the document subtitle,
-- 
cgit v1.2.1


From df05185ff0a8c586230c827b46a1cf43544c65fa Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 2 May 2005 03:59:11 +0000
Subject: added ``line`` element; corrected ``line_block`` details

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3282 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt | 163 +++++++++++++++++++++++++++++++++++----------------
 1 file changed, 114 insertions(+), 49 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 2ae37b9f5..f432ed1f6 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -161,9 +161,8 @@ Simple body elements are empty or directly contain text data.  Those
 that contain text data may also contain inline elements.  Such
 elements therefore have a "mixed content model".
 
-Category members: comment_, doctest_block_, image_, line_block_,
-literal_block_, paragraph_, pending_, raw_, rubric_,
-substitution_definition_, target_
+Category members: comment_, doctest_block_, image_, literal_block_,
+paragraph_, pending_, raw_, rubric_, substitution_definition_, target_
 
 
 Compound Body Elements
@@ -175,8 +174,8 @@ and further body elements.  They do not directly contain text data.
 Category members: admonition_, attention_, block_quote_, bullet_list_,
 caution_, citation_, compound_, danger_, definition_list_,
 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
-important_, note_, option_list_, system_message_, table_, tip_,
-warning_
+important_, line_block, note_, option_list_, system_message_, table_,
+tip_, warning_
 
 
 Body Subelements
@@ -190,7 +189,8 @@ always occur within specific parent elements, never at the body
 element level (beside paragraphs, etc.).
 
 Category members (simple): attribution_, caption_, classifier_,
-colspec_, field_name_, label_, option_argument_, option_string_, term_
+colspec_, field_name_, label_, line_, option_argument_,
+option_string_, term_
 
 Category members (compound): definition_, definition_list_item_,
 description_, entry_, field_, field_body_, legend_, list_item_,
@@ -305,7 +305,8 @@ its writing.
 The ``address`` element holds the surface mailing address information
 for the author (individual or group) of the document, or a third-party
 contact address.  Its structure is identical to that of the
-line_block_ element: whitespace is significant, especially newlines.
+literal_block_ element: whitespace is significant, especially
+newlines.
 
 
 Details
@@ -324,9 +325,9 @@ Details
     ``address`` is analogous to the DocBook "address" element.
 
 :Processing:
-    As with the line_block_ element, newlines and other whitespace is
-    significant and must be preserved.  However, a monospaced typeface
-    need not be used.
+    As with the literal_block_ element, newlines and other whitespace
+    is significant and must be preserved.  However, a monospaced
+    typeface need not be used.
 
     See also docinfo_.
 
@@ -2538,21 +2539,67 @@ Pseudo-XML_ fragment from simple parsing::
 `To be completed`_.
 
 
+``line``
+========
+
+The ``line`` element contains a single line of text, part of a
+`line_block`_.
+
+
+Details
+-------
+
+:Category:
+    `Body Subelements`_ (simple)
+
+:Parents:
+    Only the `line_block`_ element contains ``line``.
+
+:Children:
+    ``line`` elements may contain text data plus `inline elements`_.
+
+:Analogues:
+    ``line`` has no direct analogues in common DTDs.  It can be
+    emulated with primitives or type effects.
+
+:Processing:
+    See `line_block`_.
+
+
+Content Model
+-------------
+
+.. parsed-literal::
+
+   `%text.model;`_
+
+:Attributes:
+    The ``line`` element contains the `common attributes`_ (id_,
+    name_, dupname_, source_, and class_), plus `xml:space`_.
+
+
+Examples
+--------
+
+See `line_block`_.
+
+
 ``line_block``
 ==============
 
-The ``line_block`` element contains a block of text where line breaks
-and whitespace are significant and must be preserved.  ``line_block``
-elements are commonly used for verse and addresses.  See `line_block`_
-for an alternative useful for program listings and interactive
-computer sessions.
+The ``line_block`` element contains a sequence of lines and nested
+line blocks.  Line breaks (implied between elements) and leading
+whitespace (indicated by nesting) is significant and must be
+preserved.  ``line_block`` elements are commonly used for verse and
+addresses.  See `literal_block`_ for an alternative useful for program
+listings and interactive computer sessions.
 
 
 Details
 -------
 
 :Category:
-    `Simple Body Elements`_
+    `Compound Body Elements`_
 
 :Parents:
     All elements employing the `%body.elements;`_ or
@@ -2560,8 +2607,8 @@ Details
     may contain ``line_block``.
 
 :Children:
-    ``line_block`` elements may contain text data plus `inline
-    elements`_.
+    ``line_block`` elements may contain line_ elements and nested
+    ``line_block`` elements.
 
 :Analogues:
     ``line_block`` is analogous to the DocBook "literallayout" element
@@ -2570,7 +2617,7 @@ Details
 
 :Processing:
     Unline ``literal_block``, ``line_block`` elements are typically
-    rendered in an ordinary text typeface.  It is crucial that all
+    rendered in an ordinary text typeface.  It is crucial that leading
     whitespace and line breaks are preserved in the rendered form.
 
 
@@ -2579,7 +2626,7 @@ Content Model
 
 .. parsed-literal::
 
-   `%text.model;`_
+   (line_ | line_block_)+
 
 :Attributes:
     The ``line_block`` element contains the `common attributes`_ (id_,
@@ -2599,40 +2646,58 @@ Example source::
 
     Take it away, Eric the Orchestra Leader!
 
-    .. line-block::
-
-       A one, two, a one two three four
-
-       Half a bee, philosophically,
-           must, *ipso facto*, half not be.
-       But half the bee has got to be,
-           *vis a vis* its entity.  D'you see?
-
-       But can a bee be said to be
-           or not to be an entire bee,
-               when half the bee is not a bee,
-                   due to some ancient injury?
-
-       Singing...
+    | A one, two, a one two three four
+    |
+    | Half a bee, philosophically,
+    |     must, *ipso facto*, half not be.
+    | But half the bee has got to be,
+    |     *vis a vis* its entity.  D'you see?
+    |
+    | But can a bee be said to be
+    |     or not to be an entire bee,
+    |         when half the bee is not a bee,
+    |             due to some ancient injury?
+    |
+    | Singing...
 
 Pseudo-XML_ fragment from simple parsing::
 
     <paragraph>
         Take it away, Eric the Orchestra Leader!
-    <line_block xml:space="preserve">
-        A one, two, a one two three four
-
-        Half a bee, philosophically,
-            must, <emphasis>ipso facto</emphasis>, half not be.
-        But half the bee has got to be,
-            <emphasis>vis a vis</emphasis>its entity.  D'you see?
-
-        But can a bee be said to be
-            or not to be an entire bee,
-                when half the bee is not a bee,
-                    due to some ancient injury?
-
-        Singing...
+    <line_block>
+        <line>
+            A one, two, a one two three four
+        <line>
+        <line>
+            Half a bee, philosophically,
+        <line_block>
+            <line>
+                must, 
+                <emphasis>
+                    ipso facto
+                , half not be.
+        <line>
+            But half the bee has got to be,
+        <line_block>
+            <line>
+                <emphasis>
+                    vis a vis
+                 its entity.  D'you see?
+            <line>
+        <line>
+            But can a bee be said to be
+        <line_block>
+            <line>
+                or not to be an entire bee,
+            <line_block>
+                <line>
+                    when half the bee is not a bee,
+                <line_block>
+                    <line>
+                        due to some ancient injury?
+                    <line>
+        <line>
+            Singing...
 
 
 ``list_item``
-- 
cgit v1.2.1


From abecd9557393b8a49965f04edad866b950feb338 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 2 May 2005 14:59:57 +0000
Subject: added motivation for unresolved charset

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3283 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 66aaa06fb..79bac6202 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -132,8 +132,9 @@ html_body
 html_head
     ``parts['html_head']`` contains the HTML ``<head>`` content, less
     the stylesheet link and the ``<head>`` and ``</head>`` tags
-    themselves.  The "Content-Type" meta tag's "charset" value is left
-    unresolved, as "%s"::
+    themselves.  Since ``publish_parts`` returns Unicode strings and
+    does not know about the output encoding, the "Content-Type" meta
+    tag's "charset" value is left unresolved, as "%s"::
 
         <meta http-equiv="Content-Type" content="text/html; charset=%s" />
 
-- 
cgit v1.2.1


From 55cd5272b6cec7dc3cc9eae6bd8076dd0df064ab Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 9 May 2005 15:49:37 +0000
Subject: Added "border" option to "image" directive (& attribute to doctree
 element); updated docs & tests.  Closes Feature Request 1193389.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3322 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt           | 9 ++++-----
 docs/ref/docutils.dtd       | 1 +
 docs/ref/rst/directives.txt | 6 ++++++
 3 files changed, 11 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index cba560dca..fc06bbf85 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1121,12 +1121,11 @@ when used in a document.
     .. _unicode:
        http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
 
-  - _`images.image`: "border"?
+  - _`images.image`:_`Units of measure`?  (See `docutils-users,
+    2003-03-02`__, and `docutils-develop, 2004-04-29`__.)
 
-    _`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>`_.)
+    __ http://article.gmane.org/gmane.text.docutils.user/154
+    __ http://article.gmane.org/gmane.text.docutils.devel/1439
 
   - _`images.figure`: "title" and "number", to indicate a formal
     figure?
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index f3a7d37ca..455a8ae3a 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -481,6 +481,7 @@ or " ") or the text between option arguments (typically either "," or
     %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
+    border    %number;  #IMPLIED
     height    %number;  #IMPLIED
     width     %number;  #IMPLIED
     scale     %number;  #IMPLIED>
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 130f0d154..1ca51f28f 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -226,6 +226,12 @@ The following options are recognized:
     text flow around it.  The specific behavior depends upon the
     browser or rendering software used.
 
+``border`` : integer
+    The width of the image border, in pixels.  For images that are
+    also hyperlink references (see the ``target`` option, below),
+    browsers often draw a border by default.  Set ``:border: 0`` to
+    disable this default.
+
 ``target`` : text (URI or reference name)
     Makes the image into a hyperlink reference ("clickable").  The
     option argument may be a URI (relative or absolute), or a
-- 
cgit v1.2.1


From 9ed38a53f7de2eed5ed8ba98afb3e2ee28f2f75d Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 14 May 2005 16:14:44 +0000
Subject: reverting revision 3322: addition of ":border:" option to "image"
 directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3340 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt           | 9 +++++----
 docs/ref/docutils.dtd       | 1 -
 docs/ref/rst/directives.txt | 6 ------
 3 files changed, 5 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index fc06bbf85..cba560dca 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1121,11 +1121,12 @@ when used in a document.
     .. _unicode:
        http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
 
-  - _`images.image`:_`Units of measure`?  (See `docutils-users,
-    2003-03-02`__, and `docutils-develop, 2004-04-29`__.)
+  - _`images.image`: "border"?
 
-    __ http://article.gmane.org/gmane.text.docutils.user/154
-    __ http://article.gmane.org/gmane.text.docutils.devel/1439
+    _`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?
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index 455a8ae3a..f3a7d37ca 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -481,7 +481,6 @@ or " ") or the text between option arguments (typically either "," or
     %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
-    border    %number;  #IMPLIED
     height    %number;  #IMPLIED
     width     %number;  #IMPLIED
     scale     %number;  #IMPLIED>
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 1ca51f28f..130f0d154 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -226,12 +226,6 @@ The following options are recognized:
     text flow around it.  The specific behavior depends upon the
     browser or rendering software used.
 
-``border`` : integer
-    The width of the image border, in pixels.  For images that are
-    also hyperlink references (see the ``target`` option, below),
-    browsers often draw a border by default.  Set ``:border: 0`` to
-    disable this default.
-
 ``target`` : text (URI or reference name)
     Makes the image into a hyperlink reference ("clickable").  The
     option argument may be a URI (relative or absolute), or a
-- 
cgit v1.2.1


From 23969b82fe403cc4811537f5d42f8ef163326210 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 14 May 2005 16:30:08 +0000
Subject: note about "border": bad idea

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3342 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index cba560dca..fe74e54f4 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1121,7 +1121,7 @@ when used in a document.
     .. _unicode:
        http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
 
-  - _`images.image`: "border"?
+  - _`images.image`: "border"?  No, bad idea; use CSS instead.
 
     _`Units of measure`?  (See `docutils-users, 2003-03-02
     <http://article.gmane.org/gmane.text.docutils.user/154>`__, and
-- 
cgit v1.2.1


From 4ae722d597317382b222737ecf0b898b224dddcd Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 18 May 2005 22:27:52 +0000
Subject: added SectSubTitle transform

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3351 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 2 ++
 docs/user/config.txt    | 8 ++++++++
 2 files changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 9e4687a72..079bedaaa 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -34,6 +34,8 @@ frontmatter.DocTitle            standalone (r)                320
 
 frontmatter.DocInfo             standalone (r)                340
 
+frontmatter.SectSubTitle        standalone (r)                350
+
 peps.Headers                    pep (r)                       360
 
 peps.Contents                   pep (r)                       380
diff --git a/docs/user/config.txt b/docs/user/config.txt
index e3e052aaf..c00d82133 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -463,6 +463,14 @@ _`doctitle_xform`
 
     Default: enabled (1).  Options: ``--no-doc-title``.
 
+_`sectsubtitle_xform`
+
+    Enable or disable the promotion of the title of a lone subsection
+    to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
+
+    Default: disabled (0).  Options: ``--section-subtitle,
+    --no-section-subtitle``.
+
 
 [pep reader]
 ````````````
-- 
cgit v1.2.1


From caa4d0fc6528ad55bdd96434d7970ecc86931199 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 19 May 2005 00:49:14 +0000
Subject: renamed command-line options for SectSubTitle transform (plural reads
 better); tweaked test text

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3353 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index c00d82133..63725cf73 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -468,8 +468,8 @@ _`sectsubtitle_xform`
     Enable or disable the promotion of the title of a lone subsection
     to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
 
-    Default: disabled (0).  Options: ``--section-subtitle,
-    --no-section-subtitle``.
+    Default: disabled (0).  Options: ``--section-subtitles,
+    --no-section-subtitles``.
 
 
 [pep reader]
-- 
cgit v1.2.1


From 6570a5fef9123233156b518e2e0a5164e6411410 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 20 May 2005 22:35:39 +0000
Subject: added to-do list entry for figwidth test

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3355 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index fe74e54f4..2dd958920 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -677,6 +677,9 @@ __ rst/alternatives.html#or-not-to-do
 
 * Add (functional) tests for untested roles.
 
+* Add test for ":figwidth: image" option of "figure" directive.  (Test
+  code needs to check if PIL is available on the system.)
+
 * 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
-- 
cgit v1.2.1


From d7cf3789302b13092b7eeef61fbf0573a11b7af4 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 20 May 2005 23:25:18 +0000
Subject: documented different traceback default for programmatic use

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3356 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 63725cf73..de08d7960 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -356,9 +356,12 @@ _`traceback`
     reports.  Exceptions are allowed to propagate, instead of being
     caught and reported (in a user-friendly way) by Docutils.
 
-    Default: disabled (None).  Options: ``--traceback,
+    Default: disabled (None) unless Docutils is run programmatically
+    using the `Publisher Interface`_.  Options: ``--traceback,
     --no-traceback``.
 
+    .. _Publisher Interface: ../api/publisher.html
+
 _`warning_stream`
     Path to a file for the output of system messages (warnings)
     [#pwd]_.
-- 
cgit v1.2.1


From b9e9b91de245c0bba4bf150665474806b6924e01 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 20 May 2005 23:51:58 +0000
Subject: restored alphabetical order

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3357 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index de08d7960..d72ab621d 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -309,6 +309,18 @@ _`output_encoding_error_handler`
     Default: "strict".  Options: ``--output-encoding-error-handler,
     --output-encoding, -o``.
 
+_`record_dependencies`
+
+    Path to a file to which Docutils writes a list of files the input
+    file(s) depends on [#dependencies]_, e.g. due to file
+    inclusion. [#pwd]_ The format is one filename per line.  This
+    option is particularly useful in conjunction with programs like
+    ``make``.
+
+    Set to ``-`` in order to write dependencies to stdout.
+
+    Default: None.  Option: ``--record-dependencies``.
+
 _`report_level`
     Verbosity threshold at or above which system messages are
     reported.
@@ -368,18 +380,6 @@ _`warning_stream`
 
     Default: stderr (None).  Options: ``--warnings``.
 
-_`record_dependencies`
-
-    Path to a file to which Docutils writes a list of files the input
-    file(s) depends on [#dependencies]_, e.g. due to file
-    inclusion. [#pwd]_ The format is one filename per line.  This
-    option is particularly useful in conjunction with programs like
-    ``make``.
-
-    Set to ``-`` in order to write dependencies to stdout.
-
-    Default: None.  Option: ``--record-dependencies``.
-
 
 [parsers]
 ---------
-- 
cgit v1.2.1


From 3600f164d1078d31b98a31f9dbd878b6e2b7bf11 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 21 May 2005 00:00:25 +0000
Subject: added --id-prefix and --auto-id-prefix options

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3358 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index d72ab621d..a99bc5572 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -143,6 +143,13 @@ Some knowledge of Python_ is assumed for some attributes.
 
 Settings in the "[general]" section are always applied.
 
+_`auto_id_prefix`
+    Prefix prepended to all auto-generated IDs generated within the
+    document, after id_prefix_.
+
+    Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
 _`datestamp`
     Include a time/datestamp in the document footer.  Contains a
     format string for Python's ``time.strftime``.  See the `time
@@ -249,6 +256,13 @@ _`halt_level`
 
     Default: severe (4).  Options: ``--halt, --strict``.
 
+_`id_prefix`
+    Prefix prepended to all IDs generated within the document.  See
+    also auto_id_prefix_.
+
+    Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
 _`input_encoding`
     The text encoding for input.
 
-- 
cgit v1.2.1


From 0a9a7c9ed49f0a3320ffeba38df3a06a3424ad2f Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:41:17 +0000
Subject: some updates of doc files from CVS to SVN

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3363 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-plan.txt | 11 ++++++-----
 docs/dev/testing.txt        |  2 +-
 2 files changed, 7 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt
index e37bb0ded..0ab0d3c83 100644
--- a/docs/dev/enthought-plan.txt
+++ b/docs/dev/enthought-plan.txt
@@ -91,12 +91,13 @@ 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 Subversion 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.
+The Docutils project is very open about granting Subversion write
+access; so far, everyone who asked has been given access.  Any
+Enthought staff member who would like Subversion 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
diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 53faff37e..c3e9486c6 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -169,7 +169,7 @@ 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, copy it to
 ``functional/expected/`` (overwriting the old expected output), and
-commit the change to CVS.
+commit the change.
 
 
 .. _default configuration file:
-- 
cgit v1.2.1


From 4e18a9066509d7a767315773806789e589fb49ac Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:44:08 +0000
Subject: documented ignoring of functional test config files which start with
 an underscore

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3364 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index c3e9486c6..cc4f4881d 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -118,7 +118,8 @@ The Testing Process
 -------------------
 
 When running ``test_functional.py``, all config files in
-``functional/tests/`` are processed.
+``functional/tests/`` are processed.  (Config files whose names begin
+with an underscore are ignored.)
 
 For example, ``functional/tests/some_test.py`` could read like this::
 
-- 
cgit v1.2.1


From addb725de29a5e58a7c82d3d070c9a0b2b20704a Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:58:09 +0000
Subject: added information about working directory

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3365 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index cc4f4881d..9feac9c6a 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -119,7 +119,8 @@ The Testing Process
 
 When running ``test_functional.py``, all config files in
 ``functional/tests/`` are processed.  (Config files whose names begin
-with an underscore are ignored.)
+with an underscore are ignored.)  The current working directory is
+always Docutils' main test directory (``test/``).
 
 For example, ``functional/tests/some_test.py`` could read like this::
 
@@ -132,6 +133,8 @@ For example, ``functional/tests/some_test.py`` could read like this::
     parser_name = "rst"
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
+    # Relative to main ``test/`` directory.
+    settings_overrides['stylesheet_path'] = '../tools/stylesheets/default.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
-- 
cgit v1.2.1


From 8691ba2bdfae4c01a7bbbdfb8ae4fe8824efb4f9 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 26 May 2005 11:39:39 +0000
Subject: added "see also" references

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3370 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index a99bc5572..1b52511b4 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -407,7 +407,8 @@ Docutils currently supports only one parser, for reStructuredText.
 _`file_insertion_enabled`
     Enable or disable directives that insert the contents of external
     files, such as the "include_" & "raw_".  A "warning" system
-    message (including the directive text) is inserted instead.
+    message (including the directive text) is inserted instead.  (See
+    also raw_enabled_ for another security-relevant setting.)
 
     Default: enabled (1).  Options: ``--file-insertion-enabled,
     --no-file-insertion``.
@@ -429,7 +430,9 @@ _`pep_base_url`
 
 _`raw_enabled`
     Enable or disable the "raw_" directive.  A "warning" system
-    message (including the directive text) is inserted instead.
+    message (including the directive text) is inserted instead.  (See
+    also file_insertion_enabled_ for another security-relevant
+    setting.)
 
     Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
 
@@ -583,7 +586,8 @@ _`embed_stylesheet`
 _`field_name_limit`
     The maximum width (in characters) for one-column field names.
     Longer field names will span an entire row of the table used to
-    render the field list.  0 indicates "no limit".
+    render the field list.  0 indicates "no limit".  See also
+    option_limit_.
 
     Default: 14 characters.  Option: ``--field-name-limit``.
 
@@ -611,7 +615,8 @@ _`initial_header_level`
 _`option_limit`
     The maximum width (in characters) for options in option lists.
     Longer options will span an entire row of the table used to render
-    the option list.  0 indicates "no limit".
+    the option list.  0 indicates "no limit".  See also
+    field_name_limit_.
 
     Default: 14 characters.  Option: ``--option-limit``.
 
-- 
cgit v1.2.1


From caf8da4ece842aa51365a61dde28e0206fbc4b93 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 27 May 2005 20:46:54 +0000
Subject: moved section "Web Access" to the top

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3384 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index ade960c12..e22b0d428 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -23,6 +23,13 @@ Subversion is exhaustively documented in the `Subversion Book`_
 Accessing the Repository
 ========================
 
+Web Access
+----------
+
+The repository can be browsed and examined via the web at
+http://svn.berlios.de/viewcvs/docutils/.
+
+
 Anonymous Access
 ----------------
 
@@ -143,13 +150,6 @@ your shell account.
   password.
 
 
-Web Access
-----------
-
-The repository can be browsed and examined via the web at
-http://svn.berlios.de/viewcvs/docutils/.
-
-
 Repository Layout
 =================
 
-- 
cgit v1.2.1


From fa2db94c8f7c89a8ca41639eaf7925dc5506eaca Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 27 May 2005 23:26:21 +0000
Subject: moved mailing-lists.txt to docs/user so that it is included in the
 Docutils distribution

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3393 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt              |   1 +
 docs/user/mailing-lists.txt | 108 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 docs/user/mailing-lists.txt

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index 230761c10..1d8449a97 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -82,6 +82,7 @@ Docutils-general:
 * `Docutils Front-End Tools <user/tools.html>`__
 * `Docutils Configuration Files <user/config.html>`__
 * `Docutils LaTeX Writer <user/latex.html>`__
+* `Docutils Mailing Lists <user/mailing-lists.html>`__
 
 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
 
diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
new file mode 100644
index 000000000..e033f0cb8
--- /dev/null
+++ b/docs/user/mailing-lists.txt
@@ -0,0 +1,108 @@
+=========================
+ Docutils_ Mailing Lists
+=========================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+
+All discussion about Docutils takes place on mailing lists.
+
+There are four different lists with traffic related to Docutils.  If
+unsure, use the **Docutils-users** mailing list:
+
+
+Docutils-users
+--------------
+
+The Docutils-users mailing list is a place to discuss any issues
+related to the usage of Docutils and reStructuredText.  (Please be
+sure to check the FAQ_ first.)
+
+There are three possibilities to **read and post** messages on the
+mailing lists; use the one you feel most comfortable with.
+
+* Using an `email subscription`__.  This is the traditional way; you
+  will receive all messages sent to the mailing list via email.
+
+  __ http://lists.sourceforge.net/lists/listinfo/docutils-users
+
+* Using Gmane's `web interface`__.  To post a message, click "post" or
+  "followup" in the drop-down menu on the right.
+
+  __ http://news.gmane.org/gmane.text.docutils.user
+
+* If you prefer using a newsreader, you can also use Gmane's `NNTP
+  interface`__ (gmane.text.docutils.user on news.gmane.org).
+
+  __ nntp://news.gmane.org/gmane.text.docutils.user.
+
+**If you do not wish to subscribe,** you can also just send an email
+to Docutils-users@lists.sourceforge.net.  Please note in your email
+that you are not subscribed (to make sure that you receive copies
+[CCs] of any replies).
+
+The first time you post a message without being subscribed (also when
+posting via Gmane), you will receive an email with the subject "Your
+message to Docutils-users awaits moderator approval"; this is done to
+prevent spam to the mailing lists.  Your message will usually be
+approved within a few hours.  To avoid duplicates, please do not
+resend your message using a different email address.
+
+
+Doc-SIG
+-------
+
+The "Python Documentation Special Interest Group" (Doc-SIG) mailing
+list is occasionally used to discuss the usage of Docutils for Python
+documentation.
+
+This mailing list can be accessed via `email subscription`__, web__ or
+news__ (gmane.comp.python.documentation) as well.  You must be
+subscribed in order to post messages to this mailing list.
+
+__ http://mail.python.org/mailman/listinfo/doc-sig
+__ http://news.gmane.org/gmane.comp.python.documentation
+__ nntp://news.gmane.org/gmane.comp.python.documentation
+
+
+Docutils-develop
+----------------
+
+Discussions about developing and extending Docutils take place on the
+Docutils-develop mailing list.
+
+You can access this list via `email subscription`__, web__ or news__
+(gmane.text.docutils.devel); the posting address is
+Docutils-develop@lists.sourceforge.net.
+
+__ http://lists.sourceforge.net/lists/listinfo/docutils-develop
+__ http://news.gmane.org/gmane.text.docutils.devel
+__ nntp://news.gmane.org/gmane.text.docutils.devel
+
+Docutils-checkins
+-----------------
+
+All check-ins to the `Subversion repository`_ cause a "check-in email"
+to the Docutils-checkins list.  In order to stay informed about
+current development, developers are advised to monitor this mailing
+list as well.
+
+
+This mailing list is for reading only; please direct any discussion
+about the check-ins to Docutils-develop.  (For your convenience, the
+Reply-To header of all check-in emails points to Docutils-develop.)
+
+This mailing list is accessible via `email subscription`__, web__ or
+news__ (gmane.text.docutils.cvs) as well.
+
+__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins
+__ http://news.gmane.org/gmane.text.docutils.cvs
+__ nntp://news.gmane.org/gmane.text.docutils.cvs
+
+.. _Subversion repository: http://docutils.sf.net/docs/dev/repository.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _FAQ: http://docutils.sourceforge.net/FAQ.html
-- 
cgit v1.2.1


From 5817462e98504cbdf9be51649639273ed604c739 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 27 May 2005 23:30:32 +0000
Subject: updated rst-roles howto to match new "classes" list attribute

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3394 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/rst-roles.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt
index f271bff9d..f8ce08bca 100644
--- a/docs/howto/rst-roles.txt
+++ b/docs/howto/rst-roles.txt
@@ -199,8 +199,10 @@ Here is the implementation of the role::
             prb = inliner.problematic(rawtext, rawtext, msg)
             return [prb], [msg]
         # Base URL mainly used by inliner.rfc_reference, so this is correct:
-        ref = inliner.rfc_url % rfcnum
-        node = nodes.reference(rawtext, 'RFC ' + text, refuri=ref, **options)
+        ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
+        set_classes(options)
+        node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
+                               **options)
         return [node], []
 
     register_canonical_role('rfc-reference', rfc_reference_role)
@@ -218,7 +220,9 @@ Noteworthy in the code above are:
    the "refuri" attribute of a "reference" element.
 
 3. The ``options`` function parameter, a dictionary, may contain a
-   "class" customization attribute; it is passed through to the
-   "reference" element node constructor.
+   "class" customization attribute; it is interpreted and replaced
+   with a "classes" attribute by the ``set_classes()`` function.  The
+   resulting "classes" attribute is passed through to the "reference"
+   element node constructor.
 
 .. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search
-- 
cgit v1.2.1


From b7b2f9f3ecf1b3877314db63d09242dfe71b41fc Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 28 May 2005 00:30:02 +0000
Subject: replaced references to the mailing lists with references to the new
 "mailing-lists" document

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3396 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/runtime-settings.txt |  4 ++--
 docs/dev/policies.txt         | 19 +++----------------
 docs/dev/release.txt          |  4 ++--
 docs/ref/rst/directives.txt   | 10 ++++++----
 docs/ref/rst/roles.txt        |  6 ++++--
 docs/user/rst/quickstart.txt  |  9 +++------
 docs/user/tools.txt           | 12 ++++--------
 7 files changed, 24 insertions(+), 40 deletions(-)

(limited to 'docs')

diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt
index d6b8997cd..0da1ae6d9 100644
--- a/docs/api/runtime-settings.txt
+++ b/docs/api/runtime-settings.txt
@@ -176,7 +176,7 @@ application calls one of ``publish_file``, ``publish_string``, or
 which implements a generic programmatic interface.  Although an
 application may also call ``publish_programmatically`` directly, it is
 not recommended (if it does seem to be necessary, please write to the
-`Docutils-Develop mailing list`_).
+Docutils-develop_ mailing list).
 
 ``publish_programmatically`` accepts the same `convenience function
 parameters`_ as ``publish_cmdline``.  Where things differ is that
@@ -189,4 +189,4 @@ up the runtime settings.
 .. copy & modify the list from command-line tools?
 
 
-.. _Docutils-Develop mailing list: docutils-develop@lists.sf.net
+.. _Docutils-develop: ../users/mailing-lists.html#docutils-develop
diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 99eade2e7..f21ed470e 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -306,22 +306,9 @@ meaning.  There are two ways to keep the Docutils code accessible:
 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@python.org).
-* Docutils-develop__, for implementation discussions
-  (email to docutils-develop@lists.sourceforge.net).
-* Docutils-checkins__, to monitor Subversion check-in 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
+Developers are recommended to subscribe to all `mailing lists`_.
+
+.. _mailing lists:: ../user/mailing-lists.html
 
 
 The Sandbox
diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index 7ae12af88..fd941e5d3 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -15,7 +15,7 @@ sandbox/felixwiemann/release.sh.  "Not covered" means that you aren't
 even reminded of them.  Note: The release.sh script needs to be
 updated to reflect the recent move to Subversion!)
 
-* **Announce a checkin freeze on Docutils-develop.  Post a list of
+* **Announce a check-in freeze on Docutils-develop.  Post a list of
   major changes since the last release and ask for additions.**
 
   .. _CHANGES.txt:
@@ -137,7 +137,7 @@ updated to reflect the recent move to Subversion!)
 * **Send announcement email to:**
 
   * docutils-develop@lists.sourceforge.net (also announcing the end
-    of the checkin freeze)
+    of the check-in freeze)
   * docutils-users@lists.sourceforge.net
   * doc-sig@python.org
   * python-announce@python.org
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 130f0d154..603b89b98 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -612,8 +612,10 @@ that begins in one physical paragraph and ends in another.
    sequence of elements, or you may get unexpected results.
 
    If you happen to need a generic block-level container, please
-   describe your use-case in an email to
-   docutils-users@lists.sourceforge.net.
+   describe your use-case in an email to the Docutils-users_ mailing
+   list.
+
+   .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
 
 Compound paragraphs are typically rendered as multiple distinct text
 blocks, with the possibility of variations to emphasize their logical
@@ -1224,8 +1226,8 @@ Raw Data Pass-Through
    If you often need to use the "raw" directive or a "raw"-derived
    interpreted text role, that is a sign either of overuse/abuse or
    that functionality may be missing from reStructuredText.  Please
-   describe your situation in email to
-   docutils-users@lists.sourceforge.net.
+   describe your situation in an email to the Docutils-users_ mailing
+   list.
 
 The "raw" directive indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  The names of the output formats are
diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index a911cf469..1cb2e540b 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -276,8 +276,10 @@ must be used to obtain a ``title_reference`` element.
    If you often need to use "raw"-derived interpreted text roles or
    the "raw" directive, that is a sign either of overuse/abuse or that
    functionality may be missing from reStructuredText.  Please
-   describe your situation in email to
-   docutils-users@lists.sourceforge.net.
+   describe your situation in an email to the Docutils-users_ mailing
+   list.
+
+   .. _Docutils-users: ../../user/mailing-lists.html#docutils-user
 
 The "raw" role indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  It is the inline equivalent of the
diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt
index bf6b21275..735dcf512 100644
--- a/docs/user/rst/quickstart.txt
+++ b/docs/user/rst/quickstart.txt
@@ -375,16 +375,13 @@ user reference is a good place to go next.  For complete details, the
 `reStructuredText Markup Specification`_ is the place to go [#]_.
 
 Users who have questions or need assistance with Docutils or
-reStructuredText should `post a message`_ to the `Docutils-Users
-mailing list`_.  The `Docutils project web site`_ has more
-information.
+reStructuredText should post a message to the Docutils-users_ mailing
+list.
 
 .. [#] If that relative link doesn't work, try the master document:
    http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
 
 .. _reStructuredText Markup Specification:
    ../../ref/rst/restructuredtext.html
-.. _post a message: mailto:docutils-users@lists.sourceforge.net
-.. _Docutils-Users mailing list:
-   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils-users: ../mailing-lists.html#docutils-users
 .. _Docutils project web site: http://docutils.sourceforge.net/
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index ab31e0917..9cd136988 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -44,14 +44,10 @@ Getting Help
 First, try the "``--help``" option each front-end tool has.
 
 Users who have questions or need assistance with Docutils or
-reStructuredText should `post a message`_ to the `Docutils-Users
-mailing list`_.  The `Docutils project web site`_ has more
-information.
-
-.. _post a message: mailto:docutils-users@lists.sourceforge.net
-.. _Docutils-Users mailing list:
-   http://lists.sourceforge.net/lists/listinfo/docutils-users
-.. _Docutils project web site: http://docutils.sourceforge.net/
+reStructuredText should post a message to the Docutils-users_ mailing
+list.
+
+.. _Docutils-users: mailing-lists.html#docutils-users
 
 
 The Tools
-- 
cgit v1.2.1


From 470195b45aa54c6f651cb107c038218090b05653 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 28 May 2005 01:22:12 +0000
Subject: fixed links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3398 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/runtime-settings.txt | 2 +-
 docs/howto/i18n.txt           | 2 +-
 docs/peps/pep-0256.txt        | 2 +-
 docs/peps/pep-0258.txt        | 2 +-
 docs/peps/pep-0287.txt        | 2 +-
 docs/user/config.txt          | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt
index 0da1ae6d9..2d60aa3e1 100644
--- a/docs/api/runtime-settings.txt
+++ b/docs/api/runtime-settings.txt
@@ -189,4 +189,4 @@ up the runtime settings.
 .. copy & modify the list from command-line tools?
 
 
-.. _Docutils-develop: ../users/mailing-lists.html#docutils-develop
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
diff --git a/docs/howto/i18n.txt b/docs/howto/i18n.txt
index e3d97502a..4a5b1de5a 100644
--- a/docs/howto/i18n.txt
+++ b/docs/howto/i18n.txt
@@ -59,7 +59,7 @@ is "en" for English.  Examples of module names include ``en.py``,
    of hyphens, to conform to Python naming rules.
 
 .. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html
-.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
+.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
 .. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
    02iso-3166-code-lists/index.html
 
diff --git a/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt
index 42c1bada9..1e5e87e35 100644
--- a/docs/peps/pep-0256.txt
+++ b/docs/peps/pep-0256.txt
@@ -246,7 +246,7 @@ References and Footnotes
 
 .. _Literate Programming: http://www.literateprogramming.com/
 
-.. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
+.. _POD: http://perldoc.perl.org/perlpod.html
 
 .. _Javadoc: http://java.sun.com/j2se/javadoc/
 
diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt
index 4aaeecf3a..7779411a6 100644
--- a/docs/peps/pep-0258.txt
+++ b/docs/peps/pep-0258.txt
@@ -969,7 +969,7 @@ stylist code will lower the barrier considerably.
 .. _Docutils Python Source DTD:
    http://docutils.sourceforge.net/docs/dev/pysource.dtd
 
-.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
+.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
 
 .. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/
 
diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt
index d22efe224..18b3abfa7 100644
--- a/docs/peps/pep-0287.txt
+++ b/docs/peps/pep-0287.txt
@@ -757,7 +757,7 @@ __ http://www.python.org/doc/Humor.html#zen
 
 .. _TeX: http://www.tug.org/interest.html
 
-.. _Perl POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
+.. _Perl POD: http://perldoc.perl.org/perlpod.html
 
 .. _JavaDoc: http://java.sun.com/j2se/javadoc/
 
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 1b52511b4..66ad39234 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -903,7 +903,7 @@ _`_source`
     Default: stdin (None).  No command-line options.
 
 
-.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
+.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
 
 .. [#pwd] Path relative to the working directory of the process at
    launch.
-- 
cgit v1.2.1


From 03e444a1ba0af10974dce90d058328365d356e0c Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 28 May 2005 13:20:48 +0000
Subject: started links document

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3399 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 docs/user/links.txt

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
new file mode 100644
index 000000000..2102fac7d
--- /dev/null
+++ b/docs/user/links.txt
@@ -0,0 +1,18 @@
+=================
+ Docutils_ Links
+=================
+
+:Revision: $Revision $
+:Date: $Date $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+The most current version of this document can always be found at
+http://docutils.sourceforge.net/docs/user/links.html.
+
+* rest2web__ is a tool for creating web sites with reStructuredText.
+
+  __ http://article.gmane.org/gmane.text.docutils.user/2006
+
+* to be continued...
-- 
cgit v1.2.1


From 453b70a30a2a182d5498dabed978c4b7ff997cea Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 28 May 2005 14:16:21 +0000
Subject: fixed revision and date

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3400 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 2102fac7d..466f8a8ee 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -2,8 +2,8 @@
  Docutils_ Links
 =================
 
-:Revision: $Revision $
-:Date: $Date $
+:Revision: $Revision$
+:Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
 .. _Docutils: http://docutils.sourceforge.net/
-- 
cgit v1.2.1


From 1c2ca6555cd55bec2fa4a4207a24a2c1d16b9234 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 29 May 2005 06:53:02 +0000
Subject: updated links; removed note about possibly outdated docs -- that's
 obvious

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3404 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index 1d8449a97..bffe3942d 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -9,13 +9,10 @@
 :Copyright: This document has been placed in the public domain.
 
 The latest working documents may be accessed individually below, or
-from the ``docs`` directory of the `development snapshots`__.  They
-are also distributed with the `latest project release package`__, but
-those may not be completely up to date.
+from the ``docs`` directory of the `Docutils distribution`_.
 
-__ http://docutils.sourceforge.net/#development-snapshots
-__ http://docutils.sourceforge.net/#project-releases
 .. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils distribution: http://docutils.sourceforge.net/#download
 
 .. contents::
 
-- 
cgit v1.2.1


From 0967ac7c8663c1b4555a05067cdbc3194b526fe5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 31 May 2005 21:11:09 +0000
Subject: added target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3414 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 2dd958920..abcb2e66b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -680,9 +680,9 @@ __ rst/alternatives.html#or-not-to-do
 * Add test for ":figwidth: image" option of "figure" directive.  (Test
   code needs to check if PIL is available on the system.)
 
-* 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
+* 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 function ``unicodedata.east_asian_width``,
-- 
cgit v1.2.1


From 09bd939d15ae77a5e53274cdf27ee6bd8587553b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 1 Jun 2005 00:56:39 +0000
Subject: correction

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3415 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/latex.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/latex.txt b/docs/user/latex.txt
index d66586bc7..ce8447692 100644
--- a/docs/user/latex.txt
+++ b/docs/user/latex.txt
@@ -219,8 +219,8 @@ Images
 Images are included in LaTeX by the graphicx package. The supported
 image formats depend on the used driver (dvi, dvips, pdftex, ...).
 
-pdf-image inclusion in pdf files fails, specify ``--graphicx-option=pdftex``
-or ``--graphicx-option=auto``.
+If pdf-image inclusion in pdf files fails, specify
+``--graphicx-option=pdftex`` or ``--graphicx-option=auto``.
 
 
 Commands directly to LaTeX
-- 
cgit v1.2.1


From 78ed5de20eb3c06ef02efd5710145321fc40596f Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 1 Jun 2005 14:44:50 +0000
Subject: docutils.__version_details__ renamed from .__version_suffix__

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3417 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index fd941e5d3..b242720d0 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -24,6 +24,9 @@ updated to reflect the recent move to Subversion!)
   (e.g. CHANGES.txt) to have it at hand when you need it for posting
   announcements or pasting it into forms.**
 
+* Change ``__version_details__`` in docutils/docutils/__init__.py to
+  "release" (from "repository").
+
 * Bump the _`version number` in the following files:
 
   + docutils/setup.py
@@ -126,6 +129,9 @@ updated to reflect the recent move to Subversion!)
 
 * Register with PyPI (``python setup.py register``).
 
+* Restore ``__version_details__`` in docutils/docutils/__init__.py to
+  "repository" (from "release").
+
 * Bump the `version number`_ again.
 
 * Add a new empty section "Changes Since ..." in HISTORY.txt.
-- 
cgit v1.2.1


From 8e0b54fa689b16798b6ca213bad39fca17954438 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 1 Jun 2005 21:45:03 +0000
Subject: added idea for document splitting

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3422 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index abcb2e66b..361a82c6d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -250,7 +250,7 @@ General
 * 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).
+  other documents`_ below), splitting (`document splitting`_ below).
 
   When writing a book, the author probably wants to split it up into
   files, perhaps one per chapter (but perhaps even more detailed).
@@ -1683,11 +1683,36 @@ Unimplemented Transforms
   (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.
+  Ideas:
+
+  - 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.
+
+  - Transform a single-root document into a document containing
+    multiple subdocuments, recursively.  The content model of the
+    "document" element would have to change to::
+
+        <!ELEMENT document
+            ( (title, subtitle?)?,
+              decoration?,
+              (docinfo, transition?)?,
+              %structure.model;,
+              document* )>
+
+    (I.e., add the last line -- 0 or more document elements.)
+
+    Let's look at the case of hierarchical (directories and files)
+    HTML output.  Each document element containing further document
+    elements would correspond to a directory (with an index.html file
+    for the content preceding the subdocuments).  Each document
+    element containing no subdocuments (i.e., structure model elements
+    only) corresponds to a concrete file with no directory.
+
+    The natural transform would be to map sections to subdocuments,
+    but possibly only a given number of levels deep.
 
 * _`Navigation`
 
-- 
cgit v1.2.1


From 5095d1c0d6811a2180da6528e929347c10fc123e Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 3 Jun 2005 23:52:18 +0000
Subject: added clarification

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3426 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 57362c5db..6d21934b4 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2213,6 +2213,8 @@ Replacement text
         __ http://developer.java.sun.com/developer/earlyAccess/
            j2eecas/
 
+    The "replace_" directive has been implemented.
+
 
 Comments
 ````````
@@ -2815,6 +2817,7 @@ Markup errors are handled according to the specification in `PEP
 .. _HTML Techniques for Web Content Accessibility Guidelines:
    http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
 .. _image: directives.html#image
+.. _replace: directives.html#replace
 .. _meta: directives.html#meta
 .. _figure: directives.html#figure
 .. _admonition: directives.html#admonitions
-- 
cgit v1.2.1


From c1312b37ba8887cf092065cb09f3d09ee034ac31 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 4 Jun 2005 04:01:58 +0000
Subject: added "default-role" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3427 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 603b89b98..d336a48dd 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1542,6 +1542,49 @@ details.
 .. _reStructuredText Interpreted Text Roles: roles.html
 
 
+.. _default-role:
+
+Setting the Default Interpreted Text Role
+=========================================
+
+:Directive Type: "default-role"
+:Doctree Element: None; affects subsequent parsing.
+:Directive Arguments: One, optional (new default role name).
+:Directive Options: None.
+:Directive Content: None.
+
+(New in Docutils 0.3.8)
+
+The "default-role" directive sets the default interpreted text role,
+the role that is used for interpreted text without an explicit role.
+For example, after setting the default role like this::
+
+    .. default-role:: subscript
+
+any subsequent use of implicit-role interpreted text in the document
+will use the "subscript" role::
+
+    An example of a `default` role.
+
+This will be parsed into the following document tree fragment::
+
+    <paragraph>
+        An example of a
+        <subscript>
+            default
+         role.
+
+Custom roles may be used (see the "role_" directive above), but it
+must have been declared in a document before it can be set as the
+default role.  See the `reStructuredText Interpreted Text Roles`_
+document for details of built-in roles.
+
+The directive may be used without an argument to restore the initial
+default interpreted text role, which is application-dependent.  The
+initial default interpreted text role of the standard reStructuredText
+parser is "title-reference".
+
+
 Restructuredtext-Test-Directive
 ===============================
 
-- 
cgit v1.2.1


From 8190158763b3afc33a14d0674e7364fc2d2d26f6 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 4 Jun 2005 04:08:25 +0000
Subject: updated & corrected docs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3428 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt  | 2 +-
 docs/user/rst/cheatsheet.txt | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index d336a48dd..dde952b7d 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1553,7 +1553,7 @@ Setting the Default Interpreted Text Role
 :Directive Options: None.
 :Directive Content: None.
 
-(New in Docutils 0.3.8)
+(New in Docutils 0.3.10)
 
 The "default-role" directive sets the default interpreted text role,
 the role that is used for interpreted text without an explicit role.
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 03eddf814..7ae1d55f5 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -100,6 +100,7 @@ replace           Replacement text for substitution definitions
 unicode           Unicode character code conversion for substitution defs
 class             Set a "class" attribute on the next element
 role              Create a custom interpreted text role [0.3.2]
+default-role      Set the default interpreted text role [0.3.10]
 ================  ============================================================
 
 Interpreted Text Role Quick Reference
-- 
cgit v1.2.1


From 1e84e4a9faaecb92e19f35d4597db8d208490132 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 4 Jun 2005 19:05:59 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3429 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 361a82c6d..4f4509dfc 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1508,8 +1508,8 @@ 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
+just need to have already been declared.  Adding a new role may
+involve 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.
 
@@ -1530,7 +1530,7 @@ 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
+    role for interpreted text (done)
   - allow the reST processor to take an argument for the default role
     (this will be subsumed by the above via the runtime settings
     mechanism)
-- 
cgit v1.2.1


From 5dd123325ec534de16ee060bf1723a8fa5bb33d7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 5 Jun 2005 15:12:08 +0000
Subject: added a "Hacker's Guide" containing a first overview of Docutils'
 architecture

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3431 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/hacking.txt | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.txt       |   1 +
 2 files changed, 211 insertions(+)
 create mode 100644 docs/dev/hacking.txt

(limited to 'docs')

diff --git a/docs/dev/hacking.txt b/docs/dev/hacking.txt
new file mode 100644
index 000000000..d98823ba0
--- /dev/null
+++ b/docs/dev/hacking.txt
@@ -0,0 +1,210 @@
+.. -*- coding: utf-8 -*-
+
+==========================
+ Docutils_ Hacker's Guide
+==========================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+:Abstract: This is the introduction to Docutils for all persons who
+    want to extend Docutils in some way.
+:Prerequisites: You have used reStructuredText_ and played around with
+    the `Docutils front-end tools`_ before.  Some (basic) Python
+    knowledge is certainly helpful (though not necessary, strictly
+    speaking).
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Docutils front-end tools: ../user/tools.html
+
+.. contents::
+
+
+Overview of the Docutils Architecture
+=====================================
+
+To give you an understanding of the Docutils architecture, we'll dive
+right into the internals using a practical example.
+
+Consider the following reStructuredText file::
+
+    My *favorite* language is Python_.
+
+    .. _Python: http://www.python.org/
+
+Using the ``rst2html.py`` front-end tool, you would get an HTML output
+which looks like this::
+
+    [uninteresting HTML code removed]
+    <body>
+    <div class="document">
+    <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p>
+    </div>
+    </body>
+    </html>
+
+While this looks very simple, it's enough to illustrate all internal
+processing stages of Docutils.  Let's see how this document is
+processed from the reStructuredText source to the final HTML output:
+
+Reading the Document
+--------------------
+
+The **Reader** reads the document from the source file and passes it
+to the parser (see below).  The default reader is the standalone
+reader (``docutils/readers/standalone.py``) which just reads the input
+data from a single text file.  Unless you want to do really fancy
+things, there is no need to change that.
+
+Since you probably won't need to touch readers, we will just move on
+to the next stage:
+
+Parsing the Document
+--------------------
+
+The **Parser** analyzes the the input document and creates a **node
+tree** representation.  In this case we are using the
+**reStructuredText parser** (``docutils/parsers/rst/__init__.py``).
+To see what that node tree looks like, we call ``quicktest.py`` (which
+can be found in the ``tools/`` directory of the Docutils distribution)
+with our example file (``test.txt``) as first parameter (Windows users
+might need to type ``python quicktest.py test.txt``)::
+
+    $ quicktest.py test.txt
+    <document source="test.txt">
+        <paragraph>
+            My
+            <emphasis>
+                favorite
+             language is
+            <reference name="Python" refname="python">
+                Python
+            .
+        <target ids="python" names="python" refuri="http://www.python.org/">
+
+Let us now examine the node tree:
+
+The top-level node is ``document``.  It has a ``source`` attribute
+whose value is ``text.txt``.  There are two children: A ``paragraph``
+node and a ``target`` node.  The ``paragraph`` in turn has children: A
+text node ("My "), an ``emphasis`` node, a text node (" language is "),
+a ``reference`` node, and again a ``Text`` node (".").
+
+These node types (``document``, ``paragraph``, ``emphasis``, etc.) are
+all defined in ``docutils/nodes.py``.  The node types are internally
+arranged as a class hierarchy (for example, both ``emphasis`` and
+``reference`` have the common superclass ``Inline``).  To get an
+overview of the node class hierarchy, use epydoc (type ``epydoc
+nodes.py``) and look at the class hierarchy tree.
+
+Transforming the Document
+-------------------------
+
+In the node tree above, the ``reference`` node does not contain the
+target URI (``http://www.python.org/``) yet.
+
+Assigning the target URI (from the ``target`` node) to the
+``reference`` node is *not* done by the parser (the parser only
+translates the input document into a node tree).
+
+Instead, it's done by a **Transform**.  In this case (resolving a
+reference), it's done by the ``ExternalTargets`` transform in
+``docutils/transforms/references.py``.
+
+In fact, there are quite a lot of Transforms, which do various useful
+things like creating the table of contents, applying substitution
+references or resolving auto-numbered footnotes.
+
+The Transforms are applied after parsing.  To see how the node tree
+has changed after applying the Transforms, we use the
+``rst2pseudoxml.py`` tool:
+
+.. parsed-literal::
+
+    $ rst2pseudoxml.py test.txt
+    <document source="test.txt">
+        <paragraph>
+            My
+            <emphasis>
+                favorite
+             language is
+            <reference name="Python" **refuri="http://www.python.org/"**>
+                Python
+            .
+        <target ids="python" names="python" ``refuri="http://www.python.org/"``>
+
+For our small test document, the only change is that the ``refname``
+attribute of the reference has been replaced by a ``refuri``
+attribute—the reference has been resolved.
+
+While this does not look very exciting, transforms are a powerful tool
+to apply any kind of transformation on the node tree.
+
+By the way, you can also get a "real" XML representation of the node
+tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``.
+
+Writing the Document
+--------------------
+
+To get an HTML document out of the node tree, we use a **Writer**, the
+HTML writer in this case (``docutils/writers/html4css1.py``).
+
+The writer receives the node tree and returns the output document.
+For HTML output, we can test this using the ``rst2html.py`` tool::
+
+    $ rst2html.py test.txt
+    <?xml version="1.0" encoding="utf-8" ?>
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+    <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
+    <title>
+    
+    
+    
+    
    
+    
    My favorite language is Python.
    
+    
    
+    
+    
+
+So here we finally have our HTML output.  The actual document contents
+are in the fourth-last line.  Note, by the way, that the HTML writer
+did not render the (invisible) ``target`` node—only the ``paragraph``
+node and its children appear in the HTML output.
+
+
+Extending Docutils
+==================
+
+Now you'll ask, "how do I actually extend Docutils?"
+
+First of all, once you are clear about *what* you want to achieve, you
+have to decide *where* to implement it—in the Parser (e.g. by adding a
+directive or role to the reStructuredText parser), as a Transform, or
+in the Writer.  There is often one obvious choice among those three
+(Parser, Transform, Writer).  If you are unsure, ask on the
+Docutils-develop_ mailing list.
+
+In order to find out how to start, it is often helpful to look at
+similar features which are already implemented.  For example, if you
+want to add a new directive to the reStructuredText parser, look at
+the implementation of a similar directive in
+``docutils/parsers/rst/directives/``.
+
+
+What Now?
+=========
+
+This document is not complete.  Many topics could (and should) be
+covered here.  To find out with which topics we should write about
+first, we are awaiting *your* feedback.  So please ask your questions
+on the Docutils-develop_ mailing list.
+
+
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
diff --git a/docs/index.txt b/docs/index.txt
index bffe3942d..67849d393 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -179,6 +179,7 @@ __ http://www.python.org/peps/pep-0287.html
 
 Docutils-general:
 
+* `Docutils Hacker's Guide `__
 * `Docutils To Do List `__
 * `Docutils Project Policies `__
 * `Docutils Web Site `__
-- 
cgit v1.2.1


From 2a162380e977d3862d42986cbbd470bbbe6a463e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 5 Jun 2005 15:21:24 +0000
Subject: correction

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3432 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/mailing-lists.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
index e033f0cb8..c7ce909cf 100644
--- a/docs/user/mailing-lists.txt
+++ b/docs/user/mailing-lists.txt
@@ -89,8 +89,7 @@ Docutils-checkins
 All check-ins to the `Subversion repository`_ cause a "check-in email"
 to the Docutils-checkins list.  In order to stay informed about
 current development, developers are advised to monitor this mailing
-list as well.
-
+list.
 
 This mailing list is for reading only; please direct any discussion
 about the check-ins to Docutils-develop.  (For your convenience, the
-- 
cgit v1.2.1


From a862180aebdaa82e6169aa0ee42bf029be48575c Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 5 Jun 2005 19:05:58 +0000
Subject: added posting statistics from Gmane

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3435 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/mailing-lists.txt | 49 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

(limited to 'docs')

diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
index c7ce909cf..e1083fc9a 100644
--- a/docs/user/mailing-lists.txt
+++ b/docs/user/mailing-lists.txt
@@ -18,6 +18,18 @@ unsure, use the **Docutils-users** mailing list:
 Docutils-users
 --------------
 
+.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
+    group=gmane.text.docutils.user&
+    title=Posting+rate+for+Docutils-users
+   :target: http://gmane.org/plot-rate.php?width=600&height=300&
+    group=gmane.text.docutils.user&
+    title=Posting+rate+for+Docutils-users
+   :alt: Posting rate for Docutils-users
+   :width: 300
+   :height: 150
+   :align: right
+   :class: borderless
+
 The Docutils-users mailing list is a place to discuss any issues
 related to the usage of Docutils and reStructuredText.  (Please be
 sure to check the FAQ_ first.)
@@ -56,6 +68,18 @@ resend your message using a different email address.
 Doc-SIG
 -------
 
+.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
+    group=gmane.comp.python.documentation&
+    title=Posting+rate+for+Doc-SIG
+   :target: http://gmane.org/plot-rate.php?width=600&height=300&
+    group=gmane.comp.python.documentation&
+    title=Posting+rate+for+Doc-SIG
+   :alt: Posting rate for Doc-SIG
+   :width: 300
+   :height: 150
+   :align: right
+   :class: borderless
+
 The "Python Documentation Special Interest Group" (Doc-SIG) mailing
 list is occasionally used to discuss the usage of Docutils for Python
 documentation.
@@ -72,6 +96,18 @@ __ nntp://news.gmane.org/gmane.comp.python.documentation
 Docutils-develop
 ----------------
 
+.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
+    group=gmane.text.docutils.devel&
+    title=Posting+rate+for+Docutils-develop
+   :target: http://gmane.org/plot-rate.php?width=600&height=300&
+    group=gmane.text.docutils.devel&
+    title=Posting+rate+for+Docutils-develop
+   :alt: Posting rate for Docutils-develop
+   :width: 300
+   :height: 150
+   :align: right
+   :class: borderless
+
 Discussions about developing and extending Docutils take place on the
 Docutils-develop mailing list.
 
@@ -83,9 +119,22 @@ __ http://lists.sourceforge.net/lists/listinfo/docutils-develop
 __ http://news.gmane.org/gmane.text.docutils.devel
 __ nntp://news.gmane.org/gmane.text.docutils.devel
 
+
 Docutils-checkins
 -----------------
 
+.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
+    group=gmane.text.docutils.cvs&
+    title=Posting+rate+for+Docutils-checkins
+   :target: http://gmane.org/plot-rate.php?width=600&height=300&
+    group=gmane.text.docutils.cvs&
+    title=Posting+rate+for+Docutils-checkins
+   :alt: Posting rate for Docutils-checkins
+   :width: 300
+   :height: 150
+   :align: right
+   :class: borderless
+
 All check-ins to the `Subversion repository`_ cause a "check-in email"
 to the Docutils-checkins list.  In order to stay informed about
 current development, developers are advised to monitor this mailing
-- 
cgit v1.2.1


From bcea223d684bff8c8344421ca3a0540313e9bd3e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 5 Jun 2005 19:33:33 +0000
Subject: added note about developers who already have CVS write-access on
 SF.net

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3436 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index e22b0d428..7a3cfde60 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -3,6 +3,7 @@
 ==========================
 
 :Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
@@ -60,6 +61,12 @@ type ::
 Developer Access
 ----------------
 
+(Developers who had write-access for Docutils' CVS repository on
+SourceForge.net should `register at BerliOS`__ and send an email with
+their BerliOS user name to `Felix Wiemann `_.)
+
+__ https://developer.berlios.de/account/register.php
+
 If you are a developer, you get read-write access via
 ``svn+ssh://username@svn.berlios.de/svnroot/repos/docutils/``, where
 ``username`` is your BerliOS user name.  So to retrieve a working
-- 
cgit v1.2.1


From 7ccac8221c559ac7fab0428807919c6831b6c848 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 7 Jun 2005 22:13:33 +0000
Subject: removed mailing list statistics; they are distracting

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3450 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/mailing-lists.txt | 48 ---------------------------------------------
 1 file changed, 48 deletions(-)

(limited to 'docs')

diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
index e1083fc9a..de4aff3de 100644
--- a/docs/user/mailing-lists.txt
+++ b/docs/user/mailing-lists.txt
@@ -18,18 +18,6 @@ unsure, use the **Docutils-users** mailing list:
 Docutils-users
 --------------
 
-.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
-    group=gmane.text.docutils.user&
-    title=Posting+rate+for+Docutils-users
-   :target: http://gmane.org/plot-rate.php?width=600&height=300&
-    group=gmane.text.docutils.user&
-    title=Posting+rate+for+Docutils-users
-   :alt: Posting rate for Docutils-users
-   :width: 300
-   :height: 150
-   :align: right
-   :class: borderless
-
 The Docutils-users mailing list is a place to discuss any issues
 related to the usage of Docutils and reStructuredText.  (Please be
 sure to check the FAQ_ first.)
@@ -68,18 +56,6 @@ resend your message using a different email address.
 Doc-SIG
 -------
 
-.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
-    group=gmane.comp.python.documentation&
-    title=Posting+rate+for+Doc-SIG
-   :target: http://gmane.org/plot-rate.php?width=600&height=300&
-    group=gmane.comp.python.documentation&
-    title=Posting+rate+for+Doc-SIG
-   :alt: Posting rate for Doc-SIG
-   :width: 300
-   :height: 150
-   :align: right
-   :class: borderless
-
 The "Python Documentation Special Interest Group" (Doc-SIG) mailing
 list is occasionally used to discuss the usage of Docutils for Python
 documentation.
@@ -96,18 +72,6 @@ __ nntp://news.gmane.org/gmane.comp.python.documentation
 Docutils-develop
 ----------------
 
-.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
-    group=gmane.text.docutils.devel&
-    title=Posting+rate+for+Docutils-develop
-   :target: http://gmane.org/plot-rate.php?width=600&height=300&
-    group=gmane.text.docutils.devel&
-    title=Posting+rate+for+Docutils-develop
-   :alt: Posting rate for Docutils-develop
-   :width: 300
-   :height: 150
-   :align: right
-   :class: borderless
-
 Discussions about developing and extending Docutils take place on the
 Docutils-develop mailing list.
 
@@ -123,18 +87,6 @@ __ nntp://news.gmane.org/gmane.text.docutils.devel
 Docutils-checkins
 -----------------
 
-.. image:: http://gmane.org/plot-rate.php?width=300&height=150&
-    group=gmane.text.docutils.cvs&
-    title=Posting+rate+for+Docutils-checkins
-   :target: http://gmane.org/plot-rate.php?width=600&height=300&
-    group=gmane.text.docutils.cvs&
-    title=Posting+rate+for+Docutils-checkins
-   :alt: Posting rate for Docutils-checkins
-   :width: 300
-   :height: 150
-   :align: right
-   :class: borderless
-
 All check-ins to the `Subversion repository`_ cause a "check-in email"
 to the Docutils-checkins list.  In order to stay informed about
 current development, developers are advised to monitor this mailing
-- 
cgit v1.2.1


From 8aa5605c667d2b86b3ad0b41f3209720e2b3eae0 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 8 Jun 2005 13:49:42 +0000
Subject: added emphasis and clarification

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3453 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index f21ed470e..2bede5ffd 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -84,11 +84,16 @@ Conventions`_ PEPs, with the following clarifications and extensions:
   "note_explicit_target", "explicit_target").  If in doubt, use
   underscores.
 
-* Avoid functional constructs (lambda, filter, map, etc.).  Use list
+* Avoid lambda expressions, which are inherently difficult to
+  understand.  Named functions are preferable and superior: they're
+  faster (no run-time compilation), and well-chosen names serve to
+  document and aid understanding.
+
+* Avoid functional constructs (filter, map, etc.).  Use list
   comprehensions instead.
 
-* Avoid ``from __future__ import`` constructs; we don't want them in
-  production code.
+* Avoid ``from __future__ import`` constructs.  They are inappropriate
+  for production code.
 
 * Use 'single quotes' for string literals, and """triple double
   quotes""" for docstrings.
-- 
cgit v1.2.1


From 61075e34557635f6facec931b31da5ec3b04243c Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 9 Jun 2005 17:32:17 +0000
Subject: added "title" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3455 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt  | 15 +++++++++++++++
 docs/user/config.txt         |  8 ++++++++
 docs/user/rst/cheatsheet.txt |  1 +
 3 files changed, 24 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index dde952b7d..a0102f9e1 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -634,6 +634,21 @@ The following option is recognized:
     class_ directive below.
 
 
+Title
+=====
+
+:Directive Type: "title"
+:Doctree Element: None.
+:Directive Arguments: 1, required (the title text).
+:Directive Options: None.
+:Directive Content: None.
+
+The "title" directive specifies the document title as metadata, which
+does not become part of the document body.  It overrides a
+document-supplied title.  For example, in HTML output the metadata
+document title appears in the title bar of the browser window.
+
+
 --------
  Tables
 --------
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 66ad39234..fd75a16df 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -369,6 +369,14 @@ _`strict_visitor`
     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
     for development use only).
 
+-`title`
+    The document title as metadata, which does not become part of the
+    document body.  It overrides a document-supplied title.  For
+    example, in HTML output the metadata document title appears in the
+    title bar of the browser window.
+
+    Default: none.  Option: ``--title``.
+
 _`toc_backlinks`
     Enable backlinks from section titles to table of contents entries
     ("entry"), to the top of the TOC ("top"), or disable ("none").
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 7ae1d55f5..2142d9ce0 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -101,6 +101,7 @@ unicode           Unicode character code conversion for substitution defs
 class             Set a "class" attribute on the next element
 role              Create a custom interpreted text role [0.3.2]
 default-role      Set the default interpreted text role [0.3.10]
+title             Set the metadata document title [0.3.10]
 ================  ============================================================
 
 Interpreted Text Role Quick Reference
-- 
cgit v1.2.1


From dbab7e3441e11bf2bed00c53314191aefa808eed Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 9 Jun 2005 17:37:49 +0000
Subject: removed item; done with "title" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3456 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 4f4509dfc..5d6186b2a 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1774,9 +1774,6 @@ HTML Writer
 * 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  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:
-- 
cgit v1.2.1


From ac610390f0e3da3f10f8faf06017062c862c6e60 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 11 Jun 2005 03:17:27 +0000
Subject: removed implemented idea

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3466 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5d6186b2a..a806bc0cf 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1192,9 +1192,6 @@ when used in a document.
 
   - _`misc.include`:
 
-    - "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?
-- 
cgit v1.2.1


From d37a0a8fed7d6df884502b52da032379c5ff067b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 12 Jun 2005 04:20:01 +0000
Subject: removed redundancy with "encoding" option description

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3469 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index a0102f9e1..6ea521ac1 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1197,9 +1197,6 @@ example::
 If an included document fragment contains section structure, the title
 adornments must match those of the master document.
 
-The text encoding of the master input source is used for included
-files.
-
 The following options are recognized:
 
 ``literal`` : flag (empty)
-- 
cgit v1.2.1


From ad8ed1d2dabfec3f3f0ab51f03355adc25cdb77d Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 12 Jun 2005 05:00:49 +0000
Subject: updated location

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3471 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 32 +++++++++++++++++---------------
 1 file changed, 17 insertions(+), 15 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 6ea521ac1..bdcf3ac1f 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -634,21 +634,6 @@ The following option is recognized:
     class_ directive below.
 
 
-Title
-=====
-
-:Directive Type: "title"
-:Doctree Element: None.
-:Directive Arguments: 1, required (the title text).
-:Directive Options: None.
-:Directive Content: None.
-
-The "title" directive specifies the document title as metadata, which
-does not become part of the document body.  It overrides a
-document-supplied title.  For example, in HTML output the metadata
-document title appears in the title bar of the browser window.
-
-
 --------
  Tables
 --------
@@ -1597,6 +1582,23 @@ initial default interpreted text role of the standard reStructuredText
 parser is "title-reference".
 
 
+.. _title:
+
+Metadata Document Title
+=======================
+
+:Directive Type: "title"
+:Doctree Element: None.
+:Directive Arguments: 1, required (the title text).
+:Directive Options: None.
+:Directive Content: None.
+
+The "title" directive specifies the document title as metadata, which
+does not become part of the document body.  It overrides a
+document-supplied title.  For example, in HTML output the metadata
+document title appears in the title bar of the browser window.
+
+
 Restructuredtext-Test-Directive
 ===============================
 
-- 
cgit v1.2.1


From 3b7a7200860068db23463a6a4246c19814012ee9 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 12 Jun 2005 16:40:14 +0000
Subject: Added standard data file syntax to the "include" directive.  Added
 docutils/parsers/rst/include/ directory; contains the standard data files,
 with character entity substitution definition sets as initial contents. 
 Added docs/ref/rst/substitutions.txt: "reStructuredText Standard Substitution
 Definition Sets".  Updated docs, tests, & setup.py.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3472 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt              |  39 ++----------
 docs/index.txt                 |   2 +
 docs/ref/rst/directives.txt    |  16 ++++-
 docs/ref/rst/substitutions.txt | 134 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 155 insertions(+), 36 deletions(-)
 create mode 100644 docs/ref/rst/substitutions.txt

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index a806bc0cf..016388305 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -905,11 +905,6 @@ __ rst/alternatives.html#or-not-to-do
 * Generalize the "target-notes" directive into a command-line option
   somehow?  See docutils-develop 2003-02-13.
 
-* Include 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?
 
@@ -1196,38 +1191,12 @@ when used in a document.
 
     - Option to label lines?
 
-    - Default directory for "built-in includes", using the C syntax
-      ``<name>`` (as in ``#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
+    - How about an environment variable, say RSTINCLUDEPATH or
+      RSTPATH, for standard includes (as in ``.. include:: <name>``)?
+      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?
-
-    - Add support for inclusion by URL::
+    - Add support for inclusion by URL? ::
 
           .. include::
              :url: http://www.example.org/inclusion.txt
diff --git a/docs/index.txt b/docs/index.txt
index 67849d393..c8a933ac7 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -119,6 +119,8 @@ reStructuredText_:
 * `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
 * `reStructuredText Directives <ref/rst/directives.html>`__
 * `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
+* `reStructuredText Standard Substitution Definition Sets
+  <ref/rst/substitutions.html>`_
 
 Prehistoric:
 
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index bdcf3ac1f..cf5c20361 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1149,7 +1149,7 @@ Including an External Document Fragment
 
 :Directive Type: "include"
 :Doctree Elements: depend on data being included
-:Directive Arguments: One, required.
+:Directive Arguments: One, required (path to the file to include).
 :Directive Options: Possible.
 :Directive Content: None.
 
@@ -1182,6 +1182,20 @@ example::
 If an included document fragment contains section structure, the title
 adornments must match those of the master document.
 
+Standard data files intended for inclusion in reStructuredText
+documents are distributed with the Docutils source code, located in
+the "docutils" package in the ``docutils/parsers/rst/include``
+directory.  To access these files, use the special syntax for standard
+"include" data files, angle brackets around the file name::
+
+    .. include:: <isonum.txt>
+
+The current set of standard "include" data files consists of sets of
+substitution definitions.  See `reStructuredText Standard Substitution
+Definition Sets`__ for details of the available standard data files.
+
+__ substitutions.html
+
 The following options are recognized:
 
 ``literal`` : flag (empty)
diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt
new file mode 100644
index 000000000..3ddb71123
--- /dev/null
+++ b/docs/ref/rst/substitutions.txt
@@ -0,0 +1,134 @@
+========================================================
+ reStructuredText Standard Substitution Definition Sets
+========================================================
+:Author: David Goodger
+:Contact: goodger@python.org
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+The data files described below contain sets of reStructuredText
+`substitution definitions`__.  They can be included in documents using
+the `"include" directive's`__ special syntax for standard data files,
+angle brackets around the file name::
+
+    .. include:: <filename.txt>
+
+__ restructuredtext.html#substitution-definitions
+__ directives.html#include
+
+The definitions can then be used in documents using `substitution
+references`__.  For example, the copyright symbol is defined in
+``isonum.txt`` as "copy"::
+
+    .. include:: <isonum.txt>
+
+    Copyright |copy| 2003 by John Q. Public, all rights reserved.
+
+__ restructuredtext.html#substitution-references
+
+Individual definitions can also be copied from these data files and
+pasted into documents.  This has two advantages: it removes
+dependencies, and it saves processing of unused definitions.  However,
+multiple substitution definitions add clutter to the document.
+
+Substitution references require separation from the surrounding text
+with whitespace or punctuation.  To use a substitution without
+intervening whitespace, you can use the disappearing-whitespace escape
+sequence, backslash-space::
+
+    .. include:: isonum.txt
+
+    Copyright |copy| 2003, BogusMegaCorp\ |trade|.
+
+Custom definitions may use the `"unicode" directive`__.  Whitespace is
+ignored and removed, effectively sqeezing together the text::
+
+    .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
+
+    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+
+__ directives.html#unicode
+
+In addition, the "ltrim", "rtrim", and "trim" options may be used with
+the "unicode" directive to automatically trim spaces from the left,
+right, or both sides (respectively) of substitution references::
+
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
+
+The individual data files are stored with the Docutils source code in
+the "docutils" package, in the ``docutils/parsers/rst/include``
+directory.
+
+
+Character Entity Sets
+=====================
+
+The following files contain substitution definitions corresponding to
+XML character entity sets, from the following standards: ISO 8879 &
+ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
+the ``tools/unicode2rstsubs.py`` program from the input file
+unicode.xml__, which is maintained as part of the MathML 2
+Recommentation XML source.
+
+__ http://www.w3.org/2003/entities/xml/
+
+==================  ==================================================
+Entity Set File    Description
+==================  ==================================================
+isoamsa.txt         Added Mathematical Symbols: Arrows
+isoamsb.txt         Added Mathematical Symbols: Binary Operators
+isoamsc.txt         Added Mathematical Symbols: Delimiters
+isoamsn.txt         Added Mathematical Symbols: Negated Relations
+isoamso.txt         Added Mathematical Symbols: Ordinary
+isoamsr.txt         Added Mathematical Symbols: Relations
+isobox.txt          Box and Line Drawing
+isocyr1.txt         Russian Cyrillic
+isocyr2.txt         Non-Russian Cyrillic
+isodia.txt          Diacritical Marks
+isogrk1.txt         Greek Letters
+isogrk2.txt         Monotoniko Greek
+isogrk3.txt         Greek Symbols
+isogrk4.txt  [1]_   Alternative Greek Symbols
+isolat1.txt         Added Latin 1
+isolat2.txt         Added Latin 2
+isomfrk.txt  [1]_   Mathematical Fraktur
+isomopf.txt  [1]_   Mathematical Openface (Double-struck)
+isomscr.txt  [1]_   Mathematical Script
+isonum.txt          Numeric and Special Graphic
+isopub.txt          Publishing
+isotech.txt         General Technical
+mmlalias.txt        MathML aliases for entities from other sets
+mmlextra.txt [1]_   Extra names added by MathML
+xhtml4-lat1.txt     XHTML Latin 1
+xhtml4-special.txt  XHTML Special Characters
+xhtml4-symbol.txt   XHTML Mathematical, Greek and Symbolic Characters
+==================  ==================================================
+
+.. [1] There are ``*-wide.txt`` variants for each of these character
+   entity set files, containing characters outside of the Unicode
+   basic multilingual plane or BMP (wide-Unicode; code points greater
+   than U+FFFF).  Most pre-built Python distributions are "narrow" and
+   do not support wide-Unicode characters.  Python *can* be built with
+   wide-Unicode support though; consult the Python build instructions
+   for details.
+
+For example, the copyright symbol is defined as the XML character
+entity ``©``.  The equivalent reStructuredText substitution
+reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
+``|copy|``.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
-- 
cgit v1.2.1


From 530bfbe824e80b0996edf5961ccf63d93f542afd Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 12 Jun 2005 16:44:50 +0000
Subject: correction

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3473 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/substitutions.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt
index 3ddb71123..d4ff17a42 100644
--- a/docs/ref/rst/substitutions.txt
+++ b/docs/ref/rst/substitutions.txt
@@ -80,7 +80,7 @@ Recommentation XML source.
 __ http://www.w3.org/2003/entities/xml/
 
 ==================  ==================================================
-Entity Set File    Description
+Entity Set File     Description
 ==================  ==================================================
 isoamsa.txt         Added Mathematical Symbols: Arrows
 isoamsb.txt         Added Mathematical Symbols: Binary Operators
-- 
cgit v1.2.1


From 03b1c8e2a42aa2987828cccef1a99d6c9ebafdec Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 13 Jun 2005 03:22:17 +0000
Subject: removed implemented item

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3476 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 016388305..1b201598a 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -33,10 +33,6 @@ Priorities
 
   __ ../../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!
-- 
cgit v1.2.1


From eea838e5d1dc2071e2c50315d740c6ff495ebdf5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 15 Jun 2005 22:28:26 +0000
Subject: added link targets

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3479 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index c8a933ac7..08fbddcf0 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -71,6 +71,8 @@ top level of the Docutils project directory.
 .. _THANKS.txt: ../THANKS.html
 
 
+.. _user:
+
 ``user/``: Introductory & Tutorial Material for End-Users
 =========================================================
 
@@ -93,6 +95,8 @@ Docutils-general:
   look at the `text source <user/rst/demo.txt>`__)
 
 
+.. _ref:
+
 ``ref/``: Reference Material for All Groups
 ===========================================
 
@@ -128,6 +132,8 @@ Prehistoric:
   <http://docutils.sourceforge.net/mirror/setext.html>`__
 
 
+.. _peps:
+
 ``peps/``: Python Enhancement Proposals
 =======================================
 
@@ -156,6 +162,8 @@ __ http://www.python.org/peps/pep-0287.html
 .. _master repository: http://www.python.org/peps/
 
 
+.. _api:
+
 ``api/``: API Reference Material for Client-Developers
 ======================================================
 
@@ -167,6 +175,8 @@ __ http://www.python.org/peps/pep-0287.html
 `PEP 258`_ is an overview of the architecture of Docutils.
 
 
+.. _howto:
+
 ``howto/``: Instructions for Developers
 =======================================
 
@@ -176,6 +186,8 @@ __ http://www.python.org/peps/pep-0287.html
   <howto/rst-roles.html>`__
 
 
+.. _dev:
+
 ``dev/``: Development Notes and Plans for Core-Developers
 =========================================================
 
-- 
cgit v1.2.1


From 9425c5e74a7324d830f0484ccf1d9eedb76c4aa6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 15 Jun 2005 23:33:44 +0000
Subject: moved links from sandbox/README.txt to links.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3486 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 73 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 466f8a8ee..ea9460168 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -2,6 +2,8 @@
  Docutils_ Links
 =================
 
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
@@ -11,8 +13,76 @@
 The most current version of this document can always be found at
 http://docutils.sourceforge.net/docs/user/links.html.
 
-* rest2web__ is a tool for creating web sites with reStructuredText.
 
-  __ http://article.gmane.org/gmane.text.docutils.user/2006
+Related Projects
+================
 
-* to be continued...
+These are projects users of Docutils and reStructuredText may find
+useful.  Many of them projects are hosted in the `Docutils Sandbox`_.
+All projects are usable by end users in some way, however do not
+expect all of them to run out of the box.
+
+* rest2web_, by Michael Foord, is a tool for creating web sites with
+  reStructuredText.
+
+* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope"
+  application that is complete and ready to install.
+
+* PySource_, by Tony Ibbs, is an experimental Python source Reader.
+  In some form, it will soon become part of core Docutils.  There is
+  some related code in David Goodger's sandbox (pysource_reader_) and
+  a `Python Source Reader`_ document.
+
+  .. Is this usable for end users?  Maybe move to a "Developers"
+     section?
+
+* The Docutils interface to PythonPoint_, also by Richard Jones,
+  produces PDF presentations using ReportLabs.
+
+* Engelbert Gruber has begun a `ManPage Writer`_.
+
+* Sidnei da Silva has taken over `ReportLabs/PDF Writer`_ components.
+
+  .. Can anyone confirm that this works and maybe provide installation
+     instructions?  (Emailed Sidnei about that.)
+
+* Oliver Rutherfurd has begun a `DocBook Writer`_ component and
+  `HT2HTML integration`_ component.
+
+* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
+  Docutils.
+
+* Aahz has begun an `OpenOffice.org Writer`_.
+
+  .. Can anyone confirm that this works and maybe provide installation
+     instructions?  (Emailed Aahz about that.)
+
+* For Wikis, please see the `FAQ entry about Wikis`_.
+
+* Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely
+  on CSS (stylesheets).
+
+* Beni Cherniavsky has written a generic `preprocessing module`_ for
+  roles and/or directives and built preprocessors for TeX math for
+  both LaTeX and HTML output on top of it.
+
+* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
+  to handle everything one might do with docutils.
+
+.. _rest2web: http://www.voidspace.org.uk/python/rest2web/
+.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
+.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
+.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/
+.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/
+.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
+.. _PythonPoint: http://docutils.sf.net/sandbox/richard/pythonpoint/
+.. _Manpage Writer: http://docutils.sf.net/sandbox/grubert/man/
+.. _ReportLabs/PDF Writer: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
+.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
+.. _HT2HTML integration: http://docutils.sf.net/sandbox/oliverr/ht/
+.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
+.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/aahz/OO/
+.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
+.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
+.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
+.. _Makefile: http://docutils.sf.net/sandbox/cben/make/
-- 
cgit v1.2.1


From 09e012ec57acc45f8d56ee2f176c03f1ffab1862 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 16 Jun 2005 00:37:34 +0000
Subject: added link target; removed reference to fixed bug; removed other idea
 -- looks bad

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3493 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 19 +++++--------------
 1 file changed, 5 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 1b201598a..3509a87c5 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -949,7 +949,7 @@ __ rst/alternatives.html#or-not-to-do
   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.) ::
+  _`literal block without a blank line`?  (Idea from Paul Moore.) ::
 
       ::
           This is a literal block
@@ -958,25 +958,16 @@ __ rst/alternatives.html#or-not-to-do
   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
+  escape it.  Currenty, ``:\:`` is misinterpreted as a field name
+  (name ``\``; **bug**).  Assuming this bug is 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>`__.
-- 
cgit v1.2.1


From bea16992178d8ce87ce5e315d459beb7905cd14e Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 16 Jun 2005 01:08:33 +0000
Subject: removed link to PDF writer; Sidnei says it's probably not functional;
 he hasn't used it for ages

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3495 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 5 -----
 1 file changed, 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index ea9460168..1e463e0a2 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -41,11 +41,6 @@ expect all of them to run out of the box.
 
 * Engelbert Gruber has begun a `ManPage Writer`_.
 
-* Sidnei da Silva has taken over `ReportLabs/PDF Writer`_ components.
-
-  .. Can anyone confirm that this works and maybe provide installation
-     instructions?  (Emailed Sidnei about that.)
-
 * Oliver Rutherfurd has begun a `DocBook Writer`_ component and
   `HT2HTML integration`_ component.
 
-- 
cgit v1.2.1


From 04f2424447e9de96e74c65e24d68fab32bfa33e3 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 16 Jun 2005 22:03:08 +0000
Subject: added support for units in image widths and heights; I called a
 number combined with a unit (e.g. 5em) a "measure"; I am not entirely sure if
 that's the right term, though

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3497 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/docutils.dtd             |  7 +++++--
 docs/ref/rst/directives.txt       |  8 ++++++++
 docs/ref/rst/restructuredtext.txt | 40 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index f3a7d37ca..fd47b6c91 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -39,6 +39,9 @@ by wrapper DTDs.
 <!-- Emphasize that the attribute value must be a number. -->
 <!ENTITY % number  "NMTOKEN">
 
+<!-- A number which may be immediately followed by a unit. -->
+<!ENTITY % measure "NMTOKEN">
+
 <!ENTITY % additional.basic.atts "">
 <!--
 Attributes shared by all elements in this DTD:
@@ -481,8 +484,8 @@ or " ") or the text between option arguments (typically either "," or
     %align-hv.att;
     uri       CDATA     #REQUIRED
     alt       CDATA     #IMPLIED
-    height    %number;  #IMPLIED
-    width     %number;  #IMPLIED
+    height    %measure; #IMPLIED
+    width     %measure; #IMPLIED
     scale     %number;  #IMPLIED>
 
 <!ELEMENT caption %text.model;>
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index cf5c20361..2235c428f 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -202,11 +202,19 @@ The following options are recognized:
     specified, they are combined.  For example, a height of 200 and a
     scale of 50 is equivalent to a height of 100 with no scale.
 
+    It is also possible to specify a `length value`_.
+
 ``width`` : integer
     The width of the image in pixels, used to reserve space or scale
     the image horizontally.  As with "height" above, when the "scale"
     option is also specified, they are combined.
 
+    It is also possible to specify a length_ or `percentage value`_.
+
+    .. _length:
+    .. _length value: restructuredtext.html#length-units
+    .. _percentage value: restructuredtext.html#percentage-units
+
 ``scale`` : integer
     The uniform scaling factor of the image, a percentage (but no "%"
     symbol is required or allowed).  "100" means full-size, and is
diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 6d21934b4..0823cc8eb 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2781,6 +2781,46 @@ characters (see `Escaping Mechanism`_ above).
    RFC2396_ and RFC2732_.
 
 
+Units
+=====
+
+All measures consist of a positive floating point number in standard
+(non-scientific) notation and a unit, possibly separated by one or
+more spaces.
+
+Units are only supported where explicitly mentioned in the reference
+manuals.
+
+
+Length Units
+------------
+
+The following length units are supported by the reStructuredText
+parser:
+
+* em (ems, the height of the element's font)
+* ex (x-height, the height of the letter "x")
+* px (pixels, relative to the canvas resolution)
+* in (inches; 1in=2.54cm)
+* cm (centimeters; 1cm=10mm)
+* mm (millimeters)
+* pt (points; 1pt=1/72in)
+* pc (picas; 1pc=12pt)
+
+(List and explanations taken from
+http://www.htmlhelp.com/reference/css/units.html#length.)
+
+The following are all valid length values: "1.5em", "20 mm", ".5in".
+
+
+Percentage Units
+----------------
+
+Percentage values have a percent sign ("%") as unit.  Percentage
+values are relative to other values, depending on the context in which
+they occur.
+
+
 ----------------
  Error Handling
 ----------------
-- 
cgit v1.2.1


From 5b01b700102eafc5edc5284f17b9055dc7d24e20 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 16 Jun 2005 22:04:32 +0000
Subject: removed to do list entries: image.border: bad idea; units of measure:
 implemented

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3498 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 -------
 1 file changed, 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 3509a87c5..481a99142 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1106,13 +1106,6 @@ when used in a document.
     .. _unicode:
        http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
 
-  - _`images.image`: "border"?  No, bad idea; use CSS instead.
-
-    _`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?
 
-- 
cgit v1.2.1


From 1ff93dd94d3e3b0d398f88a6cfa3ece4558ef8ad Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 16 Jun 2005 22:07:31 +0000
Subject: documented what image widths as percentage are relative to

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3499 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 2235c428f..73614b043 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -209,7 +209,8 @@ The following options are recognized:
     the image horizontally.  As with "height" above, when the "scale"
     option is also specified, they are combined.
 
-    It is also possible to specify a length_ or `percentage value`_.
+    It is also possible to specify a length_ or `percentage value`_
+    (which is relative to the current line width).
 
     .. _length:
     .. _length value: restructuredtext.html#length-units
-- 
cgit v1.2.1


From 8b7c50c33f64055a2be9342baadeb836dc07d6c8 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 17 Jun 2005 00:05:32 +0000
Subject: updated link to OpenOffice writer; Aahz says Patrick has a more
 recent version (a quick test shows that it works)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3502 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 1e463e0a2..313fb84f8 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -47,10 +47,7 @@ expect all of them to run out of the box.
 * Gunnar Schwant's DocFactory_ is a wxPython GUI application for
   Docutils.
 
-* Aahz has begun an `OpenOffice.org Writer`_.
-
-  .. Can anyone confirm that this works and maybe provide installation
-     instructions?  (Emailed Aahz about that.)
+* Patrick O'Brien has taken over the `OpenOffice.org Writer`_.
 
 * For Wikis, please see the `FAQ entry about Wikis`_.
 
@@ -76,7 +73,7 @@ expect all of them to run out of the box.
 .. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
 .. _HT2HTML integration: http://docutils.sf.net/sandbox/oliverr/ht/
 .. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
-.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/aahz/OO/
+.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
-- 
cgit v1.2.1


From efefd166b752519c6af782b182d87963a8e47f30 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 17 Jun 2005 13:46:10 +0000
Subject: corrected internal links; improved layout a bit

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3503 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/quickref.html | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html
index e391763c2..cdda16c68 100644
--- a/docs/user/rst/quickref.html
+++ b/docs/user/rst/quickref.html
@@ -123,14 +123,14 @@
       <td nowrap><samp>reference_</samp>
       <td><a href="#hyperlink-targets">reference</a>
       <td>A simple, one-word hyperlink reference.  See <a
-      href="#hyperlinks" >Hyperlinks</a>.
+      href="#hyperlink-targets">Hyperlink Targets</a>.
 
     <tr valign="top">
       <td nowrap><samp>`phrase reference`_</samp>
       <td><a href="#hyperlink-targets">phrase reference</a>
       <td>A hyperlink reference with spaces or punctuation needs to be
       quoted with backquotes.  See <a
-      href="#hyperlink-targets">Hyperlinks</a>.
+      href="#hyperlink-targets">Hyperlink Targets</a>.
 
     <tr valign="top">
       <td nowrap><samp>anonymous__</samp>
@@ -138,13 +138,13 @@
       <td>With two underscores instead of one, both simple and phrase
       references may be anonymous (the reference text is not repeated
       at the target).  See <a
-      href="#hyperlink-targets">Hyperlinks</a>.
+      href="#hyperlink-targets">Hyperlink Targets</a>.
 
     <tr valign="top">
       <td nowrap><samp>_`inline internal target`</samp>
       <td><a name="inline-internal-target">inline internal target</a>
       <td>A crossreference target within text.
-      See <a href="#hyperlink-targets">Hyperlinks</a>.
+      See <a href="#hyperlink-targets">Hyperlink Targets</a>.
 
     <tr valign="top">
       <td nowrap><samp>|substitution reference|</samp>
@@ -1063,7 +1063,7 @@ A transition marker is a horizontal line
       <tbody>
 
     <tr valign="top">
-      <td>
+      <td rowspan="2">
         <samp>External hyperlinks, like Python_.</samp>
 
         <p><samp>.. _Python: http://www.python.org/</samp>
@@ -1072,6 +1072,10 @@ A transition marker is a horizontal line
           <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
           <tr><td>Indirect hyperlinks, like
           <a href="http://www.python.org">Python</a>.
+        </table>
+    <tr valign="top">
+      <td>
+        <table width="100%">
           <tr bgcolor="#99CCFF"><td><em>Call-out form</em>
           <tr><td>External hyperlinks, like
           <a href="#labPython"><i>Python</i></a>.
@@ -1102,7 +1106,7 @@ A transition marker is a horizontal line
       <tbody>
 
     <tr valign="top">
-      <td><samp>Internal crossreferences, like example_.</samp>
+      <td rowspan="2"><samp>Internal crossreferences, like example_.</samp>
 
         <p><samp>.. _example:</samp>
 
@@ -1117,6 +1121,10 @@ A transition marker is a horizontal line
           <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a>
           <p><a name="example-foldin">This</a> is an example
             crossreference target.
+        </table>
+    <tr valign="top">
+      <td>
+        <table width="100%">
           <tr><td bgcolor="#99CCFF"><em>Call-out form</em>
           <tr><td>Internal crossreferences, like <a href="#example-callout">example</a>
 
-- 
cgit v1.2.1


From d1368a7bed991b9a20a12b51373ccf974c23cad0 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 17 Jun 2005 14:19:17 +0000
Subject: added link to default-role directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3504 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/roles.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index 1cb2e540b..b396af2eb 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -1,6 +1,7 @@
 =========================================
  reStructuredText Interpreted Text Roles
 =========================================
+
 :Author: David Goodger
 :Contact: goodger@users.sourceforge.net
 :Revision: $Revision$
@@ -20,7 +21,8 @@ with colons.  For example::
 
 A default role may be defined by applications of reStructuredText; it
 is used if no explicit ``:role:`` prefix or suffix is given.  The
-"default default role" is `:title-reference:`_.
+"default default role" is `:title-reference:`_.  It can be changed
+using the default-role_ directive.
 
 See the `Interpreted Text`_ section in the `reStructuredText Markup
 Specification`_ for syntax details.  For details on the hierarchy of
@@ -30,6 +32,7 @@ implementation details, see `Creating reStructuredText Interpreted
 Text Roles`_.
 
 .. _"role" directive: directives.html#role
+.. _default-role: directives.html#default-role
 .. _Interpreted Text: restructuredtext.html#interpreted-text
 .. _reStructuredText Markup Specification: restructuredtext.html
 .. _The Docutils Document Tree: ../doctree.html
-- 
cgit v1.2.1


From 25229d1cf6672933c6d9d50e9b0c656265dceab3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 17 Jun 2005 15:12:51 +0000
Subject: added embedded URI example; corrected link

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3505 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/quickref.html | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html
index cdda16c68..fdb9a8adb 100644
--- a/docs/user/rst/quickref.html
+++ b/docs/user/rst/quickref.html
@@ -1070,8 +1070,8 @@ A transition marker is a horizontal line
       <td>
         <table width="100%">
           <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
-          <tr><td>Indirect hyperlinks, like
-          <a href="http://www.python.org">Python</a>.
+          <tr><td>External hyperlinks, like
+          <a href="http://www.python.org/">Python</a>.
         </table>
     <tr valign="top">
       <td>
@@ -1094,6 +1094,28 @@ A transition marker is a horizontal line
       printed documents, where the link needs to be presented explicitly, for
       example as a footnote.
 
+    <p>reStructuredText also provides for <b>embedded URIs</b> (<a
+      href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>),
+      a convenience at the expense of readability.  A hyperlink
+      reference may directly embed a target URI inline, within angle
+      brackets.  The following is exactly equivalent to the example above:
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td rowspan="2">
+        <samp>External hyperlinks, like `Python
+<br><http://www.python.org/>`_.</samp>
+      <td>External hyperlinks, like
+          <a href="http://www.python.org/">Python</a>.
+    </table>
+
     <h4><a href="#contents" name="internal-hyperlink-targets" class="backref"
         >Internal Hyperlink Targets</a></h4>
 
-- 
cgit v1.2.1


From 7fcc4af21966bb94d513017d40c68cc8335640f7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 17 Jun 2005 15:20:28 +0000
Subject: added "New in Docutils 3.4.10" for units

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3506 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt       | 8 +++++---
 docs/ref/rst/restructuredtext.txt | 2 ++
 2 files changed, 7 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 73614b043..73c0b39ca 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -202,15 +202,17 @@ The following options are recognized:
     specified, they are combined.  For example, a height of 200 and a
     scale of 50 is equivalent to a height of 100 with no scale.
 
-    It is also possible to specify a `length value`_.
+    New in Docutils 3.4.10: It is also possible to specify a `length
+    value`_.
 
 ``width`` : integer
     The width of the image in pixels, used to reserve space or scale
     the image horizontally.  As with "height" above, when the "scale"
     option is also specified, they are combined.
 
-    It is also possible to specify a length_ or `percentage value`_
-    (which is relative to the current line width).
+    New in Docutils 3.4.10: It is also possible to specify a length_
+    or `percentage value`_ (which is relative to the current line
+    width).
 
     .. _length:
     .. _length value: restructuredtext.html#length-units
diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 0823cc8eb..2282beac2 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2784,6 +2784,8 @@ characters (see `Escaping Mechanism`_ above).
 Units
 =====
 
+(New in Docutils 3.4.10.)
+
 All measures consist of a positive floating point number in standard
 (non-scientific) notation and a unit, possibly separated by one or
 more spaces.
-- 
cgit v1.2.1


From 4220823618786ebcf147ce3dee195b6acdd4bb00 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 18 Jun 2005 00:09:14 +0000
Subject: added link to rst2chm

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3510 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 313fb84f8..22c8a9706 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -18,9 +18,13 @@ Related Projects
 ================
 
 These are projects users of Docutils and reStructuredText may find
-useful.  Many of them projects are hosted in the `Docutils Sandbox`_.
-All projects are usable by end users in some way, however do not
-expect all of them to run out of the box.
+useful, listed in no particular order.  Many of them projects are
+hosted in the `Docutils Sandbox`_.  All projects are usable by end
+users in some way, however do not expect all of them to run out of the
+box.
+
+* rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML
+  Help files from reStructuredText files.
 
 * rest2web_, by Michael Foord, is a tool for creating web sites with
   reStructuredText.
@@ -61,6 +65,7 @@ expect all of them to run out of the box.
 * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
   to handle everything one might do with docutils.
 
+.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 .. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
 .. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
-- 
cgit v1.2.1


From b30cbb0571acc552f53b3021ad9c63508a14330c Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 19 Jun 2005 15:26:13 +0000
Subject: made xmlcharrefreplace the default output encoding error handler for
 HTML and XML writer

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3512 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ----
 1 file changed, 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 481a99142..2727aeb43 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -122,10 +122,6 @@ General
   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
-- 
cgit v1.2.1


From 150b5f5083d215326c040df4393413379f62e8f4 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 17:57:40 +0000
Subject: added Distributor's Guide; if there is agreement on this installation
 procedure, I'll send email to the package maintainers

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3527 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 159 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.txt            |   1 +
 2 files changed, 160 insertions(+)
 create mode 100644 docs/dev/distributing.txt

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
new file mode 100644
index 000000000..f7979a62f
--- /dev/null
+++ b/docs/dev/distributing.txt
@@ -0,0 +1,159 @@
+.. -*- coding: utf-8 -*-
+
+===============================
+ Docutils_ Distributor's Guide
+===============================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+This document describes how to create packages of Docutils (e.g. for
+shipping them with a Linux distribution).  If you have any questions,
+please direct them to the Docutils-develop_ mailing list.
+
+First of all, please download the most current `release tarball`_ and
+unpack it.
+
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+.. _release tarball: http://docutils.sourceforge.net/#download
+
+
+Dependencies
+============
+
+Docutils has the following dependencies:
+
+* Python 2.1 or later is required.  (While the compiler package from
+  the Tools/ directory of Python's source distribution must be
+  installed for the test suite to pass with Python 2.1, the
+  functionality available to end users should be available without the
+  compiler package as well.  So just use >= Python 2.1 in the
+  dependencies.)
+
+* Docutils may optionally make use of the PIL (Python Imaging
+  Library).  If PIL is present, it is automatically detected by
+  Docutils.
+
+* There are three files in the ``extras/`` directory of the Docutils
+  distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``.
+  For Python 2.1/2.2, all of them must be installed (into the
+  ``site-packages/`` directory).  Python 2.3 and later versions have
+  ``textwrap`` and ``optparse`` included in the standard library, so
+  only ``roman.py`` is required here; installing the other files won't
+  hurt, though.
+
+  These files are automatically installed by the setup script (when
+  calling "python setup.py install").
+
+
+Python Files
+============
+
+The Docutils Python files must be installed into the
+``site-packages/`` directory of Python.  Running ``python setup.py
+install`` should do the trick, but if you want to place the files
+yourself, you can just install the ``docutils/`` directory of the
+Docutils tarball to ``/usr/lib/python/site-packages/docutils/``.  In
+this case you should also compile the Python files to ``.pyc`` and/or
+``.pyo`` files so that Docutils doesn't need to be recompiled
+everytime it's executed.
+
+
+Binaries
+========
+
+The binaries are located in the ``tools/`` directory of the Docutils
+tarball.
+
+The ``rst2*.py`` tools except ``rst2newlatex.py`` are intended for
+end-users.  You should install them to ``/usr/bin/``.  You do not need
+to change the names (e.g. to ``docutils-rst2html.py``) because the
+``rst2`` prefix is unique.
+
+
+Documentation
+=============
+
+The documentation should be generated using ``buildhtml.py``.  Go to
+the ``tools/`` directory and run ``./buildhtml.py ..``.  This will
+create all HTML files.
+
+Then install the following files to ``/usr/share/doc/docutils/`` (or
+however you like to call the documentation directory):
+
+* All ``.html`` and ``.txt`` files in the base directory.
+* The ``docs/`` directory.  (Do not install the contents of the
+  ``docs/`` directory directory directly to
+  ``/usr/share/doc/docutils/``—it's incomplete and would contain
+  invalid references!)
+* The ``licenses/`` directory.
+* ``tools/stylesheets/default.css``, creating the ``tools/`` and
+  ``tools/stylesheets/`` directory beforehand.  This file is needed
+  for correct viewing of the HTML files.  (You do not need to install
+  the other contents of the ``tools/`` or ``stylesheets/`` directory.
+  However, do not install ``default.css`` right into the documentation
+  base directory, or the references to the stylesheet will not work.)
+
+
+Removing the ``.txt`` Files
+---------------------------
+
+If you are tight with disk space, you can remove all ``.txt`` files in
+the tree except for:
+
+* those in the ``licenses/`` directory because they have not been
+  processed to HTML and
+* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
+  be readable in source form.
+
+Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
+as ``./buildhtml.py .. --no-source-link`` to avoid broken references
+to the source files.
+
+
+Other Files
+===========
+
+Install ``tools/stylesheets/`` to ``/usr/lib/docutils/stylesheets/``
+and ``tools/pep-html-template`` to
+``/usr/lib/docutils/pep-html-template``.
+
+You may also want to install the Emacs-Lisp files
+``tools/editors/emacs/*.el`` into the appropriate directory.
+
+
+Configuration File
+==================
+
+The system-wide configuration file is located in
+``/etc/docutils.conf``.  You should *not* install
+``tools/docutils.conf`` into ``/etc/``.  Instead, we recommend that
+you create a new ``/etc/docutils.conf`` file containing references to
+the appropriate files on your system::
+
+    [html4css1 writer]
+    # These entries affect HTML output:
+    stylesheet-path: /usr/lib/docutils/stylesheets/default.css
+
+    [pep_html writer]
+    # These entries affect reStructuredText-style PEPs:
+    template: /usr/lib/docutils/pep-html-template
+    stylesheet-path: /usr/lib/docutils/stylesheets/pep.css
+
+(Adjust the paths as necessary.)
+
+
+Tests
+=====
+
+While you probably do not need to ship the tests with your
+distribution, you can test your package by installing it and then
+running ``alltests.py`` from the ``tests/`` directory of the Docutils
+tarball.
diff --git a/docs/index.txt b/docs/index.txt
index 08fbddcf0..eeb8a5125 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -194,6 +194,7 @@ __ http://www.python.org/peps/pep-0287.html
 Docutils-general:
 
 * `Docutils Hacker's Guide <dev/hacking.html>`__
+* `Docutils Distributor's Guide <dev/distributing.html>`__
 * `Docutils To Do List <dev/todo.html>`__
 * `Docutils Project Policies <dev/policies.html>`__
 * `Docutils Web Site <dev/website.html>`__
-- 
cgit v1.2.1


From c38381105b2220a495e7cec712ede709417f23c8 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 18:02:01 +0000
Subject: corrected syntax error in distributing.txt; mmmh... the spec should
 be changed, this error is unnecessary

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3529 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index f7979a62f..05aa4f2c6 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -91,7 +91,7 @@ however you like to call the documentation directory):
 * All ``.html`` and ``.txt`` files in the base directory.
 * The ``docs/`` directory.  (Do not install the contents of the
   ``docs/`` directory directory directly to
-  ``/usr/share/doc/docutils/``—it's incomplete and would contain
+  ``/usr/share/doc/docutils/``\ —it's incomplete and would contain
   invalid references!)
 * The ``licenses/`` directory.
 * ``tools/stylesheets/default.css``, creating the ``tools/`` and
-- 
cgit v1.2.1


From fbc14fc4439455bc8726051604c4148ed14e29ee Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 19:12:33 +0000
Subject: renamed tools/pep.py to rstpep2html.py

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3533 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/tools.txt | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 9cd136988..28433005e 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -141,20 +141,20 @@ stylesheets override styles in imported stylesheets, enabling
 incremental experimentation.
 
 
-pep.py
-------
+rstpep2html.py
+--------------
 
 :Reader: PEP
 :Parser: reStructuredText
 :Writer: PEP/HTML
 
-``pep.py`` reads a new-style PEP (marked up with reStructuredText) and
-produces HTML.  It requires a template file and a stylesheet.  By
-default, it makes use of a "``pep-html-template``" file and a
-"``default.css``" stylesheet in the current directory, but these can
-be overridden by command-line options or configuration files.  The
-"``tools/stylesheets/pep.css``" stylesheet is intended specifically
-for PEP use.
+``rstpep2html.py`` reads a new-style PEP (marked up with
+reStructuredText) and produces HTML.  It requires a template file and
+a stylesheet.  By default, it makes use of a "``pep-html-template``"
+file and a "``default.css``" stylesheet in the current directory, but
+these can be overridden by command-line options or configuration
+files.  The "``tools/stylesheets/pep.css``" stylesheet is intended
+specifically for PEP use.
 
 The "``docutils.conf``" `configuration file`_ in the "``tools``"
 directory of Docutils contains a default setup for use in processing
@@ -163,17 +163,17 @@ default template (``tools/pep-html-template``) and a default
 stylesheet (``tools/stylesheets/pep.css``).  See Stylesheets_ above
 for more information.
 
-``pep.py`` can be run from the ``tools`` directory or from the
+``rstpep2html.py`` can be run from the ``tools`` directory or from the
 ``docs/peps/`` directory, by adjusting the settings.  These two sets
 of commands are equivalent::
 
     cd <path-to-docutils>/tools
     # This will pick up the "docutils.conf" file automatically:
-    pep.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html
+    rstpep2html.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html
 
     cd <path-to-docutils>/docs/peps
     # Must tell the tool where to find the config file:
-    ../../tools/pep.py --config ../../tools/docutils.conf \
+    ../../tools/rstpep2html.py --config ../../tools/docutils.conf \
         pep-0287.txt pep-0287.html
 
 
@@ -191,8 +191,8 @@ indented or new-style reStructuredText) and processes accordingly.
 Since it does not use the Docutils front end mechanism (the common
 command-line options are not supported), it can only be configured
 using `configuration files`_.  The template and stylesheet
-requirements of ``pep2html.py`` are the same as those of `pep.py`_
-above.
+requirements of ``pep2html.py`` are the same as those of
+`rstpep2html.py`_ above.
 
 Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
 files.  If no arguments are given, all files of the form
-- 
cgit v1.2.1


From 6d22d0350bced331e2eb4e70f6c557ab4fe1fd57 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 19:34:29 +0000
Subject: renamed "The Docutils Repository" to "The Docutils Subversion
 Repository"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3537 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 6 +++---
 docs/index.txt          | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 7a3cfde60..dceb88f5d 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -1,6 +1,6 @@
-==========================
- The Docutils_ Repository
-==========================
+=====================================
+ The Docutils_ Subversion Repository
+=====================================
 
 :Author: Felix Wiemann
 :Contact: Felix.Wiemann@ososo.de
diff --git a/docs/index.txt b/docs/index.txt
index eeb8a5125..222d6759e 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -199,7 +199,7 @@ Docutils-general:
 * `Docutils Project Policies <dev/policies.html>`__
 * `Docutils Web Site <dev/website.html>`__
 * `Docutils Release Procedure <dev/release.html>`__
-* `The Docutils Repository <dev/repository.html>`__
+* `The Docutils Subversion Repository <dev/repository.html>`__
 * `Docutils Testing <dev/testing.html>`__
 * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
 * `Python Source Reader <dev/pysource.html>`_ (incomplete)
-- 
cgit v1.2.1


From 814741f4841bfabd6dd3681300d409611731e6f1 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 19:45:50 +0000
Subject: clarified

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3538 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index fd75a16df..bc7f289c3 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -896,7 +896,7 @@ _`_directories`
 
 _`_disable_config`
     Prevent standard configuration files from being read.  For
-    internal use only.
+    programmatic use only.
 
     Default: config files enabled (None).  No command-line options.
 
-- 
cgit v1.2.1


From acd13d4dec84b25fac3fe0572cb867fd42753fcf Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 20 Jun 2005 22:32:21 +0000
Subject: enabled embed_stylesheet by default; people who don't care of getting
 their stylesheet uploaded wouldn't include the stylesheet otherwise, and
 people who do will find --link-stylesheet

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3547 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index bc7f289c3..73444397f 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -588,7 +588,7 @@ _`embed_stylesheet`
     Embed the stylesheet in the output HTML file.  The stylesheet file
     must be accessible during processing.
 
-    Default: link, don't embed (None).  Options: ``--embed-stylesheet,
+    Default: enabled.  Options: ``--embed-stylesheet,
     --link-stylesheet``.
 
 _`field_name_limit`
-- 
cgit v1.2.1


From c04ee4d9948a2854fd9ea96eb9f1e22f56be29d5 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 21 Jun 2005 00:11:44 +0000
Subject: issue a warning rather than an error when no stylesheet is given;
 default for "stylesheet" is now None, not -1

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3549 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 73444397f..d7b08bf48 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -618,8 +618,6 @@ _`initial_header_level`
 
     Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
 
-.. _stylesheet [html4css1 writer]:
-
 _`option_limit`
     The maximum width (in characters) for options in option lists.
     Longer options will span an entire row of the table used to render
@@ -628,11 +626,14 @@ _`option_limit`
 
     Default: 14 characters.  Option: ``--option-limit``.
 
+.. _stylesheet [html4css1 writer]:
+
 stylesheet
     CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
-    [#override]_.
+    [#override]_.  Pass an empty string to deactivate stylesheet
+    inclusion.
 
-    Default: "default.css".  Options: ``--stylesheet``.
+    Default: None.  Options: ``--stylesheet``.
 
     (Setting also defined for the `LaTeX Writer`__.)
 
-- 
cgit v1.2.1


From cf6285576a6d35d2e7d8f26174c6ad7026b2eb44 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 22 Jun 2005 22:13:30 +0000
Subject: tweaks, clarifications, corrections

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3559 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 66 ++++++++++++++++++++++++++++-------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index 05aa4f2c6..0a2e25d2b 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -15,11 +15,11 @@
 .. contents::
 
 This document describes how to create packages of Docutils (e.g. for
-shipping them with a Linux distribution).  If you have any questions,
+shipping with a Linux distribution).  If you have any questions,
 please direct them to the Docutils-develop_ mailing list.
 
-First of all, please download the most current `release tarball`_ and
-unpack it.
+First, please download the most current `release tarball`_ and unpack
+it.
 
 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
 .. _release tarball: http://docutils.sourceforge.net/#download
@@ -30,15 +30,15 @@ Dependencies
 
 Docutils has the following dependencies:
 
-* Python 2.1 or later is required.  (While the compiler package from
+* Python 2.1 or later is required.  While the compiler package from
   the Tools/ directory of Python's source distribution must be
   installed for the test suite to pass with Python 2.1, the
   functionality available to end users should be available without the
-  compiler package as well.  So just use >= Python 2.1 in the
-  dependencies.)
+  compiler package as well.  So just use ">= Python 2.1" in the
+  dependencies.
 
-* Docutils may optionally make use of the PIL (Python Imaging
-  Library).  If PIL is present, it is automatically detected by
+* Docutils may optionally make use of the PIL (`Python Imaging
+  Library`).  If PIL is present, it is automatically detected by
   Docutils.
 
 * There are three files in the ``extras/`` directory of the Docutils
@@ -52,6 +52,8 @@ Docutils has the following dependencies:
   These files are automatically installed by the setup script (when
   calling "python setup.py install").
 
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
 
 Python Files
 ============
@@ -62,17 +64,17 @@ install`` should do the trick, but if you want to place the files
 yourself, you can just install the ``docutils/`` directory of the
 Docutils tarball to ``/usr/lib/python/site-packages/docutils/``.  In
 this case you should also compile the Python files to ``.pyc`` and/or
-``.pyo`` files so that Docutils doesn't need to be recompiled
-everytime it's executed.
+``.pyo`` files so that Docutils doesn't need to be recompiled every
+time it's executed.
 
 
-Binaries
-========
+Executables
+===========
 
-The binaries are located in the ``tools/`` directory of the Docutils
-tarball.
+The executable front-end tools are located in the ``tools/`` directory
+of the Docutils tarball.
 
-The ``rst2*.py`` tools except ``rst2newlatex.py`` are intended for
+The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
 end-users.  You should install them to ``/usr/bin/``.  You do not need
 to change the names (e.g. to ``docutils-rst2html.py``) because the
 ``rst2`` prefix is unique.
@@ -81,25 +83,34 @@ to change the names (e.g. to ``docutils-rst2html.py``) because the
 Documentation
 =============
 
-The documentation should be generated using ``buildhtml.py``.  Go to
-the ``tools/`` directory and run ``./buildhtml.py ..``.  This will
-create all HTML files.
+The documentation should be generated using ``buildhtml.py``.  To
+generate HTML for all documentation files, go to the ``tools/``
+directory and run::
+
+    ./buildhtml.py ..
 
 Then install the following files to ``/usr/share/doc/docutils/`` (or
-however you like to call the documentation directory):
+wherever you install documentation):
 
 * All ``.html`` and ``.txt`` files in the base directory.
-* The ``docs/`` directory.  (Do not install the contents of the
-  ``docs/`` directory directory directly to
-  ``/usr/share/doc/docutils/``\ —it's incomplete and would contain
-  invalid references!)
+
+* The ``docs/`` directory.
+
+  Do not install the contents of the ``docs/`` directory directly to
+  ``/usr/share/doc/docutils/`` —- it's incomplete and would contain
+  invalid references!
+
 * The ``licenses/`` directory.
+
 * ``tools/stylesheets/default.css``, creating the ``tools/`` and
   ``tools/stylesheets/`` directory beforehand.  This file is needed
-  for correct viewing of the HTML files.  (You do not need to install
-  the other contents of the ``tools/`` or ``stylesheets/`` directory.
-  However, do not install ``default.css`` right into the documentation
-  base directory, or the references to the stylesheet will not work.)
+  for correct viewing of the HTML files.  The remaining contents of
+  the ``tools/`` and ``tools/stylesheets/`` directories are not
+  needed.
+
+  Be sure not to install ``default.css`` into the root of the
+  documentation directory, or the relative references to the
+  stylesheet will not work.
 
 
 Removing the ``.txt`` Files
@@ -110,6 +121,7 @@ the tree except for:
 
 * those in the ``licenses/`` directory because they have not been
   processed to HTML and
+
 * ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
   be readable in source form.
 
-- 
cgit v1.2.1


From 21765adac8d10ef918eab2afc26672cfac2af4cd Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 22 Jun 2005 22:22:51 +0000
Subject: typos

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3560 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index 0a2e25d2b..a4d913655 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -38,7 +38,7 @@ Docutils has the following dependencies:
   dependencies.
 
 * Docutils may optionally make use of the PIL (`Python Imaging
-  Library`).  If PIL is present, it is automatically detected by
+  Library`_).  If PIL is present, it is automatically detected by
   Docutils.
 
 * There are three files in the ``extras/`` directory of the Docutils
@@ -97,7 +97,7 @@ wherever you install documentation):
 * The ``docs/`` directory.
 
   Do not install the contents of the ``docs/`` directory directly to
-  ``/usr/share/doc/docutils/`` —- it's incomplete and would contain
+  ``/usr/share/doc/docutils/``\—it's incomplete and would contain
   invalid references!
 
 * The ``licenses/`` directory.
-- 
cgit v1.2.1


From dfed077fc0a063a1e9d73627f0643738eacfcfab Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 23 Jun 2005 00:21:31 +0000
Subject: This wasn't a typo -- a single hyphen does not an em-dash make.  The
 backslash is butt-ugly and unnecessary.  Can we compromise on a semicolon?

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index a4d913655..c1cfc3603 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -97,7 +97,7 @@ wherever you install documentation):
 * The ``docs/`` directory.
 
   Do not install the contents of the ``docs/`` directory directly to
-  ``/usr/share/doc/docutils/``\—it's incomplete and would contain
+  ``/usr/share/doc/docutils/``; it's incomplete and would contain
   invalid references!
 
 * The ``licenses/`` directory.
-- 
cgit v1.2.1


From 33abed9a56bc9451e6728c874a6127195cb5d457 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 23 Jun 2005 10:43:30 +0000
Subject: added link to link list

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3564 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index 222d6759e..bb468e8d7 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -82,6 +82,7 @@ Docutils-general:
 * `Docutils Configuration Files <user/config.html>`__
 * `Docutils LaTeX Writer <user/latex.html>`__
 * `Docutils Mailing Lists <user/mailing-lists.html>`__
+* `Docutils Links <user/links.html>`__
 
 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
 
-- 
cgit v1.2.1


From d6649c9ccd1a002ab28b59c11d12bbaf96a5d2a9 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 27 Jun 2005 11:10:08 +0000
Subject: added link targets; note to self: need to document
 publish_(from_)doctree

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3597 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 79bac6202..98d84235f 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -97,39 +97,39 @@ the "whole" part.
 Parts Provided By All Writers
 -----------------------------
 
-whole
+_`whole`
     ``parts['whole']`` contains the entire formatted document.
 
 
 Parts Provided By the HTML Writer
 ---------------------------------
 
-body
+_`body`
     ``parts['body']`` is equivalent to ``parts['fragment']``.
 
-docinfo
+_`docinfo`
     ``parts['docinfo']`` contains the document bibliographic data.
 
-footer
+_`footer`
     ``parts['footer']`` contains the document footer content, meant to
     appear at the bottom of a web page, or repeated at the bottom of
     every printed page.
 
-fragment
+_`fragment`
     ``parts['fragment']`` contains the document body (*not* the HTML
     ``<body>``).  In other words, it contains the entire document,
     less the document title, subtitle, docinfo, header, and footer.
 
-header
+_`header`
     ``parts['header']`` contains the document header content, meant to
     appear at the top of a web page, or repeated at the top of every
     printed page.
 
-html_body
+_`html_body`
     ``parts['html_body']`` contains the HTML ``<body>`` content, less
     the ``<body>`` and ``</body>`` tags themselves.
 
-html_head
+_`html_head`
     ``parts['html_head']`` contains the HTML ``<head>`` content, less
     the stylesheet link and the ``<head>`` and ``</head>`` tags
     themselves.  Since ``publish_parts`` returns Unicode strings and
@@ -140,7 +140,7 @@ html_head
 
     The interpolation should be done by client code.
 
-html_prolog
+_`html_prolog`
     ``parts['html_prolog]`` contains the XML declaration and the
     doctype declaration.  The XML declaration's "encoding" attribute's
     value is left unresolved, as "%s"::
@@ -149,27 +149,27 @@ html_prolog
 
     The interpolation should be done by client code.
 
-html_subtitle
+_`html_subtitle`
     ``parts['html_subtitle']`` contains the document subtitle,
     including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
     tags.
 
-html_title
+_`html_title`
     ``parts['html_title']`` contains the document title, including the
     enclosing ``<h1 class="title">`` & ``</h1>`` tags.
 
-meta
+_`meta`
     ``parts['meta']`` contains all ``<meta ... />`` tags.
 
-stylesheet
+_`stylesheet`
     ``parts['stylesheet']`` contains the document stylesheet link.
 
-subtitle
+_`subtitle`
     ``parts['subtitle']`` contains the document subtitle text and any
     inline markup.  It does not include the enclosing ``<h2>`` &
     ``</h2>`` tags.
 
-title
+_`title`
     ``parts['title']`` contains the document title text and any inline
     markup.  It does not include the enclosing ``<h1>`` & ``</h1>``
     tags.
-- 
cgit v1.2.1


From 9d1a45f051d1fea540749eab04bd0b549bdd0fc4 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 27 Jun 2005 11:25:47 +0000
Subject: added more links; added note about body != html_body

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3599 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/api/publisher.txt | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
index 98d84235f..73cfc0ef2 100644
--- a/docs/api/publisher.txt
+++ b/docs/api/publisher.txt
@@ -19,19 +19,19 @@ then call its ``publish`` method.  ``docutils.core.Publisher.publish``
 handles everything else.  There are five convenience functions in the
 ``docutils.core`` module:
 
-* ``publish_cmdline``: for command-line front-end tools, like
+:_`publish_cmdline`: for command-line front-end tools, like
   ``rst2html.py``.  There are several examples in the ``tools/``
   directory.  A detailed analysis of one such tool is in `Inside A
   Docutils Command-Line Front-End Tool`_
 
-* ``publish_file``: for programmatic use with file-like I/O.  In
+:_`publish_file`: for programmatic use with file-like I/O.  In
   addition to writing the encoded output to a file, also returns the
   encoded output as a string.
 
-* ``publish_string``: for programmatic use with string I/O.  Returns
+:_`publish_string`: for programmatic use with string I/O.  Returns
   the encoded output as a string.
 
-* ``publish_parts``: for programmatic use with string input; returns a
+:_`publish_parts`: for programmatic use with string input; returns a
   dictionary of document parts.  Dictionary keys are the names of
   parts, and values are Unicode strings; encoding is up to the client.
   Useful when only portions of the processed document are desired.
@@ -39,7 +39,7 @@ handles everything else.  There are five convenience functions in the
 
   There are usage examples in the `docutils/examples.py`_ module.
 
-* ``publish_programmatically``: for custom programmatic use.  This
+:_`publish_programmatically`: for custom programmatic use.  This
   function implements common code and is used by ``publish_file``,
   ``publish_string``, and ``publish_parts``.  It returns a 2-tuple:
   the encoded string output and the Publisher object.
@@ -105,7 +105,8 @@ Parts Provided By the HTML Writer
 ---------------------------------
 
 _`body`
-    ``parts['body']`` is equivalent to ``parts['fragment']``.
+    ``parts['body']`` is equivalent to parts['fragment_'].  It is
+    *not* equivalent to parts['html_body_'].
 
 _`docinfo`
     ``parts['docinfo']`` contains the document bibliographic data.
-- 
cgit v1.2.1


From cb6b50bc802610f43831642cb08d3c845b6515bf Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 27 Jun 2005 20:49:51 +0000
Subject: added Document Conventions section

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3607 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 2bede5ffd..ed4d69789 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -104,6 +104,44 @@ Conventions`_ PEPs, with the following clarifications and extensions:
 .. _Docutils Internationalization: ../howto/i18n.html#python-code
 
 
+Documentation Conventions
+=========================
+
+* Docutils documentation is written using reStructuredText, of course.
+
+* Use 7-bit ASCII if at all possible.
+
+* Use the following section title adornment styles::
+
+      ================
+       Document Title
+      ================
+
+      ------------------------------
+       Document Subtitle (optional)
+      ------------------------------
+
+      Section
+      =======
+
+      Subsection
+      ----------
+
+  If you need subsubsections and further, these characters are
+  recommended for title underlines::
+
+      ` .
+
+* Use two blank lines before each section/subsection/etc. title.  One
+  blank line is sufficient between immediately adjacent titles.
+
+* Add a bibliographic field list immediately after the document
+  title/subtitle.  See the beginning of this document for an example.
+
+* Add an Emacs local variables block in a comment at the end of the
+  document.  See the end of this document for an example.
+
+
 Copyrights and Licensing
 ========================
 
-- 
cgit v1.2.1


From 643021dced731e9c3d207d5c595c1f6bb94d9b6a Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 27 Jun 2005 22:52:04 +0000
Subject: added link to FAQ entry about reST-blogs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3615 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 22c8a9706..d663e416b 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -20,8 +20,12 @@ Related Projects
 These are projects users of Docutils and reStructuredText may find
 useful, listed in no particular order.  Many of them projects are
 hosted in the `Docutils Sandbox`_.  All projects are usable by end
-users in some way, however do not expect all of them to run out of the
-box.
+users in some way, however please do not expect all of them to run
+straight out of the box.
+
+* For Wikis, please see the `FAQ entry about Wikis`_.
+
+* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 
 * rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML
   Help files from reStructuredText files.
@@ -53,8 +57,6 @@ box.
 
 * Patrick O'Brien has taken over the `OpenOffice.org Writer`_.
 
-* For Wikis, please see the `FAQ entry about Wikis`_.
-
 * Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely
   on CSS (stylesheets).
 
@@ -63,8 +65,10 @@ box.
   both LaTeX and HTML output on top of it.
 
 * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
-  to handle everything one might do with docutils.
+  to handle everything one might do with Docutils.
 
+.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
+.. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
 .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 .. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
@@ -79,7 +83,6 @@ box.
 .. _HT2HTML integration: http://docutils.sf.net/sandbox/oliverr/ht/
 .. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
 .. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/
-.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
 .. _Makefile: http://docutils.sf.net/sandbox/cben/make/
-- 
cgit v1.2.1


From fb247a2c98d8fffdca2a6ede5235f1b9e28a27ae Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 28 Jun 2005 13:49:10 +0000
Subject: Added ``_stylesheet_required`` internal setting,
 docutils.transforms.html.StylesheetCheck transform, docs, tests, and support.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3617 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 3 +++
 docs/user/config.txt    | 5 +++++
 2 files changed, 8 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 079bedaaa..7bdcee1de 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -40,6 +40,8 @@ peps.Headers                    pep (r)                       360
 
 peps.Contents                   pep (r)                       380
 
+html.StylesheetCheck            html4css1 (w)                 420
+
 references.AnonymousHyperlinks  standalone (r), pep (r)       440
 
 references.IndirectHyperlinks   standalone (r), pep (r)       460
@@ -83,6 +85,7 @@ misc.CallBack                   n/a                           990
 Key:
 
 * (r): Reader
+* (w): Writer
 * (d): Directive
 * (t): Transform
 * (/p): Via a "pending" node
diff --git a/docs/user/config.txt b/docs/user/config.txt
index d7b08bf48..3b7e8c2d0 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -911,6 +911,11 @@ _`_source`
 
     Default: stdin (None).  No command-line options.
 
+_`_stylesheet_required`
+    Used to disable stylesheet checking in writers that use
+    stylesheets.  For programmatic use only.
+
+    Default: required (1).  No command-line options.
 
 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
 
-- 
cgit v1.2.1


From 319f1f199e45bc596b8f2654344ffe7fdf037459 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 28 Jun 2005 20:28:17 +0000
Subject: added to-do list entries about directives

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3618 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 2727aeb43..d2741faf8 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1078,6 +1078,12 @@ 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.
 
+* Make the directive interface object-oriented
+  (http://article.gmane.org/gmane.text.docutils.user/1871).
+
+* Unify table implementations and unify options of table directives
+  (http://article.gmane.org/gmane.text.docutils.user/1857).
+
 * Allow directives to be added at run-time?
 
 * Use the language module for directive option names?
-- 
cgit v1.2.1


From 62ed4778b682fb915f13ff6b37b57e1156ac1da1 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 28 Jun 2005 21:54:42 +0000
Subject: another two to do list entries

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3619 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index d2741faf8..a35643d48 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -484,6 +484,9 @@ User Docs
   server and that it's terribly slow.  See the first paragraphs in
   <http://article.gmane.org/gmane.text.docutils.user/1584>.
 
+* Add document about what Docutils has previously been used for
+  (web/use-cases.txt?).
+
 
 Developer Docs
 --------------
@@ -662,6 +665,9 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Complain about bad URI characters
+  (http://article.gmane.org/gmane.text.docutils.user/2046).
+
 * Create ``info``-level system messages for unnecessarily
   backslash-escaped characters (as in ``"\something"``, rendered as
   "something") to allow checking for errors which silently slipped
-- 
cgit v1.2.1


From fe22e775c610696e3311ab0d6cec0e836c259576 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 28 Jun 2005 22:42:35 +0000
Subject: added history and to-do list entries

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3620 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index a35643d48..b4f1c962f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -665,6 +665,10 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Change the specification so that more punctuation is allowed
+  before/after inline markup start/end string
+  (http://article.gmane.org/gmane.text.docutils.cvs/3824).
+
 * Complain about bad URI characters
   (http://article.gmane.org/gmane.text.docutils.user/2046).
 
-- 
cgit v1.2.1


From 8d2b940d5d23fd968831db94e5fb7208cd27268b Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 29 Jun 2005 12:09:04 +0000
Subject: added "title" attribute to document tree reference

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3622 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt  | 21 +++++++++++++++++++--
 docs/ref/docutils.dtd |  4 +++-
 2 files changed, 22 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index f432ed1f6..68bfb408f 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -1785,8 +1785,11 @@ See the `%structure.model;`_ parameter entity for details of the body
 of a ``document``.
 
 :Attributes:
-    The ``document`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    The ``document`` element contains the `common attributes`_ (id_,
+    name_, dupname_, source_, and class_), plus an optional title__
+    attribute which stores the document title metadata.
+
+    __ `title (attribute)`_
 
 
 Examples
@@ -3975,6 +3978,8 @@ Pseudo-XML_ fragment from simple parsing::
             15% if the service is good.
 
 
+.. _title:
+
 ``title``
 =========
 
@@ -4577,6 +4582,18 @@ whitespace.  The attribute value should not be set in a document
 instance.
 
 
+.. _title (attribute):
+
+``title``
+=========
+
+`Attribute type`_: ``CDATA``.  Default value: none.
+
+The ``title`` attribute stores the title metadata of a document.  This
+title is typically not part of the rendered document.  It may for
+example be used in HTML's ``title`` element.
+
+
 ----------------------------
  Parameter Entity Reference
 ----------------------------
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index fd47b6c91..f6628684a 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -196,7 +196,9 @@ http://www.oasis-open.org/html/tm9901.htm).
       decoration?,
       (docinfo, transition?)?,
       %structure.model; )>
-<!ATTLIST document %basic.atts;>
+<!ATTLIST document
+    %basic.atts;
+    title     CDATA     #IMPLIED>
 
 <!--
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
cgit v1.2.1


From df203f30c658d959e8cd8c38f495d5d32c0b1edb Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 30 Jun 2005 17:52:00 +0000
Subject: deactivated _stylesheet_required for programmatic use; improved
 documentation

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3642 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 3b7e8c2d0..e0bd86a8e 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -912,8 +912,8 @@ _`_source`
     Default: stdin (None).  No command-line options.
 
 _`_stylesheet_required`
-    Used to disable stylesheet checking in writers that use
-    stylesheets.  For programmatic use only.
+    Used to disable stylesheet checking in writers that require a
+    stylesheet for correct rendering.  For programmatic use only.
 
     Default: required (1).  No command-line options.
 
-- 
cgit v1.2.1


From 21d87f8811b672fc2726cc2d69baf229240e0dd3 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 1 Jul 2005 16:39:51 +0000
Subject: improved cloaking mechanism

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3644 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index e0bd86a8e..493f4aa53 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -565,14 +565,14 @@ attribution
 
 _`cloak_email_addresses`
     Scramble email addresses to confuse harvesters.  In the visible
-    text of an email address, the "@" will be replaced by "at", and
-    all periods (".") will be replaced by "dot", with spaces added.
-    In the reference URI, the address will be replaced by %-escapes.
-    For example, "abc@example.org" will be output as::
+    text of an email address, the "@" and all periods (".") will be
+    surrounded by ``<span>`` tags.  In the reference URI, the address
+    will be replaced by %-escapes.  For example, "abc@example.org"
+    will be output as::
 
         <a class="reference"
          href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
-        abc at example dot org</a>
+        abc<span>@</span>example<span>.</span>org</a>
 
     Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 
-- 
cgit v1.2.1


From 94966c06ef09db664e9570ef16b9f2549c517fb7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Jul 2005 20:25:12 +0000
Subject: extended Hacker's guide

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3656 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/hacking.txt | 74 +++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/hacking.txt b/docs/dev/hacking.txt
index d98823ba0..ab0c85259 100644
--- a/docs/dev/hacking.txt
+++ b/docs/dev/hacking.txt
@@ -1,5 +1,3 @@
-.. -*- coding: utf-8 -*-
-
 ==========================
  Docutils_ Hacker's Guide
 ==========================
@@ -51,6 +49,7 @@ While this looks very simple, it's enough to illustrate all internal
 processing stages of Docutils.  Let's see how this document is
 processed from the reStructuredText source to the final HTML output:
 
+
 Reading the Document
 --------------------
 
@@ -63,6 +62,7 @@ things, there is no need to change that.
 Since you probably won't need to touch readers, we will just move on
 to the next stage:
 
+
 Parsing the Document
 --------------------
 
@@ -101,6 +101,7 @@ arranged as a class hierarchy (for example, both ``emphasis`` and
 overview of the node class hierarchy, use epydoc (type ``epydoc
 nodes.py``) and look at the class hierarchy tree.
 
+
 Transforming the Document
 -------------------------
 
@@ -139,7 +140,7 @@ has changed after applying the Transforms, we use the
 
 For our small test document, the only change is that the ``refname``
 attribute of the reference has been replaced by a ``refuri``
-attribute—the reference has been resolved.
+attribute |---| the reference has been resolved.
 
 While this does not look very exciting, transforms are a powerful tool
 to apply any kind of transformation on the node tree.
@@ -147,6 +148,7 @@ to apply any kind of transformation on the node tree.
 By the way, you can also get a "real" XML representation of the node
 tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``.
 
+
 Writing the Document
 --------------------
 
@@ -175,8 +177,8 @@ For HTML output, we can test this using the ``rst2html.py`` tool::
 
 So here we finally have our HTML output.  The actual document contents
 are in the fourth-last line.  Note, by the way, that the HTML writer
-did not render the (invisible) ``target`` node—only the ``paragraph``
-node and its children appear in the HTML output.
+did not render the (invisible) ``target`` node |---| only the
+``paragraph`` node and its children appear in the HTML output.
 
 
 Extending Docutils
@@ -185,11 +187,11 @@ Extending Docutils
 Now you'll ask, "how do I actually extend Docutils?"
 
 First of all, once you are clear about *what* you want to achieve, you
-have to decide *where* to implement it—in the Parser (e.g. by adding a
-directive or role to the reStructuredText parser), as a Transform, or
-in the Writer.  There is often one obvious choice among those three
-(Parser, Transform, Writer).  If you are unsure, ask on the
-Docutils-develop_ mailing list.
+have to decide *where* to implement it |---| in the Parser (e.g. by
+adding a directive or role to the reStructuredText parser), as a
+Transform, or in the Writer.  There is often one obvious choice among
+those three (Parser, Transform, Writer).  If you are unsure, ask on
+the Docutils-develop_ mailing list.
 
 In order to find out how to start, it is often helpful to look at
 similar features which are already implemented.  For example, if you
@@ -198,6 +200,45 @@ the implementation of a similar directive in
 ``docutils/parsers/rst/directives/``.
 
 
+Modifying the Document Tree Before It Is Written
+------------------------------------------------
+
+You can modify the document tree right before the writer is called.
+One possibility is to use the publish_doctree_ and
+publish_from_doctree_ functions.
+
+To retrieve the document tree, call::
+
+    document = docutils.core.publish_doctree(...)
+
+Please see the docstring of publish_doctree for a list of parameters.
+
+.. XXX Need to write a well-readable list of (commonly used) options
+   of the publish_* functions.  Probably in api/publisher.txt.
+
+``document`` is the root node of the document tree.  You can now
+change the document by accessing the ``document`` node and its
+children |---| see `The Node Interface`_ below.
+
+When you're done with modifying the document tree, you can write it
+out by calling::
+
+    output = docutils.core.publish_from_doctree(document, ...)
+
+.. _publish_doctree: ../api/publisher.html#publish_doctree
+.. _publish_from_doctree: ../api/publisher.html#publish_from_doctree
+
+
+The Node Interface
+------------------
+
+As described in the overview above, Docutils' internal representation
+of a document is a tree of nodes.  We'll now have a look at the
+interface of these nodes.
+
+(To be completed.)
+
+
 What Now?
 =========
 
@@ -208,3 +249,16 @@ on the Docutils-develop_ mailing list.
 
 
 .. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+
+
+.. |---| unicode:: 8212 .. em-dash
+   :trim:
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
-- 
cgit v1.2.1


From 2703f7c25b10c10f59db93e0776cb81c1d181bca Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Jul 2005 20:29:55 +0000
Subject: moved transition transform logic from universal.FinalChecks to a
 separate transform, misc.Transitions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3657 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 7bdcee1de..28b9c002f 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -71,6 +71,8 @@ components.Filter               "meta" (d/p)                  780
 
 universal.Decorations           Transformer                   820
 
+misc.Transitions                standalone (r)                830
+
 universal.FinalChecks           Transformer                   840
 
 universal.Messages              Transformer                   860
-- 
cgit v1.2.1


From e0a1eaac9d47da79a00c92c74ef7e789464421b7 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Jul 2005 23:14:55 +0000
Subject: moved expose_internals logic out of FinalChecks into a separate
 transform, universal.ExposeInternals

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3658 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 28b9c002f..9468619fd 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -73,7 +73,9 @@ universal.Decorations           Transformer                   820
 
 misc.Transitions                standalone (r)                830
 
-universal.FinalChecks           Transformer                   840
+universal.ExposeInternals       Transformer                   840
+
+universal.FinalChecks           Transformer                   850
 
 universal.Messages              Transformer                   860
 
-- 
cgit v1.2.1


From 88b1bd28140150e41265cd8a84b5d0ee55f05138 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 5 Jul 2005 23:36:14 +0000
Subject: renamed universal.FinalChecks to references.DanglingReferences;
 changed priority to 680

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3659 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 9468619fd..cd9cf3fe8 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -60,6 +60,8 @@ references.ExternalTargets      standalone (r), pep (r)       640
 
 references.InternalTargets      standalone (r), pep (r)       660
 
+references.DanglingReferences   standalone (r), pep (r)       680
+
 parts.SectNum                   "sectnum" (d/p)               710
 
 parts.Contents                  "contents" (d/p),             720
@@ -71,12 +73,10 @@ components.Filter               "meta" (d/p)                  780
 
 universal.Decorations           Transformer                   820
 
-misc.Transitions                standalone (r)                830
+misc.Transitions                standalone (r), pep (r)       830
 
 universal.ExposeInternals       Transformer                   840
 
-universal.FinalChecks           Transformer                   850
-
 universal.Messages              Transformer                   860
 
 universal.FilterMessages        Transformer                   870
-- 
cgit v1.2.1


From ca5818dc7398a4588dc04b4e84067f559c59b999 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 7 Jul 2005 16:14:12 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3667 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b4f1c962f..ec1f8c38a 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1299,6 +1299,8 @@ when used in a document.
     The ideas in `adaptable file extensions`_ above may also be
     applicable here.
 
+    SVG's "switch" statement may provide inspiration.
+
     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. ::
-- 
cgit v1.2.1


From 9095b7661a8313d940241110472c25d7a5fe1997 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 8 Jul 2005 01:03:11 +0000
Subject: restructured links document into "Users" and "Developers" sections;
 added link to pickle writer

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3673 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index d663e416b..8732e232b 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -8,20 +8,24 @@
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
-.. _Docutils: http://docutils.sourceforge.net/
+.. contents::
+
+This document contains links users of Docutils and reStructuredText
+may find useful, listed in no particular order.  Many of the project
+listed here are hosted in the `Docutils Sandbox`_.  If you have
+something to publish, you can get write access, too!
 
 The most current version of this document can always be found at
 http://docutils.sourceforge.net/docs/user/links.html.
 
 
-Related Projects
-================
+Users
+-----
 
-These are projects users of Docutils and reStructuredText may find
-useful, listed in no particular order.  Many of them projects are
-hosted in the `Docutils Sandbox`_.  All projects are usable by end
-users in some way, however please do not expect all of them to run
-straight out of the box.
+This section contains links which are interesting for all users of
+Docutils.  All projects listed here are usable by end users in some
+way, however please do not expect all of them to run straight out of
+the box.
 
 * For Wikis, please see the `FAQ entry about Wikis`_.
 
@@ -36,14 +40,6 @@ straight out of the box.
 * ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope"
   application that is complete and ready to install.
 
-* PySource_, by Tony Ibbs, is an experimental Python source Reader.
-  In some form, it will soon become part of core Docutils.  There is
-  some related code in David Goodger's sandbox (pysource_reader_) and
-  a `Python Source Reader`_ document.
-
-  .. Is this usable for end users?  Maybe move to a "Developers"
-     section?
-
 * The Docutils interface to PythonPoint_, also by Richard Jones,
   produces PDF presentations using ReportLabs.
 
@@ -67,6 +63,21 @@ straight out of the box.
 * Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
   to handle everything one might do with Docutils.
 
+
+Developers
+----------
+
+This section contains links which are primarily interesting for
+developers.
+
+* PySource_, by Tony Ibbs, is an experimental Python source Reader.
+  There is some related code in David Goodger's sandbox
+  (pysource_reader_) and a `Python Source Reader`_ document.
+
+* There is a `pickle writer`_, written by Martin Blais.
+
+
+.. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
 .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
@@ -86,3 +97,4 @@ straight out of the box.
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
 .. _Makefile: http://docutils.sf.net/sandbox/cben/make/
+.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
-- 
cgit v1.2.1


From 8c971c59a30b64858764817eece8107b5291c944 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 12 Jul 2005 02:51:42 +0000
Subject: fixed target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3742 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 493f4aa53..4ad94c5a7 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -369,7 +369,7 @@ _`strict_visitor`
     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
     for development use only).
 
--`title`
+_`title`
     The document title as metadata, which does not become part of the
     document body.  It overrides a document-supplied title.  For
     example, in HTML output the metadata document title appears in the
-- 
cgit v1.2.1


From 4da3f78e325199d751f8c4d7a58d9adf69da32eb Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Jul 2005 09:17:04 +0000
Subject: added link to xhtml2rest

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3751 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 8732e232b..dc19b277b 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -31,6 +31,9 @@ the box.
 
 * For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 
+* xhtml2rest_, written by Antonios Christofides, is a simple utility
+  to convert XHTML to reStructuredText.
+
 * rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML
   Help files from reStructuredText files.
 
@@ -80,6 +83,7 @@ developers.
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _xhtml2rest: http://docutils.sf.net/sandbox/felixwiemann/xhtml2rest/
 .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 .. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
-- 
cgit v1.2.1


From bb5cbfdbbbee01fe6f2ba086d4221f24c6615b44 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Jul 2005 09:49:04 +0000
Subject: replaced "document" with "link list" so that the file is found when
 googling for ``docutils link list``

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3754 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index dc19b277b..a45d1f0d9 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -15,7 +15,7 @@ may find useful, listed in no particular order.  Many of the project
 listed here are hosted in the `Docutils Sandbox`_.  If you have
 something to publish, you can get write access, too!
 
-The most current version of this document can always be found at
+The most current version of this link list can always be found at
 http://docutils.sourceforge.net/docs/user/links.html.
 
 
-- 
cgit v1.2.1


From 44dd1be96f0bddb777aaa4c14d27b4ba4469677d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 14 Jul 2005 13:50:07 +0000
Subject: Moved rst2ht to link list; it's not a blog. Moved htmlnav to link
 list; it's not a blog either. Removed restblog; it's outdated and doesn't
 work. Removed ReSTWeb; the current URL is <http://wingware.com/pub/restweb/>
 and it doesn't look like it's maintained anymore. Removed redundant
 HT2HTML-integration link; it's the same as rst2ht.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3755 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index a45d1f0d9..dff58ab0a 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -31,6 +31,12 @@ the box.
 
 * For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 
+* rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht
+  template, for use with ht2html_.
+
+* htmlnav_, by Gunnar Schwant, is an HTML writer which supports
+  navigation bars.
+
 * xhtml2rest_, written by Antonios Christofides, is a simple utility
   to convert XHTML to reStructuredText.
 
@@ -48,8 +54,7 @@ the box.
 
 * Engelbert Gruber has begun a `ManPage Writer`_.
 
-* Oliver Rutherfurd has begun a `DocBook Writer`_ component and
-  `HT2HTML integration`_ component.
+* Oliver Rutherfurd has begun a `DocBook Writer`_.
 
 * Gunnar Schwant's DocFactory_ is a wxPython GUI application for
   Docutils.
@@ -83,6 +88,9 @@ developers.
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
+.. _ht2html: http://ht2html.sourceforge.net/
+.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
 .. _xhtml2rest: http://docutils.sf.net/sandbox/felixwiemann/xhtml2rest/
 .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
@@ -95,7 +103,6 @@ developers.
 .. _Manpage Writer: http://docutils.sf.net/sandbox/grubert/man/
 .. _ReportLabs/PDF Writer: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
 .. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
-.. _HT2HTML integration: http://docutils.sf.net/sandbox/oliverr/ht/
 .. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
 .. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
-- 
cgit v1.2.1


From 28495b77f0cef86904c8075b24a15a418dbb610c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 15 Jul 2005 13:38:57 +0000
Subject: added an explicit reminder of expected errors, in the form of an
 error

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3756 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/demo.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/rst/demo.txt b/docs/user/rst/demo.txt
index 7e57b6bad..7a0abd033 100644
--- a/docs/user/rst/demo.txt
+++ b/docs/user/rst/demo.txt
@@ -544,7 +544,9 @@ Error Handling
 
 Any errors caught during processing will generate system messages.
 
-There should be five messages in the following, auto-generated
+|*** Expect 6 errors (including this one). ***|
+
+There should be six messages in the following, auto-generated
 section, "Docutils System Messages":
 
 .. section should be added by Docutils automatically
-- 
cgit v1.2.1


From 7da476da6fda4e6f2be21d683c9616844ed55c37 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 17 Jul 2005 19:59:35 +0000
Subject: removed note on Unicode support of csv-table directive; ASCII NUL
 limitation isn't worth being documented (there is an explanatory error
 message); encoding option has been implemented

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3761 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 6 ------
 1 file changed, 6 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 73c0b39ca..b5941c8de 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -744,12 +744,6 @@ Working limitations:
 
   .. Add "strict" option to verify input?
 
-* Due to limitations of the CSV parser, this directive is not Unicode
-  compatible.  It may also have problems with ASCII NUL characters.
-  Accordingly, CSV tables should be ASCII-printable safe.
-
-  .. Test with Unicode; see if that's really so.  "encoding" option?
-
 The following options are recognized:
 
 ``class`` : text
-- 
cgit v1.2.1


From ad50a0e2fa254098f6b7893e77c4ff14cac7ebae Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 17 Jul 2005 23:08:06 +0000
Subject: split developers section into API and Core developers; added link to
 nabu

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3763 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index dff58ab0a..2332bc065 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -72,18 +72,31 @@ the box.
   to handle everything one might do with Docutils.
 
 
-Developers
-----------
+API Developers
+--------------
 
 This section contains links which are primarily interesting for
-developers.
+developers who use the Docutils API from within their own
+applications.
+
+* nabu_, written by Martin Blais, is a publishing system which
+  extracts information from reStructuredText documents and stores it
+  in a database.  Python knowledge is required to write extractor
+  functions (see `Writing an Extractor`_ for an example).
+
+* There is a `pickle writer`_, written by Martin Blais.
+
+
+Core Developers
+---------------
+
+Links primarily interesting for developers who work with the Docutils
+code base.
 
 * PySource_, by Tony Ibbs, is an experimental Python source Reader.
   There is some related code in David Goodger's sandbox
   (pysource_reader_) and a `Python Source Reader`_ document.
 
-* There is a `pickle writer`_, written by Martin Blais.
-
 
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
@@ -108,4 +121,6 @@ developers.
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
 .. _Makefile: http://docutils.sf.net/sandbox/cben/make/
+.. _nabu: http://furius.ca/nabu/
+.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
 .. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
-- 
cgit v1.2.1


From 3d8992eb68df05f4e6c36fba2ad61be7f79df0d8 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 17 Jul 2005 23:11:33 +0000
Subject: clarified

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3764 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 2332bc065..8b1ba74c6 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -82,7 +82,8 @@ applications.
 * nabu_, written by Martin Blais, is a publishing system which
   extracts information from reStructuredText documents and stores it
   in a database.  Python knowledge is required to write extractor
-  functions (see `Writing an Extractor`_ for an example).
+  functions (see `Writing an Extractor`_) and to retrieve the data
+  from the database again.
 
 * There is a `pickle writer`_, written by Martin Blais.
 
-- 
cgit v1.2.1


From e930c4045e6caf9fabd9775bc8e319c8ac687128 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 18 Jul 2005 01:23:24 +0000
Subject: fixed error; added section about wiki

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3765 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index ed4d69789..a16d0ec24 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -351,7 +351,15 @@ Mailing Lists
 
 Developers are recommended to subscribe to all `mailing lists`_.
 
-.. _mailing lists:: ../user/mailing-lists.html
+.. _mailing lists: ../user/mailing-lists.html
+
+
+The Wiki
+========
+
+There is a development wiki at http://docutils.python-hosting.com/ as
+a scratchpad for transient notes.  Please use the repository for
+permament document storage.
 
 
 The Sandbox
-- 
cgit v1.2.1


From bd5d3204ec71f70e01164372d96230af029fd1c6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 18 Jul 2005 23:10:42 +0000
Subject: Make use of \Dlanguagebabel. Added \Dprinting for output primarily
 for printing, not online viewing. Some clean-up in the LaTeX stylesheet.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3766 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 8b1ba74c6..3ea6035e9 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -79,7 +79,7 @@ This section contains links which are primarily interesting for
 developers who use the Docutils API from within their own
 applications.
 
-* nabu_, written by Martin Blais, is a publishing system which
+* Nabu_, written by Martin Blais, is a publishing system which
   extracts information from reStructuredText documents and stores it
   in a database.  Python knowledge is required to write extractor
   functions (see `Writing an Extractor`_) and to retrieve the data
@@ -122,6 +122,6 @@ code base.
 .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
 .. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
 .. _Makefile: http://docutils.sf.net/sandbox/cben/make/
-.. _nabu: http://furius.ca/nabu/
+.. _Nabu: http://furius.ca/nabu/
 .. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
 .. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
-- 
cgit v1.2.1


From 5c281b455660e3d49431c6545b14e66ffe55306c Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 20 Jul 2005 15:06:38 +0000
Subject: merged todo2 branch to trunk

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3770 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 183 ++++++++++++++++++
 docs/dev/todo.txt             | 439 ++++++++++--------------------------------
 2 files changed, 283 insertions(+), 339 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 51930be3a..08b994834 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -1,6 +1,7 @@
 ==================================================
  A Record of reStructuredText Syntax Alternatives
 ==================================================
+
 :Author: David Goodger
 :Contact: goodger@users.sourceforge.net
 :Revision: $Revision$
@@ -2563,6 +2564,53 @@ Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to
 allow for nested enumerated lists without indentation?
 
 
+Indented Lists
+==============
+
+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
+
+
 Sloppy Indentation of List Items
 ================================
 
@@ -2892,6 +2940,141 @@ than of the character-encoding type.
   - Specifically, should the default be case-sensistive or
     -insensitive?
 
+
+Page Or Line Breaks
+===================
+
+* 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.
+
+  Probably a bad idea because there is no such thing as a page in a
+  generic document format.
+
+* 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.
+
+  Probably a bad idea as well because we do not want to use control
+  characters for well-readable and well-writable markup, and after all
+  we have the line block syntax for line breaks.
+
+
+Superscript Markup
+==================
+
+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").
+
+However, superscripts are seldom needed, and new syntax would break
+existing documents.  When it's needed, the ``:superscript:``
+(``:sup:``) role can we used as well.
+
+
+Code Execution
+==============
+
+Add the following directives?
+
+- "exec": Execute Python code & insert the results.  Call it
+  "python" to allow for other languages?
+
+- "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)
+
+- "eval": Evaluate an expression & insert the text.  At parse
+  time or at substitution time?  Dangerous?  Perhaps limit to canned
+  macros; see text.date_ below.
+
+It's too dangerous (or too complicated in the case of "eval").  We do
+not want to have such things in the core.
+
+
+``encoding`` Directive
+======================
+
+Add an "encoding" directive to specify the character encoding of the
+input data?  Not a good idea for the following reasons:
+
+- 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.
+
+
+Support for Annotations
+=======================
+
+Add an "annotation" role, as 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?).
+
+There have not been many requests for such feature, though.  Also,
+cluttering WYSIWYG plaintext with annotations may not seem like a good
+idea, and there is no "tool tip" in formats other than HTML.
+
+
+``term`` Role
+=============
+
+Add a "term" role for unfamiliar or specialized terminology?  Probably
+not; there is no real use case, and emphasis is enough for most cases.
+
+
 
 ..
    Local Variables:
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index ec1f8c38a..b308b759f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -20,26 +20,19 @@ 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.
+see done but are unable to implement it yourself, please consider
+donating to Docutils: |donate|
 
-__ http://docutils.sf.net/#please-contribute
+.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
+   :target: http://sourceforge.net/donate/index.php?group_id=38414
+   :align: middle
+   :width: 88
+   :height: 32
+   :alt: Support the Docutils project!
 
+Please see also the Bugs_ document for a list of bugs in Docutils.
 
-Priorities
-==========
-
-* Always high priority: `FIX BUGS!`__
-
-  __ ../../BUGS.html
-
-* 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`_.
+.. _bugs: ../../BUGS.html
 
 
 Minimum Requirements for Python Standard Library Candidacy
@@ -86,15 +79,6 @@ General
   settings.  These partially solve the problem, allowing or disabling
   **all** file accesses, but not limited access.
 
-* 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.
-
 * Configuration file handling needs discussion:
 
   - There should be some error checking on the contents of config
@@ -105,30 +89,24 @@ General
     file supplied with the ``--config`` option.  Should it?  (If yes,
     error or warning?)
 
-  - Is a system-wide configuration file (in ``/etc/docutils.conf``) a
-    good idea?
+* Internationalization:
 
-  - Is a user-specific configuration file (``~/.docutils``) really
-    necessary?  Maybe the name (``.docutils``) needs discussion, too.
+  - I18n needs refactoring, the language dictionaries are difficult to
+    maintain.  Maybe have a look at gettext or similar tools.
 
-* Language modules: in accented languages it may be useful to have
-  both accented and unaccented entries in the ``bibliographic_fields``
-  mapping for versatility.
+  - 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 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.
+  - Add internationalization to _`footer boilerplate text` (resulting
+    from "--generator", "--source-link", and "--date" etc.), allowing
+    translations.
 
 * 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
@@ -323,17 +301,9 @@ General
       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.
+* Add support for _`multiple output files`.
 
-  - Rewrite in Python?
+* Add testing for Docutils' front end tools?
 
 * Publisher: "Ordinary setup" shouldn't requre specific ordering; at
   the very least, there ought to be error checking higher up in the
@@ -374,10 +344,6 @@ General
 
 * 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?),
@@ -432,17 +398,6 @@ General
   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
-
-* Simplify the docutils.nodes.Element implementation?  ``node[x]`` is
-  convenient but can be considered ambiguous (different results if
-  ``x`` is a string or an integer).  Replace with ``node[int]`` and
-  ``node.attributes[string]``?  See
-  <http://thread.gmane.org/gmane.text.docutils.devel/2844>.
-
 * Add file-specific settings support to config files, like::
 
       [file index.txt]
@@ -572,6 +527,11 @@ General:
 
 Miscellaneous ideas:
 
+* 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.
+
 * 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::
@@ -687,19 +647,13 @@ __ rst/alternatives.html#or-not-to-do
   on whitespace and punctuation as markup delimiters, which may not be
   applicable in these languages.
 
-  Python 2.4 introduces the function ``unicodedata.east_asian_width``,
-  so this problem will be resolved later, when Python 2.4 is in a
-  reasonably stable state and being used more widely.
+  Especially the table parsers suffer from this problem.
 
-* Clean up the code; refactor as required.
+  We need to use the ``unicodedata.east_asian_width`` function,
+  introduced in Python 2.4.
 
 * Add motivation sections for constructs in spec.
 
-* 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
@@ -747,93 +701,15 @@ __ rst/alternatives.html#or-not-to-do
   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
+  .. XXX What does this mean?  Can you elaborate, David?
 
 * 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?
+  disabled at run-time.  Subclassing is probably not enough because it
+  makes it difficult to apply multiple extensions.
 
 * Generalize the "doctest block" construct (which is overly
   Python-centric) to other interactive sessions?  "Doctest block"
@@ -869,10 +745,6 @@ __ rst/alternatives.html#or-not-to-do
   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.").
-
 * Support whitespace in angle-bracketed standalone URLs according to
   Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
   2396`_.
@@ -898,8 +770,18 @@ __ rst/alternatives.html#or-not-to-do
 
   Decimal justification?
 
-* Make enumerated list parsing more strict, so that this would parse
-  as a paragraph with an info message::
+  All this shouldn't be done automatically.  Only when it's requested
+  by the user, e.g. with something like this::
+
+      .. table::
+         :auto-indent:
+
+         (Table goes here.)
+
+  Otherwise it will break existing documents.
+
+* Generate a warning or info message for paragraphs which should have
+  been lists, like this one::
 
       1. line one
       3. line two
@@ -907,53 +789,6 @@ __ rst/alternatives.html#or-not-to-do
 * Generalize the "target-notes" directive into a command-line option
   somehow?  See docutils-develop 2003-02-13.
 
-* 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.) ::
 
@@ -985,12 +820,6 @@ __ rst/alternatives.html#or-not-to-do
 
   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*
@@ -1027,9 +856,8 @@ __ rst/alternatives.html#or-not-to-do
 
       .. _name: ^url
 
-* Add an option to allow arbitrary URI schemes (not just those in
-  urischemes.py)?  This would make text like "signal:noise" into a
-  URI.
+  This may be too specific to HTML.  It hasn't been requested very
+  often either.
 
 * Add an option to add URI schemes at runtime.
 
@@ -1062,8 +890,8 @@ __ rst/alternatives.html#or-not-to-do
   LaTeX writer (which might very well happen when using configuration
   files), the spaces in front of footnote references aren't trimmed.
 
-* Enable _`tables inside XML comments`, where "--" ends comments.  I
-  see three implementation possibilities:
+* Enable grid _`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
@@ -1080,6 +908,11 @@ __ rst/alternatives.html#or-not-to-do
   tables are document-specific.  A pragma directive would be another
   approach, to set the syntax once for a whole document.
 
+  In the meantime, the list-table_ directive is a good replacement for
+  grid tables inside XML comments.
+
+  .. _list-table: ../ref/rst/directives.html#list-table
+
 
 Directives
 ----------
@@ -1115,13 +948,12 @@ when used in a document.
   - Allow the _`:trim:` option for all directives when they occur in a
     substitution definition, not only the unicode_ directive.
 
-    .. _unicode:
-       http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
+    .. _unicode: ../ref/rst/directives.html#unicode-character-codes
 
   - _`images.figure`: "title" and "number", to indicate a formal
     figure?
 
-  - _`parts.sectnum`: "local"?, "start", "refnum"
+  - _`parts.sectnum`: "local"?, "refnum"
 
     A "local" option could enable numbering for sections from a
     certain point down, and sections in the rest of the document are
@@ -1129,32 +961,12 @@ when used in a document.
     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.
+    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
@@ -1177,6 +989,9 @@ when used in a document.
     & footers?  For example, separate headers & footers for odd, even,
     and the first page of a document.
 
+    This may be too specific to output formats which have a notion of
+    "pages".
+
   - _`misc.include`:
 
     - Option to select a range of lines?
@@ -1203,61 +1018,37 @@ when used in a document.
     It needs thought & discussion though, to come up with a consistent
     set of destination labels and consistent behavior.
 
+    And placing HTML code inside the <head> element of an HTML
+    document is rather the job of a templating system.
+
   - _`body.sidebar`: Allow internal section structure?  Adornment
     styles would be independent of the main document.
 
+    That is really complicated, however, and the document model
+    greatly benefits from its simplicity.
+
 * 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?)
+  - _`html.imagemap`
 
-  - _`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)
+    It has the disadvantage that it's only easily implementable for
+    HTML, so it's specific to one output format.
 
-  - _`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.
+    (For non-HTML writers, the imagemap would have to be replaced with
+    the image only.)
 
-  - _`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.
+  - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
 
-  - _`misc.settings`: Set any Docutils runtime setting from within a
-    document?
+  - _`parts.citations`: See `Footnote & Citation Gathering`_.
 
-  - _`misc.charents`: Equivalent to::
+  - _`misc.language`: Specify (= change) the language of a document at
+    parse time.
 
-        .. include:: {includepath}/charents.txt
+  - _`misc.settings`: Set any(?) Docutils runtime setting from within
+    a document?  Needs much thought and discussion.
 
   - .. _conditional directives:
 
@@ -1487,17 +1278,6 @@ 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 (done)
-  - 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,
@@ -1580,17 +1360,17 @@ any knowledge of the Python-Reader origin of these elements.
 
        __ ../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?).
+    4. Using substitutions? ::
+
+           .. |reST| acronym:: reST
+              :text: reStructuredText
+
+    What do we do for other formats than HTML which do not support
+    tool tips?  Put the full text in parentheses?
 
   - "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::
@@ -1614,13 +1394,6 @@ Unimplemented Transforms
   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),
@@ -1713,20 +1486,17 @@ Unimplemented Transforms
 HTML Writer
 ===========
 
-* Test with modern browsers if it's possible to remove the "name"
-  attributes, which currently serve only for backwards-compatibility
-  to browsers which aren't XHTML compliant.  For a starting point, see
-  http://www.python.org/dev/doc/idtest.html.
-
-  If enough browsers support the "id" attribute, remove the "name"
-  attributes.
-
 * Add more support for <link> elements, especially for navigation
   bars.
 
-* Make the admonitions more distinctive and varied.
+  The framework does not have a notion of document relationships, so
+  probably raw.destination_ should be used.
+
+  We'll have framework support for document relationships when support
+  for `multiple output files`_ is added.  The HTML writer could
+  automatically generate <link> elements then.
 
-* Make the "class" attributes optional?  Implies no stylesheet?
+  .. _raw.destination: misc.raw_
 
 * Base list compaction on the spacing of source list?  Would require
   parser support.  (Idea: fantasai, 16 Dec 2002, doc-sig.)
@@ -1734,17 +1504,6 @@ HTML Writer
 * Add a tool tip ("title" attribute?) to footnote back-links
   identifying them as such.  Text in Docutils language module.
 
-* 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>.
-      -->
-
 
 LaTeX writer
 ============
@@ -2017,7 +1776,9 @@ Front-End Tools
 
 * Disable common options that don't apply?
 
-* Implement the "sectnum" directive as a command-line option also?
+* Add ``--section-numbering`` command line option.  The "sectnum"
+  directive should override the ``--no-section-numbering`` command
+  line option then.
 
 * Create a single dynamic_ or unqualified_ front end that can be
   installed?
-- 
cgit v1.2.1


From b19a84d73effa7aaca88ef62caabc506b5d281c6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 20 Jul 2005 15:12:00 +0000
Subject: fixed link

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3772 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 08b994834..6a3354739 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -3035,7 +3035,9 @@ Add the following directives?
 
 - "eval": Evaluate an expression & insert the text.  At parse
   time or at substitution time?  Dangerous?  Perhaps limit to canned
-  macros; see text.date_ below.
+  macros; see text.date_.
+
+  .. _text.date: ../todo.html#text-date
 
 It's too dangerous (or too complicated in the case of "eval").  We do
 not want to have such things in the core.
-- 
cgit v1.2.1


From 0494cac038b9de233f3a0e96391bf4611f420423 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 29 Jul 2005 00:46:56 +0000
Subject: added note about East Asian character widths

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3775 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b308b759f..dfddc2fcb 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -652,6 +652,13 @@ __ rst/alternatives.html#or-not-to-do
   We need to use the ``unicodedata.east_asian_width`` function,
   introduced in Python 2.4.
 
+  From `Unicode Standard Annex #11: East Asian Width
+  <http://www.unicode.org/reports/tr11/>`_:
+
+      In a broad sense, wide characters include W, F, and A (when in
+      EA context), while narrow characters include N, Na, H, and A
+      (when not in EA context).
+
 * Add motivation sections for constructs in spec.
 
 * Support generic hyperlink references to _`targets in other
-- 
cgit v1.2.1


From 845b7d6360e28760e3f904f487d815ddfba53f18 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 29 Jul 2005 00:47:21 +0000
Subject: clarified _stylesheet_required

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3776 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 4ad94c5a7..d63b5b5bf 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -912,8 +912,11 @@ _`_source`
     Default: stdin (None).  No command-line options.
 
 _`_stylesheet_required`
-    Used to disable stylesheet checking in writers that require a
-    stylesheet for correct rendering.  For programmatic use only.
+    Writers that require stylesheets for correct rendering will check
+    and warn if valid stylesheet settings are absent.  This setting is
+    used to enable stylesheet checking in writers and applications
+    that require a stylesheet, and disable checking in writers and
+    applications that don't.  For programmatic use only.
 
     Default: required (1).  No command-line options.
 
-- 
cgit v1.2.1


From 1da732b52647b11e5dec0d202bede9ed758dcd3a Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 29 Jul 2005 23:38:08 +0000
Subject: added hyperlinks to files

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3777 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/substitutions.txt | 92 +++++++++++++++++++++++++++---------------
 1 file changed, 60 insertions(+), 32 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt
index d4ff17a42..882239086 100644
--- a/docs/ref/rst/substitutions.txt
+++ b/docs/ref/rst/substitutions.txt
@@ -73,43 +73,43 @@ Character Entity Sets
 The following files contain substitution definitions corresponding to
 XML character entity sets, from the following standards: ISO 8879 &
 ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
-the ``tools/unicode2rstsubs.py`` program from the input file
+the ``tools/dev/unicode2rstsubs.py`` program from the input file
 unicode.xml__, which is maintained as part of the MathML 2
 Recommentation XML source.
 
 __ http://www.w3.org/2003/entities/xml/
 
-==================  ==================================================
-Entity Set File     Description
-==================  ==================================================
-isoamsa.txt         Added Mathematical Symbols: Arrows
-isoamsb.txt         Added Mathematical Symbols: Binary Operators
-isoamsc.txt         Added Mathematical Symbols: Delimiters
-isoamsn.txt         Added Mathematical Symbols: Negated Relations
-isoamso.txt         Added Mathematical Symbols: Ordinary
-isoamsr.txt         Added Mathematical Symbols: Relations
-isobox.txt          Box and Line Drawing
-isocyr1.txt         Russian Cyrillic
-isocyr2.txt         Non-Russian Cyrillic
-isodia.txt          Diacritical Marks
-isogrk1.txt         Greek Letters
-isogrk2.txt         Monotoniko Greek
-isogrk3.txt         Greek Symbols
-isogrk4.txt  [1]_   Alternative Greek Symbols
-isolat1.txt         Added Latin 1
-isolat2.txt         Added Latin 2
-isomfrk.txt  [1]_   Mathematical Fraktur
-isomopf.txt  [1]_   Mathematical Openface (Double-struck)
-isomscr.txt  [1]_   Mathematical Script
-isonum.txt          Numeric and Special Graphic
-isopub.txt          Publishing
-isotech.txt         General Technical
-mmlalias.txt        MathML aliases for entities from other sets
-mmlextra.txt [1]_   Extra names added by MathML
-xhtml4-lat1.txt     XHTML Latin 1
-xhtml4-special.txt  XHTML Special Characters
-xhtml4-symbol.txt   XHTML Mathematical, Greek and Symbolic Characters
-==================  ==================================================
+===================  =================================================
+Entity Set File      Description
+===================  =================================================
+isoamsa.txt_         Added Mathematical Symbols: Arrows
+isoamsb.txt_         Added Mathematical Symbols: Binary Operators
+isoamsc.txt_         Added Mathematical Symbols: Delimiters
+isoamsn.txt_         Added Mathematical Symbols: Negated Relations
+isoamso.txt_         Added Mathematical Symbols: Ordinary
+isoamsr.txt_         Added Mathematical Symbols: Relations
+isobox.txt_          Box and Line Drawing
+isocyr1.txt_         Russian Cyrillic
+isocyr2.txt_         Non-Russian Cyrillic
+isodia.txt_          Diacritical Marks
+isogrk1.txt_         Greek Letters
+isogrk2.txt_         Monotoniko Greek
+isogrk3.txt_         Greek Symbols
+isogrk4.txt_  [1]_   Alternative Greek Symbols
+isolat1.txt_         Added Latin 1
+isolat2.txt_         Added Latin 2
+isomfrk.txt_  [1]_   Mathematical Fraktur
+isomopf.txt_  [1]_   Mathematical Openface (Double-struck)
+isomscr.txt_  [1]_   Mathematical Script
+isonum.txt_          Numeric and Special Graphic
+isopub.txt_          Publishing
+isotech.txt_         General Technical
+mmlalias.txt_        MathML aliases for entities from other sets
+mmlextra.txt_ [1]_   Extra names added by MathML
+xhtml4-lat1.txt_     XHTML Latin 1
+xhtml4-special.txt_  XHTML Special Characters
+xhtml4-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
+===================  =================================================
 
 .. [1] There are ``*-wide.txt`` variants for each of these character
    entity set files, containing characters outside of the Unicode
@@ -124,6 +124,34 @@ entity ``©``.  The equivalent reStructuredText substitution
 reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
 ``|copy|``.
 
+.. _isoamsa.txt:        ../../../docutils/parsers/rst/include/isoamsa.txt
+.. _isoamsb.txt:        ../../../docutils/parsers/rst/include/isoamsb.txt
+.. _isoamsc.txt:        ../../../docutils/parsers/rst/include/isoamsc.txt
+.. _isoamsn.txt:        ../../../docutils/parsers/rst/include/isoamsn.txt
+.. _isoamso.txt:        ../../../docutils/parsers/rst/include/isoamso.txt
+.. _isoamsr.txt:        ../../../docutils/parsers/rst/include/isoamsr.txt
+.. _isobox.txt:         ../../../docutils/parsers/rst/include/isobox.txt
+.. _isocyr1.txt:        ../../../docutils/parsers/rst/include/isocyr1.txt
+.. _isocyr2.txt:        ../../../docutils/parsers/rst/include/isocyr2.txt
+.. _isodia.txt:         ../../../docutils/parsers/rst/include/isodia.txt
+.. _isogrk1.txt:        ../../../docutils/parsers/rst/include/isogrk1.txt
+.. _isogrk2.txt:        ../../../docutils/parsers/rst/include/isogrk2.txt
+.. _isogrk3.txt:        ../../../docutils/parsers/rst/include/isogrk3.txt
+.. _isogrk4.txt:        ../../../docutils/parsers/rst/include/isogrk4.txt
+.. _isolat1.txt:        ../../../docutils/parsers/rst/include/isolat1.txt
+.. _isolat2.txt:        ../../../docutils/parsers/rst/include/isolat2.txt
+.. _isomfrk.txt:        ../../../docutils/parsers/rst/include/isomfrk.txt
+.. _isomopf.txt:        ../../../docutils/parsers/rst/include/isomopf.txt
+.. _isomscr.txt:        ../../../docutils/parsers/rst/include/isomscr.txt
+.. _isonum.txt:         ../../../docutils/parsers/rst/include/isonum.txt
+.. _isopub.txt:         ../../../docutils/parsers/rst/include/isopub.txt
+.. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
+.. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
+.. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
+.. _xhtml4-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml4-lat1.txt
+.. _xhtml4-special.txt: ../../../docutils/parsers/rst/include/xhtml4-special.txt
+.. _xhtml4-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml4-symbol.txt
+
 
 ..
    Local Variables:
-- 
cgit v1.2.1


From 679456246112254d9408e9da6ab70787a4eda0bf Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 30 Jul 2005 04:53:02 +0000
Subject: clarified/simplified

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3779 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 2282beac2..41045b84e 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -723,14 +723,16 @@ escaped in order to have the line parsed as an ordinary paragraph::
 
     \A. Einstein was a really smart dude.
 
-Nested enumerated lists must be created with indentation.  For
-example::
+Examples of nested enumerated lists::
 
-    1. Item 1.
+    1. Item 1 initial text.
 
        a) Item 1a.
        b) Item 1b.
 
+    2. a) Item 2a.
+       b) Item 2b.
+
 Example syntax diagram::
 
     +-------+----------------------+
-- 
cgit v1.2.1


From c7f93a0617050e0586600e7a48dfe11780063292 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 30 Jul 2005 04:54:59 +0000
Subject: added directive idea

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3780 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index dfddc2fcb..294602281 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1176,6 +1176,9 @@ when used in a document.
 
     See docutils-users 2003-03-03.
 
+  - _`body.listing`: Code listing with title (to be numbered
+    eventually), equivalent of "figure" and "table" directives.
+
   - _`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"
-- 
cgit v1.2.1


From 01f344cfa4ebf63ce930644ca126783542418347 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 4 Aug 2005 03:00:27 +0000
Subject: add "new in Docutils 0.3.8" notice to auto-enumerated lists

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3786 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 41045b84e..23f6469b4 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -673,7 +673,8 @@ The following enumeration sequences are recognized:
 In addition, the auto-enumerator, "#", may be used to automatically
 enumerate a list.  Auto-enumerated lists may begin with explicit
 enumeration, which sets the sequence.  Fully auto-enumerated lists use
-arabic numerals and begin with 1.
+arabic numerals and begin with 1.  (Auto-enumerated lists are new in
+Docutils 0.3.8.)
 
 The following formatting types are recognized:
 
@@ -1165,7 +1166,7 @@ Syntax diagram::
 Line Blocks
 -----------
 
-Doctree elements: line_block, line.  New in Docutils 0.3.5.
+Doctree elements: line_block, line.  (New in Docutils 0.3.5.)
 
 Line blocks are useful for address blocks, verse (poetry, song
 lyrics), and unadorned lists, where the structure of lines is
-- 
cgit v1.2.1


From be1cb33dbb9cf978173fa58e20ab86f14641d6b3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 12 Aug 2005 22:18:09 +0000
Subject: minor update

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3790 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index a16d0ec24..3feae2f30 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -237,8 +237,10 @@ applicable), with particular emphasis as follows:
   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.
+  the impact, or feel that you require advice or approval, branches,
+  patches, or `the sandbox`_ are the way to go.
+
+* You must be prepared to fix any code you have committed.
 
 Docutils will pursue an open and trusting policy for as long as
 possible, and deal with any aberrations if (and hopefully not when)
-- 
cgit v1.2.1


From b80a48f879114d8b4fb34f8a589193305eeb0452 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 13:53:33 +0000
Subject: added to-do list entry

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3792 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 294602281..37b173758 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -630,7 +630,9 @@ __ rst/alternatives.html#or-not-to-do
   (http://article.gmane.org/gmane.text.docutils.cvs/3824).
 
 * Complain about bad URI characters
-  (http://article.gmane.org/gmane.text.docutils.user/2046).
+  (http://article.gmane.org/gmane.text.docutils.user/2046) and
+  disallow internal whitespace
+  (http://article.gmane.org/gmane.text.docutils.user/2214).
 
 * Create ``info``-level system messages for unnecessarily
   backslash-escaped characters (as in ``"\something"``, rendered as
-- 
cgit v1.2.1


From 6847f556f5896ce76aaffdbbd41b8aa7e276cce8 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 14:16:17 +0000
Subject: added link to xml2rst

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3793 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 3ea6035e9..c319392ac 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -31,6 +31,10 @@ the box.
 
 * For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 
+* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
+  dumps of the document tree (e.g. created with rst2xml.py) back to
+  reStructuredText.
+
 * rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht
   template, for use with ht2html_.
 
@@ -102,6 +106,7 @@ code base.
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
 .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
 .. _ht2html: http://ht2html.sourceforge.net/
 .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
-- 
cgit v1.2.1


From 51ed43cb7a9a5cc7c27959ad30d8d360237075e1 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 14:19:27 +0000
Subject: changed title to "Link List" so that it is found when googling for
 'docutils link list'

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3794 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index c319392ac..563db0fa0 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -1,6 +1,6 @@
-=================
- Docutils_ Links
-=================
+=====================
+ Docutils_ Link List
+=====================
 
 :Author: Felix Wiemann
 :Contact: Felix.Wiemann@ososo.de
-- 
cgit v1.2.1


From a308d49c7f8d62f9090183d03be546621efdd854 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 15:10:42 +0000
Subject: added target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3796 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index 6a3354739..e8730b650 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -1699,7 +1699,7 @@ Issues:
              - If we took the bones out, it wouldn't be
                crunchy, now would it?
 
-* A syntax for stubs in ASCII-art tables is easy to imagine::
+* A syntax for _`stubs in grid tables` is easy to imagine::
 
       +------------------------++------------+----------+
       | Header row, column 1   || Header 2   | Header 3 |
-- 
cgit v1.2.1


From c5052e88cd35d4376c64c96beee621e3d539cbad Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 15:19:50 +0000
Subject: added target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3797 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 37b173758..4edfe70bd 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -930,10 +930,12 @@ 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.
 
-* Make the directive interface object-oriented
+* Make the _`directive interface` object-oriented
   (http://article.gmane.org/gmane.text.docutils.user/1871).
 
-* Unify table implementations and unify options of table directives
+* .. _unify tables:
+
+  Unify table implementations and unify options of table directives
   (http://article.gmane.org/gmane.text.docutils.user/1857).
 
 * Allow directives to be added at run-time?
-- 
cgit v1.2.1


From f8ffb27c69811c3e0b936505e4ab978ddd03dbdc Mon Sep 17 00:00:00 2001
From: lele <lele@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 19:25:39 +0000
Subject: Fixed a typo in the Docutils release that introduced units

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3804 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 23f6469b4..264b9aabe 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2787,7 +2787,7 @@ characters (see `Escaping Mechanism`_ above).
 Units
 =====
 
-(New in Docutils 3.4.10.)
+(New in Docutils 0.3.10.)
 
 All measures consist of a positive floating point number in standard
 (non-scientific) notation and a unit, possibly separated by one or
-- 
cgit v1.2.1


From 572dab40eb2e04bea643f9d03f0900d91c4c6577 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 14 Aug 2005 20:24:03 +0000
Subject: two more typos

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3805 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index b5941c8de..2908d4959 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -202,7 +202,7 @@ The following options are recognized:
     specified, they are combined.  For example, a height of 200 and a
     scale of 50 is equivalent to a height of 100 with no scale.
 
-    New in Docutils 3.4.10: It is also possible to specify a `length
+    New in Docutils 0.3.10: It is also possible to specify a `length
     value`_.
 
 ``width`` : integer
@@ -210,7 +210,7 @@ The following options are recognized:
     the image horizontally.  As with "height" above, when the "scale"
     option is also specified, they are combined.
 
-    New in Docutils 3.4.10: It is also possible to specify a length_
+    New in Docutils 0.3.10: It is also possible to specify a length_
     or `percentage value`_ (which is relative to the current line
     width).
 
-- 
cgit v1.2.1


From c2a46503c0ea15806345b53815d95d917eb57e4e Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 15 Aug 2005 18:21:54 +0000
Subject: added note about project data at BerliOS and SF

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3808 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index dceb88f5d..730e54e42 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -20,6 +20,12 @@ Subversion is exhaustively documented in the `Subversion Book`_
 .. _Subversion: http://subversion.tigris.org/
 .. _Subversion Book: http://svnbook.red-bean.com/
 
+.. Note::
+
+   While the repository resides at BerliOS, all other project data
+   (web site, snapshots, releases, mailing lists, trackers) is hosted
+   at SourceForge.
+
 
 Accessing the Repository
 ========================
-- 
cgit v1.2.1


From e03c5f0ae2f26b8eed7b441a3275e453c6426abb Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 15 Aug 2005 21:17:12 +0000
Subject: added to-do list entry about block quotes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3812 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 4edfe70bd..c9df96008 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -625,6 +625,17 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Allow multiple block quotes, only separated by attributions
+  (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.::
+
+      quote 1
+
+      ---Attrib 1
+
+      quote 2
+
+      ---Attrib 2  
+
 * Change the specification so that more punctuation is allowed
   before/after inline markup start/end string
   (http://article.gmane.org/gmane.text.docutils.cvs/3824).
-- 
cgit v1.2.1


From 9ff6bdb0b70260e90973b1bf4f733ca7cc59dab6 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 17 Aug 2005 18:05:17 +0000
Subject: updated name

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3819 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index bb468e8d7..75429f87a 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -82,7 +82,7 @@ Docutils-general:
 * `Docutils Configuration Files <user/config.html>`__
 * `Docutils LaTeX Writer <user/latex.html>`__
 * `Docutils Mailing Lists <user/mailing-lists.html>`__
-* `Docutils Links <user/links.html>`__
+* `Docutils Link List <user/links.html>`__
 
 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
 
-- 
cgit v1.2.1


From ef661342c659d1cc901b6dd5c21e763c333abead Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 17 Aug 2005 18:06:34 +0000
Subject: moved ...2rest tools together

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3820 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 563db0fa0..37ccbb856 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -35,15 +35,15 @@ the box.
   dumps of the document tree (e.g. created with rst2xml.py) back to
   reStructuredText.
 
+* xhtml2rest_, written by Antonios Christofides, is a simple utility
+  to convert XHTML to reStructuredText.
+
 * rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht
   template, for use with ht2html_.
 
 * htmlnav_, by Gunnar Schwant, is an HTML writer which supports
   navigation bars.
 
-* xhtml2rest_, written by Antonios Christofides, is a simple utility
-  to convert XHTML to reStructuredText.
-
 * rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML
   Help files from reStructuredText files.
 
-- 
cgit v1.2.1


From 15f953a780c227ca084a01b0a87edc15ec88fca0 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 18 Aug 2005 11:20:39 +0000
Subject: clarify colons in explicit target names

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3823 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 264b9aabe..6bbdd9361 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1851,7 +1851,7 @@ indirect.
        .. _split: `A
           Hyperlink`_
 
-If a reference name contains a colon followed by whitespace, either:
+If the reference name contains any colons, either:
 
 - the phrase must be enclosed in backquotes::
 
-- 
cgit v1.2.1


From 7234954bc7bd0a5bceacf6a67641c876438ef67e Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 18 Aug 2005 11:21:13 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3824 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c9df96008..5c61da4ac 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -72,6 +72,9 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Move some general-interest sandboxes out of individuals'
+  directories, into subprojects?
+
 * Add option for file (and URL) access restriction to make Docutils
   usable in Wikis and similar applications.
 
-- 
cgit v1.2.1


From 2f3fd059cdc4944f1faedea164de5bd2aa85cea4 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 23 Aug 2005 23:43:40 +0000
Subject: added target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3827 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 5c61da4ac..06d1e3d8e 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -371,7 +371,9 @@ General
   & XMLs.  Aahz implemented something like this in
   sandbox/aahz/Effective/EffMap.py.
 
-* William Dode suggested that table cells be assigned "class"
+* .. _classes for table cells:
+
+  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
-- 
cgit v1.2.1


From 5c90ddc006b36818e727b4a42196a708b2a78a25 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 24 Aug 2005 21:33:21 +0000
Subject: made _stylesheet_required setting default to 0, activating it in the
 rst2html.py front-end tool

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3830 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index d63b5b5bf..0a7ce5ec3 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -651,6 +651,14 @@ stylesheet_path
 
     __ `stylesheet_path [latex2e writer]`_
 
+_`_stylesheet_required`
+    Warn if valid stylesheet settings are absent.  For programmatic
+    use only.
+
+    Default: not required (0), except when using the ``rst2html.py``
+    front-end tool.  No command-line options; pass ``--stylesheet=``
+    (i.e., with no argument) to disable the stylesheet explicitly.
+
 .. _xml_declaration [html4css1 writer]:
 
 xml_declaration
@@ -911,15 +919,6 @@ _`_source`
 
     Default: stdin (None).  No command-line options.
 
-_`_stylesheet_required`
-    Writers that require stylesheets for correct rendering will check
-    and warn if valid stylesheet settings are absent.  This setting is
-    used to enable stylesheet checking in writers and applications
-    that require a stylesheet, and disable checking in writers and
-    applications that don't.  For programmatic use only.
-
-    Default: required (1).  No command-line options.
-
 .. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html
 
 .. [#pwd] Path relative to the working directory of the process at
-- 
cgit v1.2.1


From c7418d6456149d9c8b6997d2fc9c00d0d6f3153d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Aug 2005 15:37:59 +0000
Subject: added HTML (CSS) stylesheet howto

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3836 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/html-stylesheets.txt | 73 +++++++++++++++++++++++++++++++++++++++++
 docs/index.txt                  |  2 ++
 2 files changed, 75 insertions(+)
 create mode 100644 docs/howto/html-stylesheets.txt

(limited to 'docs')

diff --git a/docs/howto/html-stylesheets.txt b/docs/howto/html-stylesheets.txt
new file mode 100644
index 000000000..74fccaa45
--- /dev/null
+++ b/docs/howto/html-stylesheets.txt
@@ -0,0 +1,73 @@
+==============================================
+ Writing HTML (CSS) Stylesheets for Docutils_
+==============================================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+The look of Docutils' HTML output is customizable via a CSS
+stylesheet.  The default stylesheet is called ``default.css`` and can
+be found in the ``tools/stylesheets/`` directory of the Docutils
+distribution tarball.
+
+To customize the stylesheet, place a new file (e.g. called
+``docutils.css``) in the same directory as ``default.css`` and use the
+following template::
+
+    /*
+    :Author: Your Name
+    :Contact: Your Email Address
+    :Copyright: This stylesheet has been placed in the public domain.
+
+    Stylesheet for use with Docutils.  [Optionally place a more
+    detailed description here.]
+    */
+
+    @import url(default.css);
+
+    /* Your customizations go here.  For example: */
+
+    h1, h2, h3, h4, h5, h6, p.topic-title {
+      font-family: sans-serif }    
+
+For help on the CSS syntax, please see `the WDG's guide to Cascading
+Style Sheets`__ and, in particular, their `list of CSS1 properties`__.
+
+__ http://www.htmlhelp.com/reference/css/
+__ http://www.htmlhelp.com/reference/css/all-properties.html
+
+It is important that you do not edit a copy of ``default.css``
+directly because ``default.css`` is frequently updated with each new
+release of Docutils.
+
+Also make sure that you import ``default.css`` (using "``@import
+url(default.css);``") because the definitions contained in the default
+stylesheet are required for correct rendering (margins, alignment,
+etc.).
+
+If you think your stylesheet is fancy and you would like to let others
+benefit from your efforts, you are encouraged to post the stylesheet
+to the Docutils-users_ mailing list.  We can upload it to the Docutils
+repository if you would like us to do so.
+
+If you decide to share you stylesheet with other users of Docutils,
+please keep website-specific customizations not applicable to
+Docutils' HTML code in a separate stylesheet.
+
+.. _Docutils-users: ../user/mailing-lists.html#docutils-users
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
diff --git a/docs/index.txt b/docs/index.txt
index 75429f87a..ab77b94a2 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -181,6 +181,8 @@ __ http://www.python.org/peps/pep-0287.html
 ``howto/``: Instructions for Developers
 =======================================
 
+* `Writing HTML (CSS) Stylesheets for Docutils
+  <howto/html-stylesheets.html>`__
 * `Docutils Internationalization <howto/i18n.html>`__
 * `Creating reStructuredText Directives <howto/rst-directives.html>`__
 * `Creating reStructuredText Interpreted Text Roles
-- 
cgit v1.2.1


From 970f082ec7e1d6c9bcd0785185dfba33a46d9115 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Aug 2005 15:49:37 +0000
Subject: updated section about stylesheets

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3837 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/tools.txt | 37 ++++++++++++-------------------------
 1 file changed, 12 insertions(+), 25 deletions(-)

(limited to 'docs')

diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 28433005e..7986e51a5 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -114,31 +114,18 @@ of processing, and links to the Docutils projects, add some options::
 Stylesheets
 ```````````
 
-``rst2html.py`` inserts into the generated HTML a link to a cascading
-stylesheet, defaulting to "``default.css``" (override with a
-"``--stylesheet``" or "``--stylesheet-path``" command-line option or
-with configuration file settings).  The
-"``tools/stylesheets/default.css``" stylesheet is provided for basic
-use.  To experiment with styles, rather than editing the default
-stylesheet (which will be updated as the project evolves), it is
-recommended to use an "``@import``" statement to create a "wrapper"
-stylesheet.  For example, a "``my.css``" stylesheet could contain the
-following::
-
-    @import url(default.css);
-
-    h1, h2, h3, h4, h5, h6, p.topic-title {
-      font-family: sans-serif }
-
-Generate HTML with the following command::
-
-    rst2html.py -stg --stylesheet my.css test.txt test.html
-
-When viewed in a browser, the new "wrapper" stylesheet will change the
-typeface family of titles to "sans serif", typically Helvetica or
-Arial.  Other styles will not be affected.  Styles in wrapper
-stylesheets override styles in imported stylesheets, enabling
-incremental experimentation.
+``rst2html.py`` inserts into the generated HTML a cascading stylesheet
+(or a link to a stylesheet, when passing the "``--link-stylesheet``"
+option).  You must specify the location of the stylesheet (normally
+``tools/stylesheets/default.css`` in the Docutils distribution
+tarball) with a "``--stylesheet``" or "``--stylesheet-path``"
+command-line option unless a configuration file
+(e.g. ``/etc/docutils.conf`` or ``~/.docutils.conf``) does so for you.
+The "``tools/stylesheets/default.css``" stylesheet is provided for
+basic use.  To experiment with styles, please see the `guide to
+writing HTML (CSS) stylesheets for Docutils`__.
+
+__ ../howto/html-stylesheets.html
 
 
 rstpep2html.py
-- 
cgit v1.2.1


From 7f6fa5828f837c9fc241ca94536937ee3578b3ed Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Aug 2005 16:15:37 +0000
Subject: minor improvements

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3838 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/html-stylesheets.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/html-stylesheets.txt b/docs/howto/html-stylesheets.txt
index 74fccaa45..1ae265e5e 100644
--- a/docs/howto/html-stylesheets.txt
+++ b/docs/howto/html-stylesheets.txt
@@ -17,8 +17,8 @@ be found in the ``tools/stylesheets/`` directory of the Docutils
 distribution tarball.
 
 To customize the stylesheet, place a new file (e.g. called
-``docutils.css``) in the same directory as ``default.css`` and use the
-following template::
+``my-docutils.css``) in the same directory as ``default.css`` and use
+the following template::
 
     /*
     :Author: Your Name
-- 
cgit v1.2.1


From 1895e2e02f536430272a0189237d4ec7a64f3cd3 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 26 Aug 2005 18:07:38 +0000
Subject: added to-do list entry about :parent: option of "class" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3839 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 06d1e3d8e..aae1b0d83 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1019,6 +1019,11 @@ when used in a document.
     This may be too specific to output formats which have a notion of
     "pages".
 
+  - _`misc.class`:
+
+    - Add a ``:parent:`` option for setting the parent's class
+      (http://article.gmane.org/gmane.text.docutils.devel/3165).
+
   - _`misc.include`:
 
     - Option to select a range of lines?
-- 
cgit v1.2.1


From fd75267451af302fc989b5e1f892dd4585311763 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 29 Aug 2005 22:34:31 +0000
Subject: HTML writer: - Added vertical space between fields of field lists. -
 Added ``--compact-field-lists`` option to remove vertical space in   simple
 field lists.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3842 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index 0a7ce5ec3..ea3916bfc 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -584,6 +584,15 @@ _`compact_lists`
     Default: enabled (1).  Options: ``--compact-lists,
     --no-compact-lists``.
 
+_`compact_field_lists`
+
+    Remove extra vertical whitespace between items of field lists that
+    are "simple" (i.e., all field bodies each contain at most one
+    paragraph).
+
+    Default: enabled (1).  Options: ``--compact-field-lists,
+    --no-compact-field-lists``.
+
 _`embed_stylesheet`
     Embed the stylesheet in the output HTML file.  The stylesheet file
     must be accessible during processing.
-- 
cgit v1.2.1


From b1115e0e1e4f8f31723af15ddf0b8a2650c7a45d Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 3 Sep 2005 23:14:29 +0000
Subject: some more search engine optimization

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3848 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 37ccbb856..d2127d3dc 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -8,6 +8,8 @@
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
+.. title:: Docutils Links
+
 .. contents::
 
 This document contains links users of Docutils and reStructuredText
-- 
cgit v1.2.1


From 322f1d74b093ec0bb7584967dedba83238c20c95 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 5 Sep 2005 20:44:51 +0000
Subject: updated text about call-out form of hyperlinks

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3853 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/quickref.html | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html
index fdb9a8adb..604cfe6bc 100644
--- a/docs/user/rst/quickref.html
+++ b/docs/user/rst/quickref.html
@@ -1092,7 +1092,10 @@ A transition marker is a horizontal line
       documents (think of the indirect hyperlink being "folded in" like
       ingredients into a cake), and "<em>call-out</em>" is more suitable for
       printed documents, where the link needs to be presented explicitly, for
-      example as a footnote.
+      example as a footnote.  You can force usage of the call-out form by
+      using the
+      "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>"
+      directive.
 
     <p>reStructuredText also provides for <b>embedded URIs</b> (<a
       href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>),
-- 
cgit v1.2.1


From 7f1304df3b44693bac96a903352618b5bec8b740 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 8 Sep 2005 04:49:59 +0000
Subject: clarified stylesheet requirement

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3857 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/tools.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 7986e51a5..9a2ddbcc4 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -99,16 +99,20 @@ rst2html.py
 
 The ``rst2html.py`` front end reads standalone reStructuredText source
 files and produces HTML 4 (XHTML 1) output compatible with modern
-browsers.  For example, to process a reStructuredText file
-"``test.txt``" into HTML::
+browsers that support cascading stylesheets (CSS).  A stylesheet is
+required for proper rendering; an example is provided in
+``tools/stylesheets/default.css`` (see Stylesheets_ below).
 
-    rst2html.py test.txt test.html
+For example, to process a reStructuredText file "``test.txt``" into
+HTML::
+
+    rst2html.py --stylesheet=mystyles.css test.txt test.html
 
 Now open the "``test.html``" file in your favorite browser to see the
 results.  To get a footer with a link to the source file, date & time
 of processing, and links to the Docutils projects, add some options::
 
-    rst2html.py -stg test.txt test.html
+    rst2html.py --stylesheet=mystyles.css -stg test.txt test.html
 
 
 Stylesheets
-- 
cgit v1.2.1


From 25decd0059501f1581c3079896a21626fcdb8174 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 11 Sep 2005 22:26:19 +0000
Subject: updated docs: history and tranform list

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3873 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index cd9cf3fe8..05185d6ef 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -71,6 +71,8 @@ peps.PEPZero                    peps.Headers (t/p)            760
 
 components.Filter               "meta" (d/p)                  780
 
+writer_aux.Compound             newlatex2e (w)                810
+
 universal.Decorations           Transformer                   820
 
 misc.Transitions                standalone (r), pep (r)       830
-- 
cgit v1.2.1


From 245f008322533935ac8e50a8b42d2f303e8c2f68 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 13 Sep 2005 17:23:28 +0000
Subject: added reference to current thread about adaptable file extensions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3876 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index aae1b0d83..18689dd8b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -715,11 +715,13 @@ __ rst/alternatives.html#or-not-to-do
   This may not be just a parser issue; it may need framework support.
 
   Mailing list threads: `Images in both HTML and LaTeX`__ (especially
-  `this summary of Felix's objections`__), `more-universal links?`__
+  `this summary of Felix's objections`__), `more-universal links?`__,
+  `Output-format-sensitive link targets?`__
 
   __ http://thread.gmane.org/gmane.text.docutils.user/1239
   __ http://article.gmane.org/gmane.text.docutils.user/1278
   __ http://thread.gmane.org/gmane.text.docutils.user/1915
+  __ http://thread.gmane.org/gmane.text.docutils.user/2438
 
 * Implement the header row separator modification to table.el.  (Wrote
   to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
-- 
cgit v1.2.1


From bbb4c700f21865d2f925acb7b6b50c2340af1851 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 15 Sep 2005 14:16:46 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3880 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 18689dd8b..c54eb4a9f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1191,6 +1191,8 @@ when used in a document.
 
     - "highlight" a range of lines
 
+    - include only a specified range of lines
+
     - "number" or "line-numbers"
 
     - "styled" could indicate that the directive should check for
-- 
cgit v1.2.1


From 8327158676328972e0e83dd2d7a8f3691d0345d1 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 17 Sep 2005 22:43:04 +0000
Subject: made cloaking of email addresses with ``--cloak-email-addresses``
 less obtrusive; updated documentation; added warning about incorrectly
 decoded cloaked email addresses

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3883 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index ea3916bfc..32be81764 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -564,16 +564,22 @@ attribution
     __ `attribution [latex2e writer]`_
 
 _`cloak_email_addresses`
-    Scramble email addresses to confuse harvesters.  In the visible
-    text of an email address, the "@" and all periods (".") will be
-    surrounded by ``<span>`` tags.  In the reference URI, the address
-    will be replaced by %-escapes.  For example, "abc@example.org"
-    will be output as::
-
-        <a class="reference"
-         href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
+    Scramble email addresses to confuse harvesters.  In the reference
+    URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
+    the visible text (link text) of an email reference, the "@" and
+    all periods (".") will be surrounded by ``<span>`` tags.
+    Furthermore, HTML entities are used to encode these characters in
+    order to further complicate decoding the email address.  For
+    example, "abc@example.org" will be output as::
+
+        <a class="reference" href="mailto:abc%40example.org">
         abc<span>@</span>example<span>.</span>org</a>
 
+    .. Note:: While cloaking email addresses will have little to no
+       impact on the rendering and usability of email links in most
+       browsers, some browsers (e.g. the ``links`` browser) may decode
+       cloaked email addresses incorrectly.
+
     Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
 
 _`compact_lists`
-- 
cgit v1.2.1


From 1920ac5081c5a617abd6a46caca014f62276f83c Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 19 Sep 2005 13:03:58 +0000
Subject: added entry for moving writer support files

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3889 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c54eb4a9f..1d53baf61 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -72,6 +72,23 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Move the following _`support files` to docutils/writers/support:
+
+  - tools/stylesheets/pep.css & default.css (renamed to html4css1.css)
+  - tools/stylesheets/style.tex (renamed to latex2e.tex) & latex.tex
+    (renamed to newlatex2e.tex or newlatex2e/style.tex).
+  - tools/pep-html-template (renamed to pep_html.template or
+    pep_html/template.txt)
+
+  The docutils/writers/support/unicode_latex.py module should probably
+  be moved to newlatex2e/unicode_map.py.
+
+  Add to docs:
+
+      Keep the basenames (e.g. "pep_html") of support files consistent
+      with the writer names.  If there are multiple support files,
+      create a subdirectory whose name matches the writer.
+
 * Move some general-interest sandboxes out of individuals'
   directories, into subprojects?
 
-- 
cgit v1.2.1


From d00d026357ce0a61022bf5a9de8babaddd981912 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 19 Sep 2005 18:36:09 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3890 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 1d53baf61..e4d8186d4 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -74,14 +74,14 @@ General
 
 * Move the following _`support files` to docutils/writers/support:
 
-  - tools/stylesheets/pep.css & default.css (renamed to html4css1.css)
+  - tools/stylesheets/pep.css (renamed to pep_html/pep.css)
+  - tools/stylesheets/default.css (renamed to html4css1.css)
   - tools/stylesheets/style.tex (renamed to latex2e.tex) & latex.tex
-    (renamed to newlatex2e.tex or newlatex2e/style.tex).
-  - tools/pep-html-template (renamed to pep_html.template or
-    pep_html/template.txt)
+    (renamed or newlatex2e/base.tex).
+  - tools/pep-html-template (renamed pep_html/template.txt)
 
-  The docutils/writers/support/unicode_latex.py module should probably
-  be moved to newlatex2e/unicode_map.py.
+  Rename docutils/writers/support/unicode_latex.py to
+  newlatex2e/unicode_map.py.
 
   Add to docs:
 
-- 
cgit v1.2.1


From 5b111006c653af57889892100b7adc5ffcca8e6f Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 20 Sep 2005 20:04:53 +0000
Subject: Merged "transforms" branch into trunk.

- Replaced ``default_transforms`` attribute of TransformSpec with
  ``get_transforms()`` method.
- Added universal.Decorations and universal.ExposeInternals
  transforms as default transforms for all readers.
- Added universal.Messages and universal.FilterMessages transforms
  as default transforms for all writers.
- Added ``ReReader`` base class for readers that reread an existing
  document tree.
- Added ``UnfilteredWriter`` base class for writers that pass the
  document tree on unchanged.


git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3892 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 05185d6ef..8cd01c895 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -73,15 +73,15 @@ components.Filter               "meta" (d/p)                  780
 
 writer_aux.Compound             newlatex2e (w)                810
 
-universal.Decorations           Transformer                   820
+universal.Decorations           Reader (r)                    820
 
 misc.Transitions                standalone (r), pep (r)       830
 
-universal.ExposeInternals       Transformer                   840
+universal.ExposeInternals       Reader (r)                    840
 
-universal.Messages              Transformer                   860
+universal.Messages              Writer (w)                    860
 
-universal.FilterMessages        Transformer                   870
+universal.FilterMessages        Writer (w)                    870
 
 universal.TestMessages          DocutilsTestSupport           880
 
-- 
cgit v1.2.1


From c01aad4e43f778039596074edfe1989e14701290 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 20 Sep 2005 20:06:17 +0000
Subject: fixed malformed hyperlink target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3893 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 9feac9c6a..681cb7ae9 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -79,7 +79,7 @@ For more details on how to write tests, please refer to the
 documentation of the ``unittest`` module.
 
 
-.. _functional::
+.. _functional:
 
 Functional Tests
 ================
-- 
cgit v1.2.1


From b709706e194b0134660d39a918d3f5429fe952ef Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 21 Sep 2005 19:15:45 +0000
Subject: adjusted spec to conform to actual behavior

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3896 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 6bbdd9361..ed6056e96 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -939,14 +939,9 @@ Processed, the "status" element's text will become simply "expansion
 text".  The dollar sign delimiters and leading RCS keyword name are
 removed.
 
-The RCS keyword processing only kicks in when both of these conditions
-hold:
-
-1. The field list is in bibliographic context (first non-comment
-   construct in the document, after a document title if there is
-   one).
-
-2. The field name is a recognized bibliographic field name.
+The RCS keyword processing only kicks in when the field list is in
+bibliographic context (first non-comment construct in the document,
+after a document title if there is one).
 
 
 Option Lists
-- 
cgit v1.2.1


From c976bf8ced13397135c52212701c0ad3aed45013 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 22 Sep 2005 18:51:33 +0000
Subject: changed DanglingReferences priority back to 850

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3897 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/transforms.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 8cd01c895..5e844e45c 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -60,8 +60,6 @@ references.ExternalTargets      standalone (r), pep (r)       640
 
 references.InternalTargets      standalone (r), pep (r)       660
 
-references.DanglingReferences   standalone (r), pep (r)       680
-
 parts.SectNum                   "sectnum" (d/p)               710
 
 parts.Contents                  "contents" (d/p),             720
@@ -79,6 +77,8 @@ misc.Transitions                standalone (r), pep (r)       830
 
 universal.ExposeInternals       Reader (r)                    840
 
+references.DanglingReferences   standalone (r), pep (r)       850
+
 universal.Messages              Writer (w)                    860
 
 universal.FilterMessages        Writer (w)                    870
-- 
cgit v1.2.1


From 1b0c89fafde2292c03a0a21822ba083dca903bb1 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 25 Sep 2005 15:49:54 +0000
Subject: added docutils/writers/support/ directory and removed
 tools/stylesheets/; updated defaults; removed docutils/transforms/html.py (no
 longer needed); removed ``_stylesheet_required`` internal setting; updated
 setup.py

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3901 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/peps/pep-0258.txt  | 21 +++++++++++++++++++--
 docs/ref/transforms.txt |  2 --
 docs/user/config.txt    | 21 +++++++++++----------
 docs/user/tools.txt     | 31 ++++++++++++++++---------------
 4 files changed, 46 insertions(+), 29 deletions(-)

(limited to 'docs')

diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt
index 7779411a6..47ede6c21 100644
--- a/docs/peps/pep-0258.txt
+++ b/docs/peps/pep-0258.txt
@@ -402,6 +402,9 @@ Docutils Package Structure
     - Module "docutils.readers.pep" reads PEPs (Python Enhancement
       Proposals).
 
+    - Module "docutils.readers.doctree" is used to re-read a
+      previously stored document tree for reprocessing.
+
     - Readers to be added for: Python source code (structure &
       docstrings), email, FAQ, and perhaps Wiki and others.
 
@@ -416,18 +419,32 @@ Docutils Package Structure
     - Module "docutils.writers.html4css1" is a simple HyperText Markup
       Language document tree writer for HTML 4.01 and CSS1.
 
+    - Module "docutils.writers.latex2e" writes LaTeX.
+
+    - Module "docutils.writers.newlatex2e" also writes LaTeX; it is a
+      new implementation.
+
     - Module "docutils.writers.docutils_xml" writes the internal
       document tree in XML form.
 
     - Module "docutils.writers.pseudoxml" is a simple internal
       document tree writer; it writes indented pseudo-XML.
 
+    - Module "docutils.writers.null" is a do-nothing writer; it is
+      used for specialized purposes such as storing the internal
+      document tree.
+
     - Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms,
-      such as DocBook), PDF, TeX, plaintext, reStructuredText, and
-      perhaps others.
+      such as DocBook), PDF, plaintext, reStructuredText, and perhaps
+      others.
 
     See `Writers`_ above.
 
+  - Package "docutils.writers.support": modules and data files that
+    support the various writers.  The names of subdirectories and
+    basenames of files immediately within the support/ directory must
+    match the corresponding writer module names.
+
   - Package "docutils.transforms": tree transform classes.
 
     - Class "Transformer" stores transforms and applies them to
diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 5e844e45c..0595175b4 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -40,8 +40,6 @@ peps.Headers                    pep (r)                       360
 
 peps.Contents                   pep (r)                       380
 
-html.StylesheetCheck            html4css1 (w)                 420
-
 references.AnonymousHyperlinks  standalone (r), pep (r)       440
 
 references.IndirectHyperlinks   standalone (r), pep (r)       460
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 32be81764..db38ac1ab 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -662,18 +662,12 @@ stylesheet_path
     relative to the output HTML file.  Also defined for the `LaTeX
     Writer`__.
 
-    Default: None.  Options: ``--stylesheet-path``.
+    Default: "html4css1.css" in the docutils/writers/support directory
+    (installed automatically; for the exact machine-specific path, use
+    the ``--help`` option).  Options: ``--stylesheet-path``.
 
     __ `stylesheet_path [latex2e writer]`_
 
-_`_stylesheet_required`
-    Warn if valid stylesheet settings are absent.  For programmatic
-    use only.
-
-    Default: not required (0), except when using the ``rst2html.py``
-    front-end tool.  No command-line options; pass ``--stylesheet=``
-    (i.e., with no argument) to disable the stylesheet explicitly.
-
 .. _xml_declaration [html4css1 writer]:
 
 xml_declaration
@@ -694,7 +688,14 @@ xml_declaration
 
 The PEP/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
-"[html4css1 writer]" section is processed before "[pep_html writer]".
+"[html4css1 writer]" section of configuration files is processed
+before the "[pep_html writer]" section.
+
+The PEP/HTML Writer's default for the ``stylesheet_path`` setting
+differs from that of the standard HTML Writer:
+``docutils/writers/support/pep_html/pep.css`` in the installation
+directory is used.  For the exact machine-specific path, use the
+``--help`` option.
 
 _`no_random`
     Do not use a random banner image.  Mainly used to get predictable
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 9a2ddbcc4..20e22e356 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -84,10 +84,10 @@ The current directory (and all subdirectories) is chosen by default if
 no directory is named.  Some files may generate system messages
 (docs/user/rst/demo.txt contains intentional errors); use the
 ``--quiet`` option to suppress all warnings.  The ``--config`` option
-ensures that the correct stylesheets, templates, and settings are in
-place (a ``docutils.conf`` configuration file in the current directory
-is picked up automatically).  Command-line options may be used to
-override config file settings or replace them altogether.
+ensures that the correct settings are in place (a ``docutils.conf``
+`configuration file`_ in the current directory is picked up
+automatically).  Command-line options may be used to override config
+file settings or replace them altogether.
 
 
 rst2html.py
@@ -100,8 +100,8 @@ rst2html.py
 The ``rst2html.py`` front end reads standalone reStructuredText source
 files and produces HTML 4 (XHTML 1) output compatible with modern
 browsers that support cascading stylesheets (CSS).  A stylesheet is
-required for proper rendering; an example is provided in
-``tools/stylesheets/default.css`` (see Stylesheets_ below).
+required for proper rendering; a simple but complete stylesheet is
+installed and used by default (see Stylesheets_ below).
 
 For example, to process a reStructuredText file "``test.txt``" into
 HTML::
@@ -110,7 +110,7 @@ HTML::
 
 Now open the "``test.html``" file in your favorite browser to see the
 results.  To get a footer with a link to the source file, date & time
-of processing, and links to the Docutils projects, add some options::
+of processing, and links to the Docutils project, add some options::
 
     rst2html.py --stylesheet=mystyles.css -stg test.txt test.html
 
@@ -120,14 +120,15 @@ Stylesheets
 
 ``rst2html.py`` inserts into the generated HTML a cascading stylesheet
 (or a link to a stylesheet, when passing the "``--link-stylesheet``"
-option).  You must specify the location of the stylesheet (normally
-``tools/stylesheets/default.css`` in the Docutils distribution
-tarball) with a "``--stylesheet``" or "``--stylesheet-path``"
-command-line option unless a configuration file
-(e.g. ``/etc/docutils.conf`` or ``~/.docutils.conf``) does so for you.
-The "``tools/stylesheets/default.css``" stylesheet is provided for
-basic use.  To experiment with styles, please see the `guide to
-writing HTML (CSS) stylesheets for Docutils`__.
+option).  A stylesheet is required for proper rendering.  The default
+stylesheet (``docutils/writers/support/html4css1.css``, located in the
+installation directory) is provided for basic use.  To use a different
+stylesheet, you must specify the stylesheet's location with a
+"``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a local
+file) command-line option, or with `configuration file`_ settings
+(e.g. ``./docutils.conf`` or ``~/.docutils.conf``).  To experiment
+with styles, please see the `guide to writing HTML (CSS) stylesheets
+for Docutils`__.
 
 __ ../howto/html-stylesheets.html
 
-- 
cgit v1.2.1


From bc4e4dd67fb0eab710abe1b8db863e206bf07b49 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 26 Sep 2005 00:42:41 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3902 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 17 -----------------
 1 file changed, 17 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index e4d8186d4..c54eb4a9f 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -72,23 +72,6 @@ for inclusion in the Python standard library.
 General
 =======
 
-* Move the following _`support files` to docutils/writers/support:
-
-  - tools/stylesheets/pep.css (renamed to pep_html/pep.css)
-  - tools/stylesheets/default.css (renamed to html4css1.css)
-  - tools/stylesheets/style.tex (renamed to latex2e.tex) & latex.tex
-    (renamed or newlatex2e/base.tex).
-  - tools/pep-html-template (renamed pep_html/template.txt)
-
-  Rename docutils/writers/support/unicode_latex.py to
-  newlatex2e/unicode_map.py.
-
-  Add to docs:
-
-      Keep the basenames (e.g. "pep_html") of support files consistent
-      with the writer names.  If there are multiple support files,
-      create a subdirectory whose name matches the writer.
-
 * Move some general-interest sandboxes out of individuals'
   directories, into subprojects?
 
-- 
cgit v1.2.1


From cee7d04e88cef9ee98b610bb4b18e373564e0363 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 26 Sep 2005 18:03:22 +0000
Subject: added section for release 0.4

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3907 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c54eb4a9f..46cbf4715 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -35,6 +35,26 @@ Please see also the Bugs_ document for a list of bugs in Docutils.
 .. _bugs: ../../BUGS.html
 
 
+Release 0.4
+===========
+
+We should get Docutils 0.4 out soon.  But we shouldn't just cut a
+"frozen snapshot" release.  Here's a list of features (achievable in
+the short term) to include:
+
+* [DONE in rev. 3901] Move support files to docutils/writers/support.
+
+* [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck
+  (no longer needed because of the above change).
+
+* Incorporate new branch policy into the docs.  [DavidG]
+  ("Development strategy" thread on Docutils-develop)
+
+* Fix East-Asian `double-width characters`_ issue.  [DavidG]
+
+Anything else?
+
+
 Minimum Requirements for Python Standard Library Candidacy
 ==========================================================
 
-- 
cgit v1.2.1


From 56141f49a0dff5ef21cd29e00479f41c4efd88db Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 28 Sep 2005 13:31:55 +0000
Subject: clarification

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3910 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 2908d4959..f67ea4532 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1551,9 +1551,9 @@ base roles:
     specified, a "class" option with the directive argument (role
     name) as the value is implied.  See the class_ directive above.
 
-Specific roles may support other options and/or directive content.
-See the `reStructuredText Interpreted Text Roles`_ document for
-details.
+Specific base roles may support other options and/or directive
+content.  See the `reStructuredText Interpreted Text Roles`_ document
+for details.
 
 .. _reStructuredText Interpreted Text Roles: roles.html
 
-- 
cgit v1.2.1


From 4c16652c99cfc1ba8ec7dd2697d606972a98e952 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 29 Sep 2005 13:10:07 +0000
Subject: Added support for "class" directive content.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3912 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index f67ea4532..88bcbf570 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1391,14 +1391,16 @@ Class
 :Directive Arguments: One or more, required (class names / attribute
                       values).
 :Directive Options: None.
-:Directive Content: None.
+:Directive Content: Optional.  If present, it is interpreted as body
+                    elements.
 
-The "class" directive sets a "class" attribute value on the first
-immediately following non-comment element [#]_.  For details of the
-"class" attribute, see `its entry`__ in `The Docutils Document Tree`_.
-The directive argument consists of one or more space-separated class
-names, which are converted to lowercase and all non-alphanumeric
-characters are converted to hyphens.  (For the rationale, see below.)
+The "class" directive sets the "class" attribute value on its content
+or on the first immediately following non-comment element [#]_.  For
+details of the "class" attribute, see `its entry`__ in `The Docutils
+Document Tree`_.  The directive argument consists of one or more
+space-separated class names, which are converted to lowercase and all
+non-alphanumeric characters are converted to hyphens.  (For the
+rationale, see below.)
 
 __ ../doctree.html#class
 
@@ -1415,6 +1417,12 @@ Examples::
 
     This is an ordinary paragraph.
 
+    .. class:: multiple
+
+       First paragraph.
+
+       Second paragraph.
+
 The text above is parsed and transformed into this doctree fragment::
 
     <paragraph class="special">
@@ -1424,6 +1432,10 @@ The text above is parsed and transformed into this doctree fragment::
             An Exceptional Section
         <paragraph>
             This is an ordinary paragraph.
+        <paragraph class="multiple">
+            First paragraph.
+        <paragraph class="multiple">
+            Second paragraph.
 
 .. [#] To set a "class" attribute value on a block quote, the "class"
    directive must be followed by an empty comment::
-- 
cgit v1.2.1


From 239b6dc3e601ada17264833b47c2cd9bbe9a647d Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 30 Sep 2005 13:04:50 +0000
Subject: updated for new stylesheet location; thanks to Michael Foord for
 pointing this out

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3913 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/howto/html-stylesheets.txt | 35 +++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

(limited to 'docs')

diff --git a/docs/howto/html-stylesheets.txt b/docs/howto/html-stylesheets.txt
index 1ae265e5e..1f61bab5d 100644
--- a/docs/howto/html-stylesheets.txt
+++ b/docs/howto/html-stylesheets.txt
@@ -12,13 +12,16 @@
 
 
 The look of Docutils' HTML output is customizable via a CSS
-stylesheet.  The default stylesheet is called ``default.css`` and can
-be found in the ``tools/stylesheets/`` directory of the Docutils
-distribution tarball.
+stylesheet.  The default stylesheet is called ``html4css1.css`` and
+can be found in the ``writers/support/`` directory of the Docutils
+installation.  Use the command ``rst2html.py --help`` and look at the
+description of the ``--stylesheet-path`` command-line option for the
+exact machine-specific location.
 
-To customize the stylesheet, place a new file (e.g. called
-``my-docutils.css``) in the same directory as ``default.css`` and use
-the following template::
+To customize the stylesheet, first copy ``html4css1.css`` to the same
+place as your output HTML files will go.  Next, place a new file
+(e.g. called ``my-docutils.css``) in the same directory and use the
+following template::
 
     /*
     :Author: Your Name
@@ -29,7 +32,7 @@ the following template::
     detailed description here.]
     */
 
-    @import url(default.css);
+    @import url(html4css1.css);
 
     /* Your customizations go here.  For example: */
 
@@ -42,26 +45,26 @@ Style Sheets`__ and, in particular, their `list of CSS1 properties`__.
 __ http://www.htmlhelp.com/reference/css/
 __ http://www.htmlhelp.com/reference/css/all-properties.html
 
-It is important that you do not edit a copy of ``default.css``
-directly because ``default.css`` is frequently updated with each new
+It is important that you do not edit a copy of ``html4css1.css``
+directly because ``html4css1.css`` is frequently updated with each new
 release of Docutils.
 
-Also make sure that you import ``default.css`` (using "``@import
-url(default.css);``") because the definitions contained in the default
-stylesheet are required for correct rendering (margins, alignment,
-etc.).
+Also make sure that you import ``html4css1.css`` (using "``@import
+url(html4css1.css);``") because the definitions contained in the
+default stylesheet are required for correct rendering (margins,
+alignment, etc.).
 
 If you think your stylesheet is fancy and you would like to let others
 benefit from your efforts, you are encouraged to post the stylesheet
-to the Docutils-users_ mailing list.  We can upload it to the Docutils
-repository if you would like us to do so.
+to the Docutils-users_ mailing list.  We can upload it to the
+`Docutils repository`__ if you would like us to do so.
 
 If you decide to share you stylesheet with other users of Docutils,
 please keep website-specific customizations not applicable to
 Docutils' HTML code in a separate stylesheet.
 
 .. _Docutils-users: ../user/mailing-lists.html#docutils-users
-
+__ http://docutils.sourceforge.net/sandbox/stylesheets/
 
 
 ..
-- 
cgit v1.2.1


From 9e9921fe49c022074aeaa20aff58cfc51828b2c3 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 30 Sep 2005 13:05:06 +0000
Subject: added entry for generic container element

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3914 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 46cbf4715..390273dd2 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -92,6 +92,10 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Add a generic "container" element, equivalent to "inline", to which
+  a "class" attribute can be attached.  Will require a reST directive
+  also.
+
 * Move some general-interest sandboxes out of individuals'
   directories, into subprojects?
 
-- 
cgit v1.2.1


From 7d8c53e396f1ff64640cd8f2f9f093186504f727 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 2 Oct 2005 01:09:01 +0000
Subject: Updated for plural attributes "classes", "ids", "names", "dupnames".

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3916 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt  | 72 ++++++++++++++++++++++++++-------------------------
 docs/ref/docutils.dtd |  8 +++---
 2 files changed, 41 insertions(+), 39 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index 68bfb408f..e6cd509de 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -4421,25 +4421,25 @@ system_message_ elements (via the `%backrefs.att;`_ parameter entity).
 The ``bullet`` attribute is used in the bullet_list_ element.
 
 
-``class``
-=========
+``classes``
+===========
 
 `Attribute type`_: ``NMTOKENS``.  Default value: none.
 
-The ``class`` attribute contains one or more names used to classify an
-element.  The purpose of the attribute is to indicate an "is-a"
-variant relationship, to allow an extensible way of defining
+The ``classes`` attribute is a list containing one or more names used
+to classify an element.  The purpose of the attribute is to indicate
+an "is-a" variant relationship, to allow an extensible way of defining
 sub-classes of existing elements.  It can be used to carry context
 forward between a Docutils Reader and Writer, when a custom structure
 is reduced to a standardized document tree.  One common use is in
 conjunction with stylesheets, to add selection criteria.  It should
 not be used to carry formatting instructions or arbitrary content.
 
-The ``class`` attribute's contents should be ignorable.  Writers that
+The ``classes`` attribute's contents should be ignorable.  Writers that
 are not familiar with the variant expressed should be able to ignore
 the attribute.
 
-``class`` is one of the `common attributes`_, shared by all Docutils
+``classes`` is one of the `common attributes`_, shared by all Docutils
 elements.
 
 
@@ -4451,17 +4451,17 @@ elements.
 The ``delimiter`` attribute is used in the option_argument_ element.
 
 
-``dupname``
-===========
+``dupnames``
+============
 
-`Attribute type`_: ``NMTOKENS``.  Default value: none.
+`Attribute type`_: ``CDATA``.  Default value: none.
 
-The ``dupname`` attribute contains the name of an element when there
-has been a naming conflict.  The contents of the ``dupname`` attribute
-would have been transferred from the `name`_ attribute.  An element
-may have at most one of the ``name`` or ``dupname`` attributes, but
-not both.  ``dupname`` is one of the `common attributes`_, shared by
-all Docutils elements.
+The ``dupnames`` attribute is a list containing the names of an
+element when there has been a naming conflict.  The contents of the
+``dupnames`` attribute would have been transferred from the `names`_
+attribute.  An element may have at most one of the ``names`` or
+``dupnames`` attributes, but not both.  ``dupnames`` is one of the
+`common attributes`_, shared by all Docutils elements.
 
 
 ``enumtype``
@@ -4473,27 +4473,29 @@ all Docutils elements.
 The ``enumtype`` attribute is used in the enumerated_list_ element.
 
 
-``id``
-======
+``ids``
+=======
 
-`Attribute type`_: ``ID``.  Default value: none.
+`Attribute type`_: ``NMTOKENS``.  Default value: none.
 
-The ``id`` attribute contains a unique identifier key.  ``id`` is one
-of the `common attributes`_, shared by all Docutils elements.
+The ``ids`` attribute is a list containing one or more unique
+identifier keys.  ``ids`` is one of the `common attributes`_, shared
+by all Docutils elements.
 
 
-``name``
-========
+``names``
+=========
 
-`Attribute type`_: ``NMTOKENS``.  Default value: none.
+`Attribute type`_: ``CDATA``.  Default value: none.
 
-The ``name`` attribute contains the name of an element, typically
-originating from the element's title or content.  ``name`` must be
-unique; if there are name conflicts (two or more elements want to the
-same name), the contents will be transferred to the `dupname`_
-attribute on the duplicate elements.  An element may have at most one
-of the ``name`` or ``dupname`` attributes, but not both.  ``name`` is
-one of the `common attributes`_, shared by all Docutils elements.
+The ``names`` attribute is a list containing the names of an element,
+typically originating from the element's title or content.  Each name
+in ``names`` must be unique; if there are name conflicts (two or more
+elements want to the same name), the contents will be transferred to
+the `dupnames`_ attribute on the duplicate elements.  An element may
+have at most one of the ``names`` or ``dupnames`` attributes, but not
+both.  ``names`` is one of the `common attributes`_, shared by all
+Docutils elements.
 
 
 ``prefix``
@@ -4668,11 +4670,11 @@ Entity definition:
 
 .. parsed-literal::
 
-    id_       ID        #IMPLIED
-    name_     NMTOKENS  #IMPLIED
-    dupname_  NMTOKENS  #IMPLIED
+    ids_      NMTOKENS  #IMPLIED
+    names_    CDATA     #IMPLIED
+    dupnames_ CDATA     #IMPLIED
     source_   CDATA     #IMPLIED
-    class_    NMTOKENS  #IMPLIED
+    classes_  NMTOKENS  #IMPLIED
     %additional.basic.atts;
 
 The ``%additional.basic.atts;`` parameter entity can be used by
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index f6628684a..c2024391f 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -53,11 +53,11 @@ Attributes shared by all elements in this DTD:
 - `class` is used to transmit individuality information forward.
 -->
 <!ENTITY % basic.atts
-  " id        ID        #IMPLIED
-    name      CDATA     #IMPLIED
-    dupname   CDATA     #IMPLIED
+  " ids       NMTOKENS  #IMPLIED
+    names     CDATA     #IMPLIED
+    dupnames  CDATA     #IMPLIED
     source    CDATA     #IMPLIED
-    class     NMTOKENS  #IMPLIED
+    classes   NMTOKENS  #IMPLIED
     %additional.basic.atts; ">
 
 <!-- External reference to a URI/URL. -->
-- 
cgit v1.2.1


From 5ba8d0c43d40007f043459bdf0f842ca52d9add7 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 2 Oct 2005 04:39:00 +0000
Subject: fixed references

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3917 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt | 148 +++++++++++++++++++++++++--------------------------
 1 file changed, 74 insertions(+), 74 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index e6cd509de..caffc3a89 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -340,8 +340,8 @@ Content Model
     `%text.model;`_
 
 :Attributes:
-    The ``address`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus `xml:space`_.
+    The ``address`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus `xml:space`_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -413,7 +413,7 @@ Content Model
 
 :Attributes:
     The ``admonition`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -480,7 +480,7 @@ Content Model
 
 :Attributes:
     The ``attention`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -542,7 +542,7 @@ Content Model
 
 :Attributes:
     The ``author`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -608,7 +608,7 @@ Content Model
 
 :Attributes:
     The ``authors`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -686,7 +686,7 @@ Content Model
 
 :Attributes:
     The ``block_quote`` element contains only the `common
-    attributes`_: id_, name_, dupname_, source_, and class_.
+    attributes`_: ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -760,7 +760,7 @@ Content Model
 
 :Attributes:
     The ``bullet_list`` element contains the `common attributes`_
-    (id_, name_, dupname_, source_, and class_), plus bullet_.
+    (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
 
     ``bullet`` is used to record the style of bullet from the input
     data.  In documents processed from reStructuredText_, it contains
@@ -844,7 +844,7 @@ Content Model
 
 :Attributes:
     The ``caution`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -915,7 +915,7 @@ Content Model
 
 :Attributes:
     The ``classifier`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1005,7 +1005,7 @@ Content Model
 
 :Attributes:
     The ``contact`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -1071,7 +1071,7 @@ Content Model
 
 :Attributes:
     The ``copyright`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -1142,7 +1142,7 @@ Content Model
 
 :Attributes:
     The ``danger`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -1199,7 +1199,7 @@ Content Model
 
 :Attributes:
     The ``date`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -1270,7 +1270,7 @@ empty ``decoration`` elements are ever created.
 
 :Attributes:
     The ``decoration`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1329,7 +1329,7 @@ Content Model
 
 :Attributes:
     The ``definition`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1380,7 +1380,7 @@ Content Model
 
 :Attributes:
     The ``definition_list`` element contains only the `common
-    attributes`_: id_, name_, dupname_, source_, and class_.
+    attributes`_: ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -1462,7 +1462,7 @@ Content Model
 
 :Attributes:
     The ``definition_list_item`` element contains only the `common
-    attributes`_: id_, name_, dupname_, source_, and class_.
+    attributes`_: ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1542,7 +1542,7 @@ Content Model
 
 :Attributes:
     The ``description`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1600,7 +1600,7 @@ Content Model
 
 :Attributes:
     The ``docinfo`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -1706,7 +1706,7 @@ Content Model
 
 :Attributes:
     The ``doctest_block`` element contains the `common attributes`_
-    (id_, name_, dupname_, source_, and class_), plus `xml:space`_.
+    (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -1785,8 +1785,8 @@ See the `%structure.model;`_ parameter entity for details of the body
 of a ``document``.
 
 :Attributes:
-    The ``document`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus an optional title__
+    The ``document`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus an optional title__
     attribute which stores the document title metadata.
 
     __ `title (attribute)`_
@@ -1873,7 +1873,7 @@ Content Model
 
 :Attributes:
     The ``enumerated_list`` element contains the `common attributes`_
-    (id_, name_, dupname_, source_, and class_), plus enumtype_,
+    (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
     prefix_, suffix_, and start_.
 
     ``enumtype`` is used to record the intended enumeration sequence,
@@ -1980,8 +1980,8 @@ Content Model
    (`%body.elements;`_)+
 
 :Attributes:
-    The ``error`` element contains only the `common attributes`_: id_,
-    name_, dupname_, source_, and class_.
+    The ``error`` element contains only the `common attributes`_: ids_,
+    names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2040,7 +2040,7 @@ Content Model
 
 :Attributes:
     The ``field`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -2088,7 +2088,7 @@ Content Model
 
 :Attributes:
     The ``field_body`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -2142,7 +2142,7 @@ Content Model
 
 :Attributes:
     The ``field_list`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2224,7 +2224,7 @@ Content Model
 
 :Attributes:
     The ``field_name`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -2276,7 +2276,7 @@ Content Model
 
 :Attributes:
     The ``footer`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -2356,7 +2356,7 @@ Content Model
 
 :Attributes:
     The ``header`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -2416,8 +2416,8 @@ Content Model
    (`%body.elements;`_)+
 
 :Attributes:
-    The ``hint`` element contains only the `common attributes`_: id_,
-    name_, dupname_, source_, and class_.
+    The ``hint`` element contains only the `common attributes`_: ids_,
+    names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2486,7 +2486,7 @@ Content Model
 
 :Attributes:
     The ``important`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2577,8 +2577,8 @@ Content Model
    `%text.model;`_
 
 :Attributes:
-    The ``line`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus `xml:space`_.
+    The ``line`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus `xml:space`_.
 
 
 Examples
@@ -2632,8 +2632,8 @@ Content Model
    (line_ | line_block_)+
 
 :Attributes:
-    The ``line_block`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus `xml:space`_.
+    The ``line_block`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus `xml:space`_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2740,7 +2740,7 @@ Content Model
 
 :Attributes:
     The ``list_item`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -2825,7 +2825,7 @@ Content Model
 
 :Attributes:
     The ``literal_block`` element contains the `common attributes`_
-    (id_, name_, dupname_, source_, and class_), plus `xml:space`_.
+    (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2896,8 +2896,8 @@ Content Model
    (`%body.elements;`_)+
 
 :Attributes:
-    The ``note`` element contains only the `common attributes`_: id_,
-    name_, dupname_, source_, and class_.
+    The ``note`` element contains only the `common attributes`_: ids_,
+    names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -2957,7 +2957,7 @@ Content Model
 
 :Attributes:
     The ``option`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3004,8 +3004,8 @@ Content Model
    (#PCDATA)
 
 :Attributes:
-    The ``option_argument`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus delimiter_.
+    The ``option_argument`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus delimiter_.
 
     ``delimiter`` contains the text preceding the ``option_argument``:
     either the text separating it from the option_string_ (typically
@@ -3060,7 +3060,7 @@ Content Model
 
 :Attributes:
     The ``option_group`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3111,7 +3111,7 @@ Content Model
 
 :Attributes:
     The ``option_list`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -3197,7 +3197,7 @@ Content Model
 
 :Attributes:
     The ``option_list_item`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3242,7 +3242,7 @@ Content Model
 
 :Attributes:
     The ``option_string`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3288,7 +3288,7 @@ Content Model
 
 :Attributes:
     The ``organization`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -3354,7 +3354,7 @@ Content Model
 
 :Attributes:
     The ``paragraph`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -3437,7 +3437,7 @@ Content Model
 
 :Attributes:
     The ``revision`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -3533,7 +3533,7 @@ of a ``section``.
 
 :Attributes:
     The ``section`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%section.elements;`_ parameter entity directly includes
@@ -3639,7 +3639,7 @@ Content Model
 
 :Attributes:
     The ``sidebar`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%structure.model;`_ parameter entity directly includes
@@ -3705,7 +3705,7 @@ Content Model
 
 :Attributes:
     The ``status`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -3795,7 +3795,7 @@ Content Model
 
 :Attributes:
     The ``subtitle`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3824,7 +3824,7 @@ Complete pseudo-XML_ result after parsing and applying transforms::
 
 Note how two section levels have collapsed, promoting their titles to
 become the document's title and subtitle.  Since there is only one
-structural element (document), the subsection's ``id`` and ``name``
+structural element (document), the subsection's ``ids`` and ``names``
 attributes are stored in the ``subtitle`` element.
 
 
@@ -3894,7 +3894,7 @@ Content Model
 
 :Attributes:
     The ``term`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 
 Examples
@@ -3955,8 +3955,8 @@ Content Model
    (`%body.elements;`_)+
 
 :Attributes:
-    The ``tip`` element contains only the `common attributes`_: id_,
-    name_, dupname_, source_, and class_.
+    The ``tip`` element contains only the `common attributes`_: ids_,
+    names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes ``tip``.
@@ -4013,8 +4013,8 @@ Content Model
     `%text.model;`_
 
 :Attributes:
-    The ``title`` element contains the `common attributes`_ (id_,
-    name_, dupname_, source_, and class_), plus refid_ and auto_.
+    The ``title`` element contains the `common attributes`_ (ids_,
+    names_, dupnames_, source_, and classes_), plus refid_ and auto_.
 
     ``refid`` is used as a backlink to a table of contents entry.
 
@@ -4089,7 +4089,7 @@ Content Model
 
 :Attributes:
     The ``topic`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%structure.model;`_ parameter entity directly includes
@@ -4174,7 +4174,7 @@ The ``transition`` element has no content; it is a "point element".
 
 :Attributes:
     The ``transition`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%structure.model;`_ parameter entity directly includes
@@ -4240,7 +4240,7 @@ Content Model
 
 :Attributes:
     The ``version`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%bibliographic.elements;`_ parameter entity directly includes
@@ -4310,7 +4310,7 @@ Content Model
 
 :Attributes:
     The ``warning`` element contains only the `common attributes`_:
-    id_, name_, dupname_, source_, and class_.
+    ids_, names_, dupnames_, source_, and classes_.
 
 :Parameter Entities:
     The `%body.elements;`_ parameter entity directly includes
@@ -4340,8 +4340,8 @@ Pseudo-XML_ fragment from simple parsing::
               :depth: 1
 
 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
-all elements contain the following attributes: id_, name_, dupname_,
-source_, and class_.
+all elements contain the following attributes: ids_, names_, dupnames_,
+source_, and classes_.
 
 .. _attribute type:
 
@@ -4408,7 +4408,7 @@ footnote_, footnote_reference_ and title_ elements (via the
 
 `Attribute type`_: ``IDREFS``.  Default value: none.
 
-The ``backrefs`` attribute contains a space-separated list of id_
+The ``backrefs`` attribute contains a space-separated list of ids_
 references, used for backlinks from footnote_, citation_, and
 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
 
@@ -4511,7 +4511,7 @@ The ``prefix`` attribute is used in the enumerated_list_ element.
 
 `Attribute type`_: ``IDREF``.  Default value: none.
 
-The ``refid`` attribute contains references to `id`_ attributes in
+The ``refid`` attribute contains references to `ids`_ attributes in
 other elements.  It is used by the target_, reference_,
 footnote_reference_, citation_reference_, title_ and problematic_
 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
@@ -4524,7 +4524,7 @@ entities).
 `Attribute type`_: ``NMTOKENS``.  Default value: none.
 
 The ``refname`` attribute contains an internal reference to the
-`name`_ attribute of another element.  On a `target`_ element,
+`names`_ attribute of another element.  On a `target`_ element,
 ``refname`` indicates an indirect target which may resolve to either
 an internal or external reference.  ``refname`` is used by the
 target_, reference_, footnote_reference_, citation_reference_, and
@@ -4817,7 +4817,7 @@ their attribute lists.
 ================
 
 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
-internal reference to the `id`_ attribute of another element.
+internal reference to the `ids`_ attribute of another element.
 
 Entity definition:
 
@@ -4837,7 +4837,7 @@ footnote_reference_, reference_, and target_ elements.
 =================
 
 The ``%refname.att;`` parameter entity contains the refname_
-attribute, an internal reference to the `name`_ attribute of another
+attribute, an internal reference to the `names`_ attribute of another
 element.  On a `target`_ element, ``refname`` indicates an indirect
 target which may resolve to either an internal or external
 reference.
-- 
cgit v1.2.1


From c54c65baf381ec76c7041b10d14ba19531f6e604 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 4 Oct 2005 18:33:57 +0000
Subject: added to do list entry about "raw-wrapped" base role

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3923 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 390273dd2..6541d41ca 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1357,6 +1357,36 @@ any knowledge of the Python-Reader origin of these elements.
 
 * Implement roles:
 
+  - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
+    around role contents.
+
+    For example, the following reStructuredText source ... ::
+
+        .. role:: red(raw-formatting)
+           :prefix:
+               :html: <font color="red">
+               :latex: {\color{red}
+           :suffix:
+               :html: </font>
+               :latex: }
+
+        colored :red:`text`
+
+    ... will yield the following document fragment::
+
+        <paragraph>
+            colored
+            <inline classes="red">
+                <raw format="html">
+                    <font color="red">
+                <raw format="latex">
+                    {\color{red}
+                text
+                <raw format="html">
+                    </font>
+                <raw format="latex">
+                    }
+
   - "acronym" and "abbreviation": Associate the full text with a short
     form.  Jason Diamond's description:
 
-- 
cgit v1.2.1


From 641669c1961739317cead6b48445e972e70b6e71 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 5 Oct 2005 01:45:59 +0000
Subject: added entry about --strip-comments option

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3924 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 6541d41ca..c45a26dfc 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -92,6 +92,12 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Add a --strip-comments command-line option (& strip_comments runtime
+  setting), declared in docutils/frontend.py, and implemented as a
+  transform.  This feature isn't specific to rst2html.py, or to the
+  HTML Writer, or to the reST parser; it applies to Docutils as a
+  whole.  See <http://thread.gmane.org/gmane.text.docutils.devel/3216>.
+
 * Add a generic "container" element, equivalent to "inline", to which
   a "class" attribute can be attached.  Will require a reST directive
   also.
-- 
cgit v1.2.1


From eabdac6b7d7561c4325f483b7d94eb307504ff73 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 5 Oct 2005 01:50:28 +0000
Subject: added entry about indirect citation/footnote links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3925 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c45a26dfc..1a9fd1d98 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -660,6 +660,16 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Add indirect links via citation references & footnote references.
+  Example::
+
+      `Goodger (2005)`_ is helpful.
+
+      .. _Goodger (2005): [goodger2005]_
+      .. [goodger2005] citation text
+
+  See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
+
 * Allow multiple block quotes, only separated by attributions
   (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.::
 
-- 
cgit v1.2.1


From 554fd14a2991750dd134aee52d40c6806aa0e8ad Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 11 Oct 2005 13:14:13 +0000
Subject: clarified row separators in simple tables

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3932 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index ed6056e96..921ac31a4 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1390,7 +1390,8 @@ Simple tables are described with horizontal borders made up of "=" and
 "-" characters.  The equals sign ("=") is used for top and bottom
 table borders, and to separate optional header rows from the table
 body.  The hyphen ("-") is used to indicate column spans in a single
-row by underlining the joined columns.
+row by underlining the joined columns, and may optionally be used to
+explicitly and/or visually separate rows.
 
 A simple table begins with a top border of equals signs with one or
 more spaces at each column boundary (two or more spaces recommended).
-- 
cgit v1.2.1


From 5da7532801abf44378d5422760ab68a84bc39fbc Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 11 Oct 2005 23:00:39 +0000
Subject: removed references to default.css; to-do: update PEP writer (->
 pep.css) and then docs/user/tools.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3940 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 43 ++++++++++---------------------------------
 docs/dev/hacking.txt      |  4 ++--
 docs/dev/testing.txt      |  2 +-
 3 files changed, 13 insertions(+), 36 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index c1cfc3603..e4495512c 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -87,7 +87,9 @@ The documentation should be generated using ``buildhtml.py``.  To
 generate HTML for all documentation files, go to the ``tools/``
 directory and run::
 
-    ./buildhtml.py ..
+    # Place html4css1.css in base directory.
+    cp ../docutils/writers/support/html4css1.css ..
+    ./buildhtml.py --stylesheet-path=../html4css1.css ..
 
 Then install the following files to ``/usr/share/doc/docutils/`` (or
 wherever you install documentation):
@@ -102,15 +104,7 @@ wherever you install documentation):
 
 * The ``licenses/`` directory.
 
-* ``tools/stylesheets/default.css``, creating the ``tools/`` and
-  ``tools/stylesheets/`` directory beforehand.  This file is needed
-  for correct viewing of the HTML files.  The remaining contents of
-  the ``tools/`` and ``tools/stylesheets/`` directories are not
-  needed.
-
-  Be sure not to install ``default.css`` into the root of the
-  documentation directory, or the relative references to the
-  stylesheet will not work.
+* ``html4css1.css`` in the base directory.
 
 
 Removing the ``.txt`` Files
@@ -126,40 +120,23 @@ the tree except for:
   be readable in source form.
 
 Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
-as ``./buildhtml.py .. --no-source-link`` to avoid broken references
-to the source files.
+with the ``--no-source-link`` switch to avoid broken references to the
+source files.
 
 
 Other Files
 ===========
 
-Install ``tools/stylesheets/`` to ``/usr/lib/docutils/stylesheets/``
-and ``tools/pep-html-template`` to
-``/usr/lib/docutils/pep-html-template``.
-
-You may also want to install the Emacs-Lisp files
+You may want to install the Emacs-Lisp files
 ``tools/editors/emacs/*.el`` into the appropriate directory.
 
 
 Configuration File
 ==================
 
-The system-wide configuration file is located in
-``/etc/docutils.conf``.  You should *not* install
-``tools/docutils.conf`` into ``/etc/``.  Instead, we recommend that
-you create a new ``/etc/docutils.conf`` file containing references to
-the appropriate files on your system::
-
-    [html4css1 writer]
-    # These entries affect HTML output:
-    stylesheet-path: /usr/lib/docutils/stylesheets/default.css
-
-    [pep_html writer]
-    # These entries affect reStructuredText-style PEPs:
-    template: /usr/lib/docutils/pep-html-template
-    stylesheet-path: /usr/lib/docutils/stylesheets/pep.css
-
-(Adjust the paths as necessary.)
+It is possible to have a system-wide configuration file at
+``/etc/docutils.conf``.  However, this is usually not necessary.  You
+should *not* install ``tools/docutils.conf`` into ``/etc/``.
 
 
 Tests
diff --git a/docs/dev/hacking.txt b/docs/dev/hacking.txt
index ab0c85259..dcbc80943 100644
--- a/docs/dev/hacking.txt
+++ b/docs/dev/hacking.txt
@@ -158,7 +158,7 @@ HTML writer in this case (``docutils/writers/html4css1.py``).
 The writer receives the node tree and returns the output document.
 For HTML output, we can test this using the ``rst2html.py`` tool::
 
-    $ rst2html.py test.txt
+    $ rst2html.py --link-stylesheet test.txt
     <?xml version="1.0" encoding="utf-8" ?>
     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
@@ -166,7 +166,7 @@ For HTML output, we can test this using the ``rst2html.py`` tool::
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
     <title>
-    
+    
     
     
     
    
diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 681cb7ae9..fc6feae2b 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -134,7 +134,7 @@ For example, ``functional/tests/some_test.py`` could read like this::
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
     # Relative to main ``test/`` directory.
-    settings_overrides['stylesheet_path'] = '../tools/stylesheets/default.css'
+    settings_overrides['stylesheet_path'] = '../docutils/writers/support/html4css1.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
-- 
cgit v1.2.1


From 67d3d970573174d53ca2f814f1205864470ecd91 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Fri, 14 Oct 2005 16:42:15 +0000
Subject: updated tools.txt to match recent reorganisation; fixed some relicts;
 esp. the "pep2html.py" section has been deleted; the script is no longer
 included in the Docutils distribution (maybe you want to use the text
 somewhere else, David?)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3942 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/tools.txt | 60 ++++++++++-------------------------------------------
 1 file changed, 11 insertions(+), 49 deletions(-)

(limited to 'docs')

diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 20e22e356..887959613 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -106,13 +106,13 @@ installed and used by default (see Stylesheets_ below).
 For example, to process a reStructuredText file "``test.txt``" into
 HTML::
 
-    rst2html.py --stylesheet=mystyles.css test.txt test.html
+    rst2html.py test.txt test.html
 
 Now open the "``test.html``" file in your favorite browser to see the
 results.  To get a footer with a link to the source file, date & time
 of processing, and links to the Docutils project, add some options::
 
-    rst2html.py --stylesheet=mystyles.css -stg test.txt test.html
+    rst2html.py -stg test.txt test.html
 
 
 Stylesheets
@@ -126,9 +126,9 @@ installation directory) is provided for basic use.  To use a different
 stylesheet, you must specify the stylesheet's location with a
 "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a local
 file) command-line option, or with `configuration file`_ settings
-(e.g. ``./docutils.conf`` or ``~/.docutils.conf``).  To experiment
-with styles, please see the `guide to writing HTML (CSS) stylesheets
-for Docutils`__.
+(e.g. ``./docutils.conf`` or ``~/.docutils``).  To experiment with
+styles, please see the `guide to writing HTML (CSS) stylesheets for
+Docutils`__.
 
 __ ../howto/html-stylesheets.html
 
@@ -143,52 +143,14 @@ rstpep2html.py
 ``rstpep2html.py`` reads a new-style PEP (marked up with
 reStructuredText) and produces HTML.  It requires a template file and
 a stylesheet.  By default, it makes use of a "``pep-html-template``"
-file and a "``default.css``" stylesheet in the current directory, but
-these can be overridden by command-line options or configuration
-files.  The "``tools/stylesheets/pep.css``" stylesheet is intended
-specifically for PEP use.
-
-The "``docutils.conf``" `configuration file`_ in the "``tools``"
-directory of Docutils contains a default setup for use in processing
-the PEP files (``docs/peps/pep-*.txt``) into HTML.  It specifies a
-default template (``tools/pep-html-template``) and a default
-stylesheet (``tools/stylesheets/pep.css``).  See Stylesheets_ above
-for more information.
-
-``rstpep2html.py`` can be run from the ``tools`` directory or from the
-``docs/peps/`` directory, by adjusting the settings.  These two sets
-of commands are equivalent::
-
-    cd /tools
-    # This will pick up the "docutils.conf" file automatically:
-    rstpep2html.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html
-
-    cd /docs/peps
-    # Must tell the tool where to find the config file:
-    ../../tools/rstpep2html.py --config ../../tools/docutils.conf \
-        pep-0287.txt pep-0287.html
+file and the "``pep.css``" stylesheet (both in the
+``docutils/writers/support/`` directory), but these can be overridden
+by command-line options or configuration files.
 
+For example, to process a PEP into HTML::
 
-pep2html.py
------------
-
-:Reader: PEP
-:Parser: reStructuredText
-:Writer: PEP/HTML
-
-``pep2html.py`` is a modified version of the original script by
-Fredrik Lundh, with support for Docutils added.  It reads the
-beginning of a PEP text file to determine the format (old-style
-indented or new-style reStructuredText) and processes accordingly.
-Since it does not use the Docutils front end mechanism (the common
-command-line options are not supported), it can only be configured
-using `configuration files`_.  The template and stylesheet
-requirements of ``pep2html.py`` are the same as those of
-`rstpep2html.py`_ above.
-
-Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
-files.  If no arguments are given, all files of the form
-"``pep-*.txt``" are processed.
+    cd /docs/peps
+    rstpep2html.py pep-0287.txt pep-0287.html
 
 
 rst2latex.py
-- 
cgit v1.2.1


From cf20217231f6f941b8e149e55f60c628141d70b2 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 16 Oct 2005 12:04:22 +0000
Subject: fixed internal link to "rstpep2html.py"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3943 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/tools.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 887959613..48105e1ba 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -27,10 +27,11 @@ pattern::
 
     toolname [options] [ [
Date: Sun, 23 Oct 2005 20:34:38 +0000
Subject: added to-do list entry about false positives with list recognition

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3947 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 1a9fd1d98..397fa2299 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -660,6 +660,19 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* The current list-recognition logic has too many false positives, as
+  in ::
+
+      * Aorta
+      * V. cava superior
+      * V. cava inferior
+
+  Here ``V.`` is recognized as an enumerator, which leads to
+  confusion.  We need to find a solution that resolves such problems
+  without complicating the spec to much.
+
+  See .
+
 * Add indirect links via citation references & footnote references.
   Example::
 
-- 
cgit v1.2.1


From d30297348e43d04a8006c12b35f407141b499dae Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 26 Oct 2005 11:48:21 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3950 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 397fa2299..706f19b61 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -38,7 +38,7 @@ Please see also the Bugs_ document for a list of bugs in Docutils.
 Release 0.4
 ===========
 
-We should get Docutils 0.4 out soon.  But we shouldn't just cut a
+We should get Docutils 0.4 out soon, but we shouldn't just cut a
 "frozen snapshot" release.  Here's a list of features (achievable in
 the short term) to include:
 
@@ -54,6 +54,18 @@ the short term) to include:
 
 Anything else?
 
+Once released,
+
+* Tag it and create a maintenance branch (perhaps "maint-0-4").
+
+* Declare that:
+
+  - Docutils 0.4.x is the last version that will support Python 2.1
+    (and perhaps higher?)
+
+  - Docutils 0.4.x is the last version that will support (make
+    compromises for) Netscape Navigator 4
+
 
 Minimum Requirements for Python Standard Library Candidacy
 ==========================================================
@@ -92,6 +104,9 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Change the docutils-update script (in sandbox/infrastructure), to
+  support arbitrary branch snapshots.
+
 * Add a --strip-comments command-line option (& strip_comments runtime
   setting), declared in docutils/frontend.py, and implemented as a
   transform.  This feature isn't specific to rst2html.py, or to the
@@ -817,8 +832,12 @@ __ rst/alternatives.html#or-not-to-do
   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?
+* The "doctest" element should go away.  The construct could simply be
+  a front-end to generic literal blocks.  We could immediately (in
+  0.4, or 0.5) remove the doctest node from the doctree, but leave the
+  syntax in reST.  The reST parser could represent doctest blocks as
+  literal blocks with a class attribute.  The syntax could be left in
+  reST for a set period of time.
 
 * Add support for pragma (syntax-altering) directives.
 
@@ -1137,6 +1156,11 @@ when used in a document.
   - _`misc.settings`: Set any(?) Docutils runtime setting from within
     a document?  Needs much thought and discussion.
 
+  - _`misc.gather`: Gather (move, or copy) all instances of a specific
+    element.  A generalization of the "endnotes" & "citations" ideas.
+
+  - Add a "directive" directive, equivalent to "role"?
+
   - .. _conditional directives:
 
     Docutils already has the ability to say "use this content for
-- 
cgit v1.2.1


From 56626f76d702387823fa3f455c136e9c7069b6c9 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 26 Oct 2005 11:57:06 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3952 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/website.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/website.txt b/docs/dev/website.txt
index e54acb802..193e9c0f2 100644
--- a/docs/dev/website.txt
+++ b/docs/dev/website.txt
@@ -31,10 +31,10 @@ After adding directories to SVN, 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 located as
-``sandbox/davidg/infrastructure/docutils-update``.
+The docutils-update__ script is located at
+``sandbox/infrastructure/docutils-update``.
 
-__ http://docutils.sf.net/sandbox/davidg/infrastructure/docutils-update
+__ http://docutils.sf.net/sandbox/infrastructure/docutils-update
 
 
 ..
-- 
cgit v1.2.1


From 09990717cff73a01c118f208643551e47871f032 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 27 Oct 2005 01:28:36 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3954 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 706f19b61..11c8046ab 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1012,6 +1012,9 @@ __ rst/alternatives.html#or-not-to-do
 
   .. _list-table: ../ref/rst/directives.html#list-table
 
+* Generalize docinfo contents (bibliographic fields): remove specific
+  fields, and have only a single generic "field"?
+
 
 Directives
 ----------
-- 
cgit v1.2.1


From 2b57cc35ca4e7793926e93ad1f7642acac61f5df Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 28 Oct 2005 16:11:45 +0000
Subject: clarified role of indentation

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3960 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 921ac31a4..3359d19a7 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -241,15 +241,14 @@ line of a document is treated as if it is followed by a blank line.
 Indentation
 -----------
 
-Indentation is used to indicate, and is only significant in
-indicating:
-
-- multi-line contents of list items,
-- multiple body elements within a list item (including nested lists),
-- the definition part of a definition list item,
-- block quotes,
-- the extent of literal blocks, and
-- the extent of explicit markup blocks.
+Indentation is used to indicate -- and is only significant in
+indicating -- block quotes, definitions (in definition list items),
+and local nested content:
+
+- list item content (multi-line contents of list items, and multiple
+  body elements within a list item, including nested lists),
+- the content of literal blocks, and
+- the content of explicit markup blocks.
 
 Any text whose indentation is less than that of the current level
 (i.e., unindented text or "dedents") ends the current level of
-- 
cgit v1.2.1


From 346f8dfa0961a46400be6764ea74337b5e13c7b6 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 28 Oct 2005 16:12:07 +0000
Subject: updated the project policies for trunk/branch development & version
 numbering

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3961 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt   | 388 +++++++++++++++++++++++++++++-------------------
 docs/dev/repository.txt |  23 +--
 docs/dev/testing.txt    |  54 ++++++-
 3 files changed, 302 insertions(+), 163 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 3feae2f30..e09f5ea67 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -10,17 +10,17 @@
 
 .. contents::
 
-Docutils is a meritocracy based on code contribution and lots of
-discussion [#bcs]_.  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:
+The Docutils project group is a meritocracy based on code contribution
+and lots of discussion [#bcs]_.  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?
+As architect, chief cook and bottle-washer, David Goodger currently
+functions as BDFN (Benevolent Dictator For Now).  (But he 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`_:
@@ -32,10 +32,10 @@ his essay `The Magic Cauldron`_:
     .. _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
+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";
+guidelines, not absolutes.  Exceptions are expected, tolerated, and
 used as a source of improvement.  Feedback and criticism is welcome.
 
 As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
@@ -51,25 +51,24 @@ originators of Ogg Vorbis) put it well when he said:
 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.
+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 and extensions:
 
-* 4 spaces per indentation level.  No tabs.
+* 4 spaces per indentation level.  No hard tabs.
 
-* Use only ASCII, no 8-bit strings.  See `Docutils
+* Use only 7-bit 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.).
+  definitions (i.e., ``class X: pass`` is OK.).
 
 * Lines should be no more than 78 characters long.
 
@@ -109,7 +108,8 @@ Documentation Conventions
 
 * Docutils documentation is written using reStructuredText, of course.
 
-* Use 7-bit ASCII if at all possible.
+* Use 7-bit ASCII if at all possible, and Unicode substitutions when
+  necessary.
 
 * Use the following section title adornment styles::
 
@@ -121,16 +121,20 @@ Documentation Conventions
        Document Subtitle (optional)
       ------------------------------
 
+      (The doc. subtitle adornment style can also be used for major
+      top-level sections.)
+
       Section
       =======
 
       Subsection
       ----------
 
-  If you need subsubsections and further, these characters are
-  recommended for title underlines::
+      Sub-Subsection
+      ``````````````
 
-      ` .
+      Sub-Sub-Subsection
+      ..................
 
 * Use two blank lines before each section/subsection/etc. title.  One
   blank line is sufficient between immediately adjacent titles.
@@ -138,7 +142,7 @@ Documentation Conventions
 * Add a bibliographic field list immediately after the document
   title/subtitle.  See the beginning of this document for an example.
 
-* Add an Emacs local variables block in a comment at the end of the
+* Add an Emacs "local variables" block in a comment at the end of the
   document.  See the end of this document for an example.
 
 
@@ -169,120 +173,121 @@ 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.
+PSF.  The PSF accepts the `Academic Free License v. 2.1
+`_ and the `Apache
+License, Version 2.0 `_.
 
 
-Subversion Check-ins
-====================
+Subversion Repository
+=====================
 
 Please see the `repository documentation`_ for details on how to
 access Docutils' Subversion repository.  Anyone can access the
 repository anonymously.  Only project developers can make changes.
-Also see `Setting Up For Docutils Development`_ below for more info.
+(If you would like to become a project developer, just ask!)  Also see
+`Setting Up For Docutils Development`_ below for some useful info.
 
-.. _repository documentation: repository.html
+.. Caution::
 
-Unless you really *really* know what you're doing, please limit your
-Subversion commands to ``svn checkout``, ``svn commit``, and ``svn
-add``.  Do **NOT** use ``svn import`` unless you're absolutely sure
-you know what you're doing.  Even then, grab a copy of the `nightly
-repository tarball`_, set it up on your own machine, and experiment
-*there* first (but remove hooks/post-commit first).
+   Unless you really *really* know what you're doing, please do
+   **NOT** use ``svn import``.  Only use ``svn import`` if you're
+   **absolutely sure you know what you're doing**.  Even then, first
+   grab a copy of the `nightly repository tarball`_, set it up on your
+   own machine, remove ``hooks/post-commit``, and experiment *there*.
+   It's quite easy to mess up the repository with an import.
 
-The `main source tree`_ ("trunk/docutils" directory) 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:
+.. _repository documentation: repository.html
 
-* 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
+Branches
+--------
 
-  Docutils currently supports Python 2.1 [#py21]_ or later, with some
-  things only working (and being tested) on Python 2.3+.  Therefore,
-  you should actually have Pythons 2.1 [#py21]_, 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.
+The "docutils" directory of the **trunk** (a.k.a. the **Docutils
+core**) is used for active -- but stable, fully tested, and reviewed
+-- development.
 
-  .. [#py21] 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.
+There will be at least one active **maintenance branch** at a time,
+based on at least the latest feature release.  For example, when
+Docutils 0.5 is released, its maintenance branch will take over, and
+the 0.4.x maintenance branch may be retired.  Maintenance branches
+will receive bug fixes only; no new features will be allowed here.
 
-  Good resources covering the differences between Python versions:
+Obvious and uncontroversial bug fixes *with tests* can be checked in
+directly to the core and to the maintenance branches.  Don't forget to
+add test cases!  Many (but not all) bug fixes will be applicable both
+to the core and to the maintenance branches; these should be applied
+to both.  No patches or dedicated branches are required for bug fixes,
+but they may be used.  It is up to the discretion of project
+developers to decide which mechanism to use for each case.
 
-  * `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`__
+Feature additions and API changes will be done in **feature
+branches**.  Feature branches will not be managed in any way.
+Frequent small checkins are encouraged here.  Feature branches must be
+discussed on the docutils-develop mailing list and reviewed before
+being merged into the core.
 
-  __ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html
-  __ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html
-  __ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html
-  __ http://www.python.org/peps/pep-0290.html
 
-* 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!
+Review Criteria
+```````````````
 
-* The `sandbox directory`_ is the place to put new, incomplete or
-  experimental code.  See `Additions to Docutils`_ and `The Sandbox`_
-  below.
+Before a new feature, an API change, or a complex, disruptive, or
+controversial bug fix can be checked in to the core or into a
+maintenance branch, it must undergo review.  These are the criteria:
 
-* 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.
+* The branch must be complete, and include full documentation and
+  tests.
 
-* For larger changes, use your best judgement.  If you're unsure of
-  the impact, or feel that you require advice or approval, branches,
-  patches, or `the sandbox`_ are the way to go.
+* There should ideally be one branch merge commit per feature or
+  change.  In other words, each branch merge should represent a
+  coherent change set.
 
-* You must be prepared to fix any code you have committed.
+* The code must be stable and uncontroversial.  Moving targets and
+  features under debate are not ready to be merged.
 
-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 Subversion is for.
+* The code must work.  The test suite must complete with no failures.
+  See `Docutils Testing`_.
 
-.. _main source tree:
-   http://svn.berlios.de/viewcvs/docutils/trunk/docutils/
-.. _Python Check-in Policies: http://www.python.org/dev/tools.html
-.. _sandbox directory:
-   http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
-.. _nightly repository tarball:
-   http://svn.berlios.de/svndumps/docutils-repos.gz
+The review process will ensure that at least one other set of eyeballs
+& brains sees the code before it enters the core.  In addition to the
+above, the general `Check-ins`_ policy (below) also applies.
 
+.. _Docutils Testing: testing.html
 
-Additions to Docutils
----------------------
 
-Additions to the project, such as new components, should be developed
-in the `sandbox 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.
+Check-ins
+---------
 
-* Why the sandbox?
+In general, the Docutils project follows the `Python Check-in
+Policies`_ as applicable.  There are some differences (e.g., we use
+Subversion now, not CVS), and we place particular emphasis as follows.
 
-  Developers should be able to try out new components while they're
-  being developed for addition to main source tree.  See `The
-  Sandbox`_ below.
+Changes or additions to the Docutils core and maintenance branches
+carry a commitment to the Docutils user community.  Developers must be
+prepared to fix and maintain any code they have committed.
 
-* _`Good shape` means that the component code is clean, readable, and
-  free of junk code (unused legacy code; by analogy with "junk DNA").
+The Docutils core (``trunk/docutils`` directory) and maintenance
+branches should always be kept in a stable state (usable and as
+problem-free as possible).  All changes to the Docutils core or
+maintenance branches must be in `good shape`_, usable_, documented_,
+tested_, and `reasonably complete`_.
+
+* _`Good shape` means that the code is clean, readable, and free of
+  junk code (unused legacy code; by analogy to "junk DNA").
 
 * _`Usable` means that the code does what it claims to do.  An "XYZ
-  Writer" should produce reasonable XYZ.
+  Writer" should produce reasonable XYZ output.
+
+* _`Documented`: The more complete the documentation the better.
+  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.
 
-* _`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.
+* _`Tested` means that unit and/or functional tests, that catch all
+  bugs fixed and/or cover all new functionality, have been added to
+  the test suite.  These tests must be checked by running the test
+  suite under all supported Python versions, and the entire test suite
+  must pass.  See `Docutils Testing`_.
 
 * _`Reasonably complete` means that the code must handle all input.
   Here "handle" means that no input can cause the code to fail (cause
@@ -293,67 +298,143 @@ Docutils user community.
   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.
+If you really want to check code directly into the Docutils core,
+you can, but you must ensure that it fulfills the above criteria
+first.  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 on a branch or in the sandbox
+first.  It's easy to move code over to the Docutils core once it's
+complete.
+
+It is the responsibility and obligation of all developers to keep the
+Docutils core and maintenance branches stable.  If a commit is made to
+the core or maintenance branch which breaks any test, the solution is
+simply to revert the change.  This is not vindictive; it's practical.
+We revert first, and discuss later.
+
+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.  We'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 Subversion is for!
 
 .. _Docutils Front-End Tools: ../user/tools.html
-.. _Docutils Configuration Files: ../user/config.html
+.. _Docutils Configuration Files: ../user/config.htm
+.. _Python Check-in Policies:
+   http://www.python.org/dev/tools.html#check-in-policies
+.. _nightly repository tarball:
+   http://svn.berlios.de/svndumps/docutils-repos.gz
+
+
+Version Numbering
+=================
+
+Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z;
+for example, 0.4.1).
+
+**Major releases** (x.0, e.g. 1.0) will be rare, and will represent
+major changes in API, functionality, or commitment.  For example, as
+long as the major version of Docutils is 0, it is to be considered
+*experimental code*.  When Docutils reaches version 1.0, the major
+APIs will be considered frozen and backward compatibility will become
+of paramount importance.
+
+Releases that change the minor number (x.y, e.g. 0.5) will be
+**feature releases**; new features from the `Docutils core`_ will be
+included.
+
+Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
+**bug-fix releases**.  No new features will be introduced in these
+releases; only bug fixes off of `maintenance branches`_ will be
+included.
+
+This policy was adopted in October 2005, and will take effect with
+Docutils version 0.4.  Prior to version 0.4, Docutils didn't have an
+official version numbering policy, and micro releases contained both
+bug fixes and new features.
+
+.. _Docutils core:
+   http://svn.berlios.de/viewcvs/docutils/trunk/docutils/
+.. _maintenance branches:
+   http://svn.berlios.de/viewcvs/docutils/branches/
+
+
+Snapshots
+=========
+
+Snapshot tarballs will be generated regularly from
+
+* the Docutils core, representing the current cutting-edge state of
+  development;
+
+* each active maintenance branch, for bug fixes;
+
+* each development branch, representing the unstable
+  seat-of-your-pants bleeding edge.
+
+The ``sandbox/infrastructure/docutils-update`` shell script, run as an
+hourly cron job on the BerliOS server, is responsible for
+automatically generating the snapshots and updating the web site.  See
+the `web site docs `__.
 
 
 Setting Up For Docutils Development
------------------------------------
+===================================
+
+When making changes to the code, testing is a must.  The code should
+be run to verify that it produces the expected results, and the entire
+test suite should be run 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 during development:
+
+1. Update your ``PYTHONPATH`` environment variable so that Python
+   picks up your local working copy of the code.  This is the
+   recommended method.
 
-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:
+   We'll assume that the Docutils trunk is checked out under your
+   ~/projects/ directory as follows::
 
-* Update your ``PYTHONPATH`` environment variable so that Python picks
-  up your local working copy of the code.  This is the recommended
-  method.
+       svn co svn+ssh://@svn.berlios.de/svnroot/repos/docutils/trunk \
+           docutils
 
-  For the bash shell and Docutils checked out from Subversion in
-  ``~/projects/docutils/``, add this to your ``~/.profile``::
+   For the bash shell, add this to your ``~/.profile``::
 
-      PYTHONPATH=$HOME/projects/docutils/docutils
-      PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
-      export PYTHONPATH
+       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``::
+   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
+       PATH=$PATH:$HOME/projects/docutils/docutils/tools
+       export PATH
 
-* Before you run anything, every time you make a change, reinstall
-  Docutils::
+2. Before you run anything, every time you make a change, reinstall
+   Docutils::
 
-      python setup.py install
+       python setup.py install
 
-  .. CAUTION::
+   .. CAUTION::
 
-     This method is **not** recommended for day-to-day development;
-     it's too easy to forget.  Confusion inevitably ensues.
+      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.
+      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 are recommended to subscribe to all `mailing lists`_.
+Developers are recommended to subscribe to all `Docutils mailing
+lists`_.
 
-.. _mailing lists: ../user/mailing-lists.html
+.. _Docutils mailing lists: ../user/mailing-lists.html
 
 
 The Wiki
@@ -371,11 +452,12 @@ The `sandbox directory`_ is a place to play around, to try out and
 share ideas.  It's a part of the Subversion repository but it isn't
 distributed as part of Docutils releases.  Feel free to check in code
 to the 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
+worry about it working 100% error-free, as is the goal of the Docutils
+core.  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.
+initial).  It's OK to make a mess in your personal space!  But please,
+play nice.
 
 Please update the `sandbox README`_ file with links and a brief
 description of your work.
@@ -385,11 +467,11 @@ out new, experimental components, the following sandbox directory
 structure is recommended::
 
     sandbox/
-        project_name/ # For a project where you invite contributions.
+        project_name/ # For a collaborative project.
                       # Structure as in userid/component_name below.
         userid/       # For personal space.
             component_name/ # A verbose name is best.
-                README.txt  # Please explain requirements,
+                README.txt  # Please explain the requirements,
                             # purpose/goals, and usage.
                 docs/
                     ...
@@ -413,6 +495,8 @@ 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
+.. _sandbox directory:
+   http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
 
 
 .. _parallel project:
diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 730e54e42..6c9e0f94a 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -12,7 +12,6 @@
 
 .. contents::
 
-
 Docutils uses a Subversion_ repository located at ``svn.berlios.de``.
 Subversion is exhaustively documented in the `Subversion Book`_
 (svnbook).
@@ -26,6 +25,11 @@ Subversion is exhaustively documented in the `Subversion Book`_
    (web site, snapshots, releases, mailing lists, trackers) is hosted
    at SourceForge.
 
+For the project policy on repository use (check-in requirements,
+branching, etc.), please see the `Docutils Project Policies`__.
+
+__ policies.html#subversion-repository
+
 
 Accessing the Repository
 ========================
@@ -74,20 +78,21 @@ their BerliOS user name to `Felix Wiemann `_.)
 __ https://developer.berlios.de/account/register.php
 
 If you are a developer, you get read-write access via
-``svn+ssh://username@svn.berlios.de/svnroot/repos/docutils/``, where
-``username`` is your BerliOS user name.  So to retrieve a working
-copy, type ::
+``svn+ssh://@svn.berlios.de/svnroot/repos/docutils/``, where
+```` is your BerliOS user account name.  So to retrieve a
+working copy, type ::
 
-    svn checkout svn+ssh://username@svn.berlios.de/svnroot/repos/docutils/trunk docutils
+    svn checkout svn+ssh://@svn.berlios.de/svnroot/repos/docutils/trunk \
+        docutils
 
 If you previously had an anonymous working copy and gained developer
 access, you can switch the URL associated with your working copy by
 typing ::
 
     svn switch --relocate svn://svn.berlios.de/docutils/trunk/docutils \
-        svn+ssh://username@svn.berlios.de/svnroot/repos/docutils
+        svn+ssh://@svn.berlios.de/svnroot/repos/docutils
 
-(``username`` is again your BerliOS user name.)
+(Again, ```` is your BerliOS user account name.)
 
 
 Setting Up Your Subversion Client For Development
@@ -142,7 +147,7 @@ your shell account.
 
   1. Log in to the BerliOS shell server::
 
-         ssh username@shell.berlios.de
+         ssh @shell.berlios.de
 
      You'll be asked for your password, which you set when you created
      your account.
@@ -157,7 +162,7 @@ your shell account.
 
   3. Copy your public key to the .ssh directory on BerliOS::
 
-         scp .ssh/id_dsa.pub username@shell.berlios.de:.ssh/authorized_keys
+         scp .ssh/id_dsa.pub @shell.berlios.de:.ssh/authorized_keys
 
   Now you should be able to start an SSH session without needing your
   password.
diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index fc6feae2b..6963f6541 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -3,6 +3,7 @@
 ===================
 
 :Author: Felix Wiemann
+:Author: David Goodger
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
@@ -11,8 +12,57 @@
 
 .. contents::
 
-This document describes how the tests are organized and how to add new
-tests or modify existing tests.
+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!
+
+This document describes how to run the Docutils test suite, how the
+tests are organized and how to add new tests or modify existing tests.
+
+
+Running the Test Suite
+======================
+
+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
+
+
+Python Versions
+===============
+
+The Docutils 0.4 release supports Python 2.1 [#py21]_ or later, with
+some features only working (and being tested) with Python 2.3+.
+Therefore, you should actually have Pythons 2.1 [#py21]_, 2.2, 2.3, as
+well as the latest Python 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 or more Python versions, the
+edge cases (2.1 and 2.3) should cover most of it.
+
+.. [#py21] 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.5/whatsnew/whatsnew23.html
+__ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html
+__ http://www.python.org/peps/pep-0290.html
+
+.. _Python Check-in Policies: http://www.python.org/dev/tools.html
+.. _sandbox directory:
+   http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
+.. _nightly repository tarball:
+   http://svn.berlios.de/svndumps/docutils-repos.gz
 
 
 Unit Tests
-- 
cgit v1.2.1


From 5eaa35732246484d010b80d2848eba8cd77158d8 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 28 Oct 2005 16:12:56 +0000
Subject: added the "container" element & directive, a generic container

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3963 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/doctree.txt         | 22 ++++++++++++++--------
 docs/ref/docutils.dtd        |  5 ++++-
 docs/ref/rst/directives.txt  | 38 +++++++++++++++++++++++++++++++++-----
 docs/user/rst/cheatsheet.txt |  1 +
 4 files changed, 52 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt
index caffc3a89..25e5f9594 100644
--- a/docs/ref/doctree.txt
+++ b/docs/ref/doctree.txt
@@ -146,12 +146,12 @@ body elements.  There are two subcategories of body elements: simple
 and compound.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, comment_, compound_, danger_, definition_list_,
-doctest_block_, enumerated_list_, error_, field_list_, figure_,
-footnote_, hint_, image_, important_, line_block_, literal_block_,
-note_, option_list_, paragraph_, pending_, raw_, rubric_,
-substitution_definition_, system_message_, table_, target_, tip_,
-warning_
+caution_, citation_, comment_, compound_, container_, danger_,
+definition_list_, doctest_block_, enumerated_list_, error_,
+field_list_, figure_, footnote_, hint_, image_, important_,
+line_block_, literal_block_, note_, option_list_, paragraph_,
+pending_, raw_, rubric_, substitution_definition_, system_message_,
+table_, target_, tip_, warning_
 
 
 Simple Body Elements
@@ -172,7 +172,7 @@ Compound body elements contain local substructure (body subelements)
 and further body elements.  They do not directly contain text data.
 
 Category members: admonition_, attention_, block_quote_, bullet_list_,
-caution_, citation_, compound_, danger_, definition_list_,
+caution_, citation_, compound_, container_, danger_, definition_list_,
 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
 important_, line_block, note_, option_list_, system_message_, table_,
 tip_, warning_
@@ -1036,6 +1036,12 @@ See docinfo_ for a more complete example, including processing
 context.
 
 
+``container``
+=============
+
+`To be completed`_.
+
+
 ``copyright``
 =============
 
@@ -4714,7 +4720,7 @@ Entity definition:
 
 .. parsed-literal::
 
-    paragraph_ | compound_ | literal_block_ | doctest_block_
+    paragraph_ | compound_ | container_ | literal_block_ | doctest_block_
     | line_block_ | block_quote_
     | table_ | figure_ | image_ | footnote_ | citation_ | rubric_
     | bullet_list_ | enumerated_list_ | definition_list_ | field_list_
diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd
index c2024391f..154566033 100644
--- a/docs/ref/docutils.dtd
+++ b/docs/ref/docutils.dtd
@@ -124,7 +124,7 @@ resolve to either an internal or external reference.
 
 
 
 
 
 
+
+
+
 
 `` element.  Do not use it only to group a
    sequence of elements, or you may get unexpected results.
 
-   If you happen to need a generic block-level container, please
-   describe your use-case in an email to the Docutils-users_ mailing
-   list.
-
-   .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
+   If you need a generic block-level container, please use the
+   container_ directive, described below.
 
 Compound paragraphs are typically rendered as multiple distinct text
 blocks, with the possibility of variations to emphasize their logical
@@ -645,6 +642,37 @@ The following option is recognized:
     class_ directive below.
 
 
+Container
+=========
+
+:Directive Type: "container"
+:Doctree Element: container
+:Directive Arguments: One or more, optional (class names).
+:Directive Options: None.
+:Directive Content: Interpreted as body elements.
+
+(New in Docutils 0.3.10)
+
+The "container" directive surrounds its contents (arbitrary body
+elements) with a generic block-level "container" element.  Combined
+with the optional "class_" attribute argument(s), this is an extension
+mechanism for users & applications.  For example::
+
+    .. container:: custom
+
+       This paragraph might be rendered in a custom way.
+
+Parsing the above results in the following pseudo-XML::
+
+    
+        
+            This paragraph might be rendered in a custom way.
+
+The "container" directive is the equivalent of HTML's ``
    ``
+element.  It may be used to group a sequence of elements for user- or
+application-specific purposes.
+
+
 --------
  Tables
 --------
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 2142d9ce0..3a2a488d1 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -86,6 +86,7 @@ epigraph          Block quote with class="epigraph"
 highlights        Block quote with class="highlights"
 pull-quote        Block quote with class="pull-quote"
 compound          Compound paragraphs [0.3.6]
+container         Generic block-level container element [0.3.10]
 table             Create a titled table [0.3.1]
 list-table        Create a table from a uniform two-level bullet list [0.3.8]
 csv-table         Create a table from CSV data (requires Python 2.3+) [0.3.4]
-- 
cgit v1.2.1


From 4250498dab37bd03b15cce64e310a3b9eba7233a Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 11:53:25 +0000
Subject: added missing target; typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3966 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt       | 2 ++
 docs/ref/rst/restructuredtext.txt | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index ec6dceb41..a2b016f57 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1273,6 +1273,8 @@ Raw Data Pass-Through
    describe your situation in an email to the Docutils-users_ mailing
    list.
 
+.. _Docutils-users: ../../user/mailing-lists.html#docutils-users
+
 The "raw" directive indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  The names of the output formats are
 given in the directive arguments.  The interpretation of the raw data
diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 3359d19a7..d503d9054 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2239,7 +2239,7 @@ constructs is recognized, leave the ".." on a line by itself::
     ..
        |even| this:: !
 
-A explicit markup start followed by a blank line and nothing else
+An explicit markup start followed by a blank line and nothing else
 (apart from whitespace) is an "empty comment".  It serves to terminate
 a preceding construct, and does **not** consume any indented text
 following.  To have a block quote follow a list or any indented
-- 
cgit v1.2.1


From e033ee28f912b3a7c0708c318daff3fd43d7859b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sat, 29 Oct 2005 12:21:09 +0000
Subject: another minor text fix

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3967 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index a2b016f57..0b2148267 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1270,7 +1270,7 @@ Raw Data Pass-Through
    If you often need to use the "raw" directive or a "raw"-derived
    interpreted text role, that is a sign either of overuse/abuse or
    that functionality may be missing from reStructuredText.  Please
-   describe your situation in an email to the Docutils-users_ mailing
+   describe your situation in a message to the Docutils-users_ mailing
    list.
 
 .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
-- 
cgit v1.2.1


From d92350b57c08a3f642a8a2e6147eb999769180f7 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 12:28:44 +0000
Subject: converted latin1 files to utf8; removed unnecessary -*- coding -*-
 tags; made some source files ASCII only

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3968 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt | 2 --
 1 file changed, 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index e4495512c..498a9fa34 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -1,5 +1,3 @@
-.. -*- coding: utf-8 -*-
-
 ===============================
  Docutils_ Distributor's Guide
 ===============================
-- 
cgit v1.2.1


From db725ada9c838f95536ce02e0d311ac0387180d3 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 14:39:45 +0000
Subject: fixed links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3974 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt         | 4 ++--
 docs/dev/rst/alternatives.txt | 2 +-
 docs/dev/rst/problems.txt     | 7 ++++---
 docs/peps/pep-0287.txt        | 2 +-
 docs/ref/rst/directives.txt   | 4 ++--
 docs/ref/rst/introduction.txt | 4 ++--
 6 files changed, 12 insertions(+), 11 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index e09f5ea67..2bc0158e8 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -30,7 +30,7 @@ his essay `The Magic Cauldron`_:
     through to contribute.
 
     .. _The Magic Cauldron:
-       http://www.tuxedo.org/~esr/writings/magic-cauldron/
+       http://www.catb.org/~esr/writings/magic-cauldron/
 
 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
@@ -319,7 +319,7 @@ just a trickle of perfect-as-they-stand changes.  The occasional
 mistake is easy to fix.  That's what Subversion is for!
 
 .. _Docutils Front-End Tools: ../user/tools.html
-.. _Docutils Configuration Files: ../user/config.htm
+.. _Docutils Configuration Files: ../user/config.html
 .. _Python Check-in Policies:
    http://www.python.org/dev/tools.html#check-in-policies
 .. _nightly repository tarball:
diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index e8730b650..d6e0957e7 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -32,7 +32,7 @@ The ideas are divided into sections:
 
 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
 .. _StructuredText:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
 .. _Problems with StructuredText: problems.html
 .. _reStructuredText Markup Specification:
    ../../ref/rst/restructuredtext.html
diff --git a/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt
index 01853c8bd..bc0101cbf 100644
--- a/docs/dev/rst/problems.txt
+++ b/docs/dev/rst/problems.txt
@@ -114,7 +114,8 @@ markup-significant characters as the characters themselves.  Currently
 there is no such mechanism (although ZWiki uses '!').  What are the
 candidates?
 
-1. ``!`` (http://dev.zope.org/Members/jim/StructuredTextWiki/NGEscaping)
+1. ``!``
+   (http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping)
 2. ``\``
 3. ``~``
 4. doubling of characters
@@ -847,14 +848,14 @@ text is separated from the link URI and the footnote, resulting in
 cleanly readable text.
 
 .. _StructuredText:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _detailed description:
    http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html
 .. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html
 .. _StructuredTextNG:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
 .. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/
    python/python/dist/src/README
 .. _Emacs table mode: http://table.sourceforge.net/
diff --git a/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt
index 18b3abfa7..689d6b919 100644
--- a/docs/peps/pep-0287.txt
+++ b/docs/peps/pep-0287.txt
@@ -764,7 +764,7 @@ __ http://www.python.org/doc/Humor.html#zen
 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
 
 .. _StructuredText:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
 
 .. _A ReStructuredText Primer:
    http://docutils.sourceforge.net/docs/user/rst/quickstart.html
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 0b2148267..58fa324cf 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -844,7 +844,7 @@ List Table
 (New in Docutils 0.3.8.  This is an initial implementation; `further
 ideas`__ may be implemented in the future.)
 
-__ http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables
+__ ../../dev/rst/alternatives.html#list-driven-tables
 
 The "list-table" directive is used to create a table from data in a
 uniform two-level bullet list.  "Uniform" means that each sublist
@@ -1512,7 +1512,7 @@ The text above is parsed and transformed into this doctree fragment::
     character must be a letter; no "unicode", "latin1", or "escape"
     characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern.
 
-    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
+    .. _HTML 4.01 spec: http://www.w3.org/TR/html401/
     .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
 
 
diff --git a/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt
index 2b64399a5..b7829816e 100644
--- a/docs/ref/rst/introduction.txt
+++ b/docs/ref/rst/introduction.txt
@@ -31,7 +31,7 @@ http://docutils.sourceforge.net/rst.html.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _StructuredText:
-    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
+    http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
 .. _Docutils: http://docutils.sourceforge.net/
 .. _A ReStructuredText Primer: ../../user/rst/quickstart.html
@@ -295,7 +295,7 @@ followed.
    http://structuredtext.sourceforge.net/
 .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
 .. _StructuredTextNG:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
 .. _project history file: ../../../HISTORY.html
 .. _PEP 287: ../../peps/pep-0287.html
 .. _Docstring Processing System framework: ../../peps/pep-0256.html
-- 
cgit v1.2.1


From 2d9be866bdfd38044a368345f77d93ef9907df9c Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 15:05:25 +0000
Subject: fixed links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3975 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-rfp.txt | 5 ++---
 docs/dev/todo.txt          | 2 +-
 2 files changed, 3 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-rfp.txt b/docs/dev/enthought-rfp.txt
index 86c932c70..5001a5600 100644
--- a/docs/dev/enthought-rfp.txt
+++ b/docs/dev/enthought-rfp.txt
@@ -49,9 +49,8 @@ Source Format
 
 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::
+   is available at http://www.enthought.com/traits/.  In the following
+   example, each trait definition is prefaced by a plain comment::
 
        __traits__ = {
 
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 11c8046ab..9513837b3 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -461,7 +461,7 @@ General
   (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
+  .. _traits: http://www.enthought.com/traits/
   .. _SciPy: http://www.scipy.org/
 
 * tools/buildhtml.py: Extend the --prune option ("prune" config
-- 
cgit v1.2.1


From ba18f6d97838e852cd174a21c0ba013cf3ee2d5a Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 15:56:28 +0000
Subject: removed coding guideline items which are contained in PEP 8;
 shortened warning about "svn import" -- it's not as dangerous as it used to
 be in CVS; removed reference to Python Check-in Policies because it's not of
 much use for us -- many items are not applicable and some even contradict
 what we're currently doing (e.g. bug/patch tracking)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3976 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 35 +++++------------------------------
 1 file changed, 5 insertions(+), 30 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 2bc0158e8..bc5ce93ac 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -29,8 +29,8 @@ his essay `The Magic Cauldron`_:
     correlated with the number of hoops each project makes a user go
     through to contribute.
 
-    .. _The Magic Cauldron:
-       http://www.catb.org/~esr/writings/magic-cauldron/
+.. _The Magic Cauldron:
+   http://www.catb.org/~esr/writings/magic-cauldron/
 
 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
@@ -63,9 +63,6 @@ Conventions`_ PEPs, with the following clarifications and extensions:
 
 * 4 spaces per indentation level.  No hard tabs.
 
-* Use only 7-bit 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 OK.).
@@ -75,14 +72,6 @@ Conventions`_ PEPs, with the following clarifications and extensions:
 * 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.
-
 * Avoid lambda expressions, which are inherently difficult to
   understand.  Named functions are preferable and superior: they're
   faster (no run-time compilation), and well-chosen names serve to
@@ -121,9 +110,6 @@ Documentation Conventions
        Document Subtitle (optional)
       ------------------------------
 
-      (The doc. subtitle adornment style can also be used for major
-      top-level sections.)
-
       Section
       =======
 
@@ -187,14 +173,9 @@ repository anonymously.  Only project developers can make changes.
 (If you would like to become a project developer, just ask!)  Also see
 `Setting Up For Docutils Development`_ below for some useful info.
 
-.. Caution::
-
-   Unless you really *really* know what you're doing, please do
-   **NOT** use ``svn import``.  Only use ``svn import`` if you're
-   **absolutely sure you know what you're doing**.  Even then, first
-   grab a copy of the `nightly repository tarball`_, set it up on your
-   own machine, remove ``hooks/post-commit``, and experiment *there*.
-   It's quite easy to mess up the repository with an import.
+Unless you really *really* know what you're doing, please do *not* use
+``svn import``.  It's quite easy to mess up the repository with an
+import.
 
 .. _repository documentation: repository.html
 
@@ -257,10 +238,6 @@ above, the general `Check-ins`_ policy (below) also applies.
 Check-ins
 ---------
 
-In general, the Docutils project follows the `Python Check-in
-Policies`_ as applicable.  There are some differences (e.g., we use
-Subversion now, not CVS), and we place particular emphasis as follows.
-
 Changes or additions to the Docutils core and maintenance branches
 carry a commitment to the Docutils user community.  Developers must be
 prepared to fix and maintain any code they have committed.
@@ -320,8 +297,6 @@ mistake is easy to fix.  That's what Subversion is for!
 
 .. _Docutils Front-End Tools: ../user/tools.html
 .. _Docutils Configuration Files: ../user/config.html
-.. _Python Check-in Policies:
-   http://www.python.org/dev/tools.html#check-in-policies
 .. _nightly repository tarball:
    http://svn.berlios.de/svndumps/docutils-repos.gz
 
-- 
cgit v1.2.1


From 049c0dd4035c4f6aae3b0491f159535539e1c032 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 29 Oct 2005 21:17:26 +0000
Subject: fixed more occurences of "an email"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3978 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt     |  2 +-
 docs/ref/rst/roles.txt      |  2 +-
 docs/user/mailing-lists.txt | 16 ++++++++--------
 3 files changed, 10 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 6c9e0f94a..95e54800a 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -72,7 +72,7 @@ Developer Access
 ----------------
 
 (Developers who had write-access for Docutils' CVS repository on
-SourceForge.net should `register at BerliOS`__ and send an email with
+SourceForge.net should `register at BerliOS`__ and send a message with
 their BerliOS user name to `Felix Wiemann `_.)
 
 __ https://developer.berlios.de/account/register.php
diff --git a/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt
index b396af2eb..3b8b114bc 100644
--- a/docs/ref/rst/roles.txt
+++ b/docs/ref/rst/roles.txt
@@ -279,7 +279,7 @@ must be used to obtain a ``title_reference`` element.
    If you often need to use "raw"-derived interpreted text roles or
    the "raw" directive, that is a sign either of overuse/abuse or that
    functionality may be missing from reStructuredText.  Please
-   describe your situation in an email to the Docutils-users_ mailing
+   describe your situation in a message to the Docutils-users_ mailing
    list.
 
    .. _Docutils-users: ../../user/mailing-lists.html#docutils-user
diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
index de4aff3de..828b19510 100644
--- a/docs/user/mailing-lists.txt
+++ b/docs/user/mailing-lists.txt
@@ -41,16 +41,16 @@ mailing lists; use the one you feel most comfortable with.
   __ nntp://news.gmane.org/gmane.text.docutils.user.
 
 **If you do not wish to subscribe,** you can also just send an email
-to Docutils-users@lists.sourceforge.net.  Please note in your email
-that you are not subscribed (to make sure that you receive copies
-[CCs] of any replies).
+message to Docutils-users@lists.sourceforge.net.  Please note in your
+message that you are not subscribed (to make sure that you receive
+copies [CCs] of any replies).
 
 The first time you post a message without being subscribed (also when
-posting via Gmane), you will receive an email with the subject "Your
-message to Docutils-users awaits moderator approval"; this is done to
-prevent spam to the mailing lists.  Your message will usually be
-approved within a few hours.  To avoid duplicates, please do not
-resend your message using a different email address.
+posting via Gmane), you will receive an automatic response with the
+subject "Your message to Docutils-users awaits moderator approval";
+this is done to prevent spam to the mailing lists.  Your message will
+usually be approved within a few hours.  To avoid duplicates, please
+do not resend your message using a different email address.
 
 
 Doc-SIG
-- 
cgit v1.2.1


From 4daab9f9ccb5c522de264c7352bbd40ee82c34ee Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 30 Oct 2005 14:23:25 +0000
Subject: again updated the link to traits

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3979 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/enthought-rfp.txt | 5 +++--
 docs/dev/todo.txt          | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/enthought-rfp.txt b/docs/dev/enthought-rfp.txt
index 5001a5600..986f5604f 100644
--- a/docs/dev/enthought-rfp.txt
+++ b/docs/dev/enthought-rfp.txt
@@ -49,8 +49,9 @@ Source Format
 
 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://www.enthought.com/traits/.  In the following
-   example, each trait definition is prefaced by a plain comment::
+   is available at http://code.enthought.com/traits/.  In the
+   following example, each trait definition is prefaced by a plain
+   comment::
 
        __traits__ = {
 
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 9513837b3..ccda16513 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -461,7 +461,7 @@ General
   (Had I known about traits when I was implementing docutils.frontend,
   I may have used them instead of rolling my own.)
 
-  .. _traits: http://www.enthought.com/traits/
+  .. _traits: http://code.enthought.com/traits/
   .. _SciPy: http://www.scipy.org/
 
 * tools/buildhtml.py: Extend the --prune option ("prune" config
-- 
cgit v1.2.1


From d54a138b591aaf47c7fa64c51473926fe0c449b9 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 30 Oct 2005 14:32:45 +0000
Subject: added note about whitelisting

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3980 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/mailing-lists.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
index 828b19510..8137e29e7 100644
--- a/docs/user/mailing-lists.txt
+++ b/docs/user/mailing-lists.txt
@@ -50,7 +50,10 @@ posting via Gmane), you will receive an automatic response with the
 subject "Your message to Docutils-users awaits moderator approval";
 this is done to prevent spam to the mailing lists.  Your message will
 usually be approved within a few hours.  To avoid duplicates, please
-do not resend your message using a different email address.
+do not resend your message using a different email address.  After
+your first message has been approved, your email address will be added
+to the whitelist and future messages will be posted to the mailing
+list without moderation.
 
 
 Doc-SIG
-- 
cgit v1.2.1


From 323d842b2d1803c0e27fa029745dc9f1eeb6e214 Mon Sep 17 00:00:00 2001
From: blais 
Date: Sun, 30 Oct 2005 15:13:46 +0000
Subject: I have cleaned up all the emacs support code for restructured text.
 If you are using it, this will most certainly affect you, here are the list
 of changes:

1. I moved the contents of restructuredtext.el, rst-mode.el and
   rst-html.el into a single file, named rst.el, and removed the old
   files.  You can remove the old files from your load-path and
   replace them with rst.el, the old files are to be considered
   OBSOLETE from now (2005-10-30).  All new contents will go to
   rst.el.

2. All the rest-* function names from restructuredtext.el have been
   RENAMED to rst-* (to be consistent with the code that was in
   rst-mode.el).  Almost all the contents of rst.el now start with
   rst-.

3. rst-text-mode-hook has been renamed to rst-text-mode-bindings.
   Because it is not a hook, but rather a function to be bound to a
   hook.  This was confusing and is now following the general emacs
   conventions.  This will affect you if you were enabling the
   adjusting and toc functions.

4. I removed the rst-html-stylesheet and the simpler rst-html-compile
   function.  It was replaced by the implementation of
   rst-html-html-comple-with-conf, which is more generic, and which
   now also uses the rst-html-options.

In addition, I wrote a document that describes how to use all the
features included in rst.el, because many emacs users I meet are not
aware of them.  You will be able to find it under
docs/user/emacs.txt.  I linked to it from the index page.



git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3981 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt      |   4 +
 docs/user/emacs.txt | 475 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 479 insertions(+)
 create mode 100644 docs/user/emacs.txt

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index ab77b94a2..69cceb717 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -95,6 +95,10 @@ Docutils-general:
   demonstration of most reStructuredText features; you can also have a
   look at the `text source `__)
 
+Editor support:
+
+* `Emacs support for reStructuredText `_
+
 
 .. _ref:
 
diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
new file mode 100644
index 000000000..347ee6b19
--- /dev/null
+++ b/docs/user/emacs.txt
@@ -0,0 +1,475 @@
+========================================
+   Emacs Support for reStructuredText
+========================================
+
+:Author: Martin Blais 
+:Date: 2005-10-29
+:Abstract:
+
+    High-level description of the existing emacs support for editing
+    reStructuredText text documents.  Suggested setup code and usage
+    instructions are provided.
+
+.. contents::
+..
+    1   Introduction
+    2   Basic Setup
+    3   Section Decoration Adjustment
+      3.1  Promoting and Demoting Many Sections
+      3.2  Customizations
+    4   Viewing the Hierarchy of Section Decorations
+    5   Table of Contents
+      5.1  Inserting a Table of Contents
+      5.2  Maintaining the Table of Contents Up-to-date
+    6   Navigating Between the Section Titles
+    7   Shifting Bulleted List Levels
+    8   Major Mode for Editing reStructuredText Documents
+    9   Converting Documents from Emacs
+    10  Other / External Useful Emacs Settings
+      10.1  Settings for Filling Bulleted Lists
+      10.2  ``text-mode`` Settings
+      10.3  Editing Tables: Emacs table mode
+      10.4  Character Processing
+    11  Credits
+    12  Obsolete Files
+    13  Future Work
+
+
+Introduction
+============
+
+reStructuredText_ is a series of conventions that allows a toolset--docutils--to
+extract generic document structure from simple text files.  For people who use
+Emacs_, there is a package that adds some support for the conventions that
+reStructuredText_ specifies: ``rst.el``.
+
+This document describes the most important features that it provides, how to
+setup your emacs to use them and how to invoke them.
+
+
+Basic Setup
+===========
+
+The emacs support is completely provided by the ``rst.el`` emacs package.  In
+order to use these features, you need to put the file in your emacs load-path,
+and to load it with::
+
+  (require 'rst)  ;; or (load "rst")
+
+Additional configuration variables can be customized and can be found by
+browsing the source code for ``rst.el``.
+
+Then you will want to bind keys to the most common commands it provides.  A
+standard text-mode hook function is maintained and provided by the package for
+this use, set it up like this::
+
+  (add-hook 'text-mode-hook 'rst-text-mode-hook)
+
+
+Section Decoration Adjustment
+=============================
+
+The rst package does not completely parse all the reStructuredText_ constructs,
+but it contains the ability to recognize the section decorations and to build
+the hierarchy of the document.  What we call section decorations or adornments
+are the underlines or under- and overlines used to mark a section title.
+
+There is a function that helps a great deal to maintain these decorations:
+``rst-adjust`` (bound on ``C-=`` by default).  This function is a swiss knife
+that can be invoked repeatedly and whose behaviour depends on context:
+
+#. If there is an incomplete underline, e.g.::
+
+      My Section Title
+      ^^
+
+   Invocation will complete the section title.  You can simply enter a few
+   characters of the title and invoke the function to complete it.  It can also
+   be used to adjust the length of the existing decoration when you need to edit
+   the title.
+
+#. If there is no section decoration, a decoration one level under the last
+   encountered section level is added;
+
+#. If there is already a section decoration, it is promoted to the next level.
+   You can invoke it like this repeatedly to cycle the title through the
+   hierarchy of existing decorations.
+
+Invoking the function with a negative prefix argument, e.g. ``C-- C-=``, will
+effectively reverse the direction of decoration cycling.  To alternate between
+underline-only and over-and-under styles, you can use a regular prefix argument,
+e.g. ``C-u C-=``.  See the documentation of ``rst-adjust`` for more description
+of the prefix arguments to alter the behaviour of the function.
+
+
+Promoting and Demoting Many Sections
+------------------------------------
+
+When you are re-organizing the structure of a document, it can be useful to
+change the level of a number of section titles.  The same key binding can be
+used to do that:  if the region is active when the binding is invoked, all the
+section titles that are within the region are promoted accordingly (or demoted,
+with negative prefix arg).
+
+
+Customizations
+--------------
+
+You can set the variable ``rst-preferred-decorations`` to a list of the
+decorations that you like to use for documents.  Everyone has their preference.
+``rst-default-indent`` can be set to the number of characters preferred for the
+over-and-under decoration style.
+
+
+Viewing the Hierarchy of Section Decorations
+============================================
+
+You can visualize the hierarchy of the section decorations in the current buffer
+by invoking ``rst-display-decorations-hierarchy``, bound on ``C-u C-x C-=``.  A
+temporary buffer will appear with fake section titles rendered in the style of
+the current document.  This can be useful when editing other people's documents
+to find out which section decorations correspond to which levels.
+
+
+Table of Contents
+=================
+
+When you are editing long documents, it can be a bit difficult to orient
+yourself in the structure of your text.  To that effect, a function is provided
+that quickly parses the document and presents a hierarchically indented table of
+contents of the document in a temporary buffer, in which you can navigate and
+press ``Ret`` to go to a specific section.
+
+Invoke this function (``rst-toc``) with ``C-x C-=``.  It should present a
+temporary buffer that looks somewhat like this::
+
+  Table of Contents: 
+  Debugging Meta-Techniques
+    Introduction
+    Debugging Solution Patterns
+      Recognize That a Bug Exists
+      Subdivide and Isolate
+      Identify and Verify Assumptions
+      Use a Tool for Introspection
+      Change one thing at a time
+      Learn about the System
+    Understanding a bug
+    The Basic Steps in Debugging
+    Attitude
+      Bad Feelings
+      Good Feelings
+    References
+
+
+When you select a section title, the temporary buffer disappears and you are
+left with the cursor positioned at the chosen section.
+
+
+Inserting a Table of Contents
+-----------------------------
+
+Oftentimes in long text documents that are meant to be read directly, a Table of
+Contents is inserted at the beginning of the text.  This is the case for most
+internet FAQs, for example.  In reStructuredText_ documents, since the table of
+contents is automatically generated by the parser with the ``.. contents::``
+directive, people generally have not been adding a text table of contents to
+their source documents, and partly because it is too much trouble to edit and
+maintain.
+
+The emacs support for reStructuredText_ provides a function to insert such a
+table of contents in your document.  Since it gets computed automatically by
+docutils, you should place such a table of contents within a contents, so that
+it gets ignored by docutils, e.g.  this is the favoured usage::
+
+  .. contents::
+  .. 
+      1  Introduction
+      2  Debugging Solution Patterns
+        2.1  Recognize That a Bug Exists
+        2.2  Subdivide and Isolate
+        2.3  Identify and Verify Assumptions
+        2.4  Use a Tool for Introspection
+        2.5  Change one thing at a time
+        2.6  Learn about the System
+      3  Understanding a bug
+      4  The Basic Steps in Debugging
+      5  Attitude
+        5.1  Bad Feelings
+        5.2  Good Feelings
+      6  References
+
+Just place the cursor at the top-left corner where you want to insert the TOC
+and invoke the function with ``C-x +``.  If there is a single top-level section
+level (i.e. the document title), by default it is ignored.  If you have deep
+nesting of sections, you can use a numeric prefix argument to limit the depth of
+rendenring of the TOC.
+
+You can also customize the look of the TOC by setting the values of the
+following variables:: ``rst-toc-indent``,
+``rst-toc-insert-always-include-top``, ``rst-toc-insert-style``,
+``rst-toc-insert-max-level``.
+
+
+Maintaining the Table of Contents Up-to-date
+--------------------------------------------
+
+One issue is that you will probably want to maintain the inserted table of
+contents up-to-date.  There is a function that will automatically look for the
+inserted TOC (``rst-toc-insert-update``) and it can be added to a hook on the
+section decoration adjustment function, so that everytime you adjust a section
+title, the TOC is updated. Add this functionality with the following emacs
+configuration::
+
+  (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
+
+
+Navigating Between the Section Titles
+=====================================
+
+You can move the cursor between the different sections by using the
+``rst-backward-section`` and ``rst-forward-section`` functions, by default bound
+to the ``C-M-{`` and ``C-M-}`` keys.
+
+
+Shifting Bulleted List Levels
+=============================
+
+Due to the nature of reStructuredText_, bulleted lists are always indented by
+two characters (unless they are part of a blockquote), e.g. ::
+
+   - Fruits
+
+     - Bananas
+     - Apples
+     - Oranges
+
+   - Veggies
+
+     - Zucchini
+     - Chick Peas
+
+To this effect, when re-organizing bulleted lists, it can be useful to shift
+regions of text by indents of two characters.  You can use the ``C-c C-r`` and
+``C-c C-l`` to shift the current region.  These bindings are similar to the ones
+provided by python-mode for editing python code and behave similarly.
+
+
+Major Mode for Editing reStructuredText Documents
+=================================================
+
+There is a major mode available for editing and syntax highlighting
+reStructuredText_ constructs.  This mode was written by Stefan Merten [#].  It
+mostly provides lazy syntax coloring for many of the constructs that
+reStructuredText_ prescribes.
+
+To enable this mode, type ``M-x rst-mode`` or you can setup an
+``auto-mode-alist`` to automatically turn it on whenever you visit
+reStructuredText_ documents::
+
+   (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
+
+If have local variables enabled (see ``enable-local-variables`` in the Emacs
+manual), you can also add the following at the top of your documents to trigger
+rst-mode::
+
+   .. -*- mode: rst -*-
+
+By default, the font-lock colouring is performed lazily.  If you don't like
+this, you can turn this off by setting the value of ``rst-mode-lazy``.  You can
+also change the various colours (see the source file for the whole list of
+customizable faces).
+
+.. [#]  This mode used to be provided by the file ``rst-mode.el`` and has now
+        been integrated with the rest of the emacs code.
+
+
+Converting Documents from Emacs
+===============================
+
+At the moment there is minimal support for calling ``rst2html.py`` from within
+Emacs.  You can add a key binding like this to invoke it::
+
+  (local-set-key [(control c)(?9)] 'rst-html-compile)
+
+This function basically creates a compilation command with the correct HTML
+output name for the current buffer and then invokes Emacs' compile function.  It
+also looks for the presence of a ``docutils.conf`` configuration file in the
+parent directories and adds it to the cmdline options.  You can customize which
+tool is used to perform the conversion and some standard options to always be
+added as well.
+
+.. note:: 
+
+   In general it is preferred to use a Makefile to automate the conversion of
+   many documents or a hierarchy of documents.  The functionality presented
+   above is meant to be convenient for use on single files.
+
+
+Other / External Useful Emacs Settings
+======================================
+
+This section covers general emacs text-mode settings that are useful in the
+context of reStructuredText_ conventions.  These are not provided by ``rst.el``
+but you may find them useful specifically for reStructuredText_ documents.
+
+
+Settings for Filling Bulleted Lists
+-----------------------------------
+
+One problem with the default text-mode settings is that *filling* long lines in
+bulleted lists that do not have an empty line between them merges them together,
+e.g.::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
+     - Oranges;
+
+Becomes::
+
+     - Bananas; One Apple a day keeps the doctor away, and
+     - eating more keeps the pirates at bay; Oranges;
+
+This is usually not what you want. What you want is this::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more
+       keeps the pirates at bay;
+     - Oranges;
+
+The problem is that emacs does not recognize the various consecutive items as
+forming paragraph boundaries.  You can fix this easily by changing the global
+value of the parapraph boundary detection to recognize such lists, like this::
+
+   (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-*] "))
+
+
+``text-mode`` Settings
+----------------------
+
+Consult the Emacs manual for more text-mode customizations.  In particular, you
+may be interested in setting the following variables, functions and modes that
+pertain somewhat to text-mode:
+
+- indent-tabs-mode
+- colon-double-space
+- auto-fill-mode
+- auto-mode-alist
+- fill-region
+
+
+Editing Tables: Emacs table mode
+--------------------------------
+
+You may want to check out `Emacs table mode`_ to create an edit tables, it
+allows creating ascii tables compatible with reStructuredText_.
+
+.. _Emacs table mode: http://table.sourceforge.net/
+
+
+
+Character Processing
+--------------------
+
+Since reStructuredText punts on the issue of character processing,
+here are some useful resources for Emacs users in the Unicode world:
+
+* `xmlunicode.el and unichars.el from Norman Walsh
+  `__
+
+* `An essay by Tim Bray, with example code
+  `__
+
+* For Emacs users on Mac OS X, here are some useful useful additions
+  to your .emacs file.
+
+  - To get direct keyboard input of non-ASCII characters (like
+    "option-e e" resulting in "é" [eacute]), first enable the option
+    key by setting the command key as your meta key::
+
+        (setq mac-command-key-is-meta t) ;; nil for option key
+
+    Next, use one of these lines::
+
+        (set-keyboard-coding-system 'mac-roman)
+        (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
+
+    I prefer the first line, because it enables non-Latin-1 characters
+    as well (em-dash, curly quotes, etc.).
+
+  - To enable the display of all characters in the Mac-Roman charset,
+    first create a fontset listing the fonts to use for each range of
+    characters using charsets that Emacs understands::
+
+      (create-fontset-from-fontset-spec
+       "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
+        ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
+
+    Latin-1 doesn't cover characters like em-dash and curly quotes, so
+    "mule-unicode-0100-24ff" is needed.
+
+    Next, use that fontset::
+
+        (set-frame-font "fontset-monaco")
+
+  - To enable cooperation between the system clipboard and the Emacs
+    kill ring, add this line::
+
+        (set-clipboard-coding-system 'mac-roman)
+
+  Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
+  FAQ `__.
+
+No matter what platform (or editor) you're using, I recommend the
+ProFont__ programmer's font.  It's monospaced, small but readable,
+similar characters are visually distinctive (like "I1l|", "0O", "ao",
+and ".,:;"), and free.
+
+__ http://www.tobias-jung.de/seekingprofont/
+
+
+
+
+Credits
+=======
+
+- The automatic section adjustment and table of contents features were written
+  by Martin Blais;
+- ``rst-mode`` and its syntax highlighting was implemented by Stefan Merten;
+- Various other functions were implemented by David Goodger.
+
+
+Obsolete Files
+==============
+
+On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and ``rst-mode.el`` were
+merged to form the new ``rst.el``.  You can consider the old files obsolete and
+remove them.
+
+
+Future Work
+===========
+
+Here are some features and ideas that will be worked on in the future, in those
+frenzy morning of excitement over the virtues of the one-true-way kitchen sink
+of editors:
+
+- It would be nice to differentiate between text files using reStructuredText_
+  and other general text files.  If we had a function to automatically guess
+  whether a .txt file is following the reStructuredText_ conventions, we could
+  trigger rst-mode without having to hardcode this on every text file, nor
+  forcing the user to add a local mode variable at the top of the file.  
+
+  We could perform this guessing by searching for a valid decoration at the top
+  of the document or searching for reStructuredText_ directives further on.
+
+- We would like to support local table of contents insertion.
+
+- The suggested decorations when adjusting should not have to cycle below one
+  below the last section decoration level preceding the cursor.  We need to fix
+  that.
+
+
+.. _Emacs: http://www.gnu.org/emacs FIXME check
+.. _reStructuredText: http://docutils.sf.net/rst.html
-- 
cgit v1.2.1


From 8e600dc640cf4db4919a452816bd20e336621d6b Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 30 Oct 2005 21:49:33 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3984 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 347ee6b19..b0ff38ee0 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -63,7 +63,7 @@ Then you will want to bind keys to the most common commands it provides.  A
 standard text-mode hook function is maintained and provided by the package for
 this use, set it up like this::
 
-  (add-hook 'text-mode-hook 'rst-text-mode-hook)
+  (add-hook 'text-mode-hook 'rst-text-mode-bindings)
 
 
 Section Decoration Adjustment
-- 
cgit v1.2.1


From f43d60fa3d795ad3e2f7c7986cb76e2e450905cc Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 30 Oct 2005 22:08:45 +0000
Subject: added some file types

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3987 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 95e54800a..568e3c6c9 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -115,8 +115,12 @@ correct properties set::
     *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision
     *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision
     *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.patch = svn:eol-style=native
     *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
     *.png = svn:mime-type=image/png
+    *.jpg = svn:mime-type=image/jpeg
+    *.gif = svn:mime-type=image/gif
 
 
 Setting Up SSH Access
-- 
cgit v1.2.1


From c5d1c54efe5b99787489f44e9fc60c78cb465e50 Mon Sep 17 00:00:00 2001
From: blais 
Date: Sun, 30 Oct 2005 22:58:09 +0000
Subject: Changed rst-html-compile to be generic and support multiple toolsets.
  The group now starts with rst-compile and the function rst-compile replaces
 rst-html-compile.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3988 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index b0ff38ee0..ba21da05f 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -286,17 +286,21 @@ customizable faces).
 Converting Documents from Emacs
 ===============================
 
-At the moment there is minimal support for calling ``rst2html.py`` from within
-Emacs.  You can add a key binding like this to invoke it::
+At the moment there is minimal support for calling the conversion tools from
+within Emacs.  You can add a key binding like this to invoke it::
 
-  (local-set-key [(control c)(?9)] 'rst-html-compile)
+  (local-set-key [(control c)(?9)] 'rst-compile)
 
-This function basically creates a compilation command with the correct HTML
-output name for the current buffer and then invokes Emacs' compile function.  It
-also looks for the presence of a ``docutils.conf`` configuration file in the
-parent directories and adds it to the cmdline options.  You can customize which
-tool is used to perform the conversion and some standard options to always be
-added as well.
+This function basically creates a compilation command with the correct output
+name for the current buffer and then invokes Emacs' compile function.  It also
+looks for the presence of a ``docutils.conf`` configuration file in the parent
+directories and adds it to the cmdline options.  You can customize which tool is
+used to perform the conversion and some standard options to always be added as
+well.
+
+Invocation uses the toolset indicated by ``rst-compile-primary-toolset``
+(default is ``'html``).  Invocation with a prefix argument uses
+``rst-compile-secondary-toolset``.
 
 .. note:: 
 
-- 
cgit v1.2.1


From 034774dae47a063345a99ac6e91d8647720a9e9a Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 31 Oct 2005 03:22:45 +0000
Subject: minor edits for consistency, typos, links, etc.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3990 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 46 +++++++++++++++++++++++++---------------------
 1 file changed, 25 insertions(+), 21 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index ba21da05f..9c399af45 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -1,3 +1,5 @@
+.. -*- coding: utf-8 -*-
+
 ========================================
    Emacs Support for reStructuredText
 ========================================
@@ -75,8 +77,8 @@ the hierarchy of the document.  What we call section decorations or adornments
 are the underlines or under- and overlines used to mark a section title.
 
 There is a function that helps a great deal to maintain these decorations:
-``rst-adjust`` (bound on ``C-=`` by default).  This function is a swiss knife
-that can be invoked repeatedly and whose behaviour depends on context:
+``rst-adjust`` (bound on ``C-=`` by default).  This function is a Swiss army 
+knife that can be invoked repeatedly and whose behaviour depends on context:
 
 #. If there is an incomplete underline, e.g.::
 
@@ -117,8 +119,8 @@ Customizations
 
 You can set the variable ``rst-preferred-decorations`` to a list of the
 decorations that you like to use for documents.  Everyone has their preference.
-``rst-default-indent`` can be set to the number of characters preferred for the
-over-and-under decoration style.
+``rst-default-indent`` can be set to the number of indent spaces preferred for
+the over-and-under decoration style.
 
 
 Viewing the Hierarchy of Section Decorations
@@ -138,10 +140,10 @@ When you are editing long documents, it can be a bit difficult to orient
 yourself in the structure of your text.  To that effect, a function is provided
 that quickly parses the document and presents a hierarchically indented table of
 contents of the document in a temporary buffer, in which you can navigate and
-press ``Ret`` to go to a specific section.
+press ``Return`` to go to a specific section.
 
 Invoke this function (``rst-toc``) with ``C-x C-=``.  It should present a
-temporary buffer that looks somewhat like this::
+temporary buffer that looks something like this::
 
   Table of Contents: 
   Debugging Meta-Techniques
@@ -160,7 +162,6 @@ temporary buffer that looks somewhat like this::
       Good Feelings
     References
 
-
 When you select a section title, the temporary buffer disappears and you are
 left with the cursor positioned at the chosen section.
 
@@ -177,9 +178,9 @@ their source documents, and partly because it is too much trouble to edit and
 maintain.
 
 The emacs support for reStructuredText_ provides a function to insert such a
-table of contents in your document.  Since it gets computed automatically by
-docutils, you should place such a table of contents within a contents, so that
-it gets ignored by docutils, e.g.  this is the favoured usage::
+table of contents in your document.  Since it is not meant to be part of the
+document text, you should place such a table of contents within a comment, so
+that it is ignored by the parser.  This is the favoured usage::
 
   .. contents::
   .. 
@@ -202,7 +203,7 @@ Just place the cursor at the top-left corner where you want to insert the TOC
 and invoke the function with ``C-x +``.  If there is a single top-level section
 level (i.e. the document title), by default it is ignored.  If you have deep
 nesting of sections, you can use a numeric prefix argument to limit the depth of
-rendenring of the TOC.
+rendering of the TOC.
 
 You can also customize the look of the TOC by setting the values of the
 following variables:: ``rst-toc-indent``,
@@ -216,7 +217,7 @@ Maintaining the Table of Contents Up-to-date
 One issue is that you will probably want to maintain the inserted table of
 contents up-to-date.  There is a function that will automatically look for the
 inserted TOC (``rst-toc-insert-update``) and it can be added to a hook on the
-section decoration adjustment function, so that everytime you adjust a section
+section decoration adjustment function, so that every time you adjust a section
 title, the TOC is updated. Add this functionality with the following emacs
 configuration::
 
@@ -262,7 +263,7 @@ reStructuredText_ constructs.  This mode was written by Stefan Merten [#].  It
 mostly provides lazy syntax coloring for many of the constructs that
 reStructuredText_ prescribes.
 
-To enable this mode, type ``M-x rst-mode`` or you can setup an
+To enable this mode, type ``M-x rst-mode`` or you can set up an
 ``auto-mode-alist`` to automatically turn it on whenever you visit
 reStructuredText_ documents::
 
@@ -274,6 +275,12 @@ rst-mode::
 
    .. -*- mode: rst -*-
 
+Or add this at the end of your documents:
+
+   ..
+      Local Variables:
+      mode: rst
+
 By default, the font-lock colouring is performed lazily.  If you don't like
 this, you can turn this off by setting the value of ``rst-mode-lazy``.  You can
 also change the various colours (see the source file for the whole list of
@@ -344,7 +351,7 @@ The problem is that emacs does not recognize the various consecutive items as
 forming paragraph boundaries.  You can fix this easily by changing the global
 value of the parapraph boundary detection to recognize such lists, like this::
 
-   (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-*] "))
+   (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-+*] "))
 
 
 ``text-mode`` Settings
@@ -370,7 +377,6 @@ allows creating ascii tables compatible with reStructuredText_.
 .. _Emacs table mode: http://table.sourceforge.net/
 
 
-
 Character Processing
 --------------------
 
@@ -387,7 +393,7 @@ here are some useful resources for Emacs users in the Unicode world:
   to your .emacs file.
 
   - To get direct keyboard input of non-ASCII characters (like
-    "option-e e" resulting in "é" [eacute]), first enable the option
+    "option-e e" resulting in "é" [eacute]), first enable the option
     key by setting the command key as your meta key::
 
         (setq mac-command-key-is-meta t) ;; nil for option key
@@ -433,8 +439,6 @@ and ".,:;"), and free.
 __ http://www.tobias-jung.de/seekingprofont/
 
 
-
-
 Credits
 =======
 
@@ -456,13 +460,13 @@ Future Work
 ===========
 
 Here are some features and ideas that will be worked on in the future, in those
-frenzy morning of excitement over the virtues of the one-true-way kitchen sink
-of editors:
+frenzied mornings of excitement over the virtues of the one-true-way kitchen
+sink of editors:
 
 - It would be nice to differentiate between text files using reStructuredText_
   and other general text files.  If we had a function to automatically guess
   whether a .txt file is following the reStructuredText_ conventions, we could
-  trigger rst-mode without having to hardcode this on every text file, nor
+  trigger rst-mode without having to hard-code this in every text file, nor
   forcing the user to add a local mode variable at the top of the file.  
 
   We could perform this guessing by searching for a valid decoration at the top
-- 
cgit v1.2.1


From b72350577e014df33d3d3fe8bab07720cbbeb859 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 1 Nov 2005 01:54:46 +0000
Subject: dynamic date

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3991 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 9c399af45..3d771f6dd 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -5,7 +5,7 @@
 ========================================
 
 :Author: Martin Blais 
-:Date: 2005-10-29
+:Date: $Date$
 :Abstract:
 
     High-level description of the existing emacs support for editing
-- 
cgit v1.2.1


From 4ff2ec740b6b5ade27810801beebbfc1d87f010d Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 1 Nov 2005 01:55:32 +0000
Subject: restored some deleted parts from r3976, & updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3992 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index bc5ce93ac..0b3fd757e 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -29,9 +29,6 @@ his essay `The Magic Cauldron`_:
     correlated with the number of hoops each project makes a user go
     through to contribute.
 
-.. _The Magic Cauldron:
-   http://www.catb.org/~esr/writings/magic-cauldron/
-
 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";
@@ -47,6 +44,9 @@ originators of Ogg Vorbis) put it well when he said:
 .. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion
    project `__.
 
+.. _The Magic Cauldron:
+   http://www.catb.org/~esr/writings/magic-cauldron/
+
 
 Python Coding Conventions
 =========================
@@ -59,10 +59,13 @@ 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 and extensions:
+Conventions`_ PEPs, summarized, clarified, and extended as follows:
 
 * 4 spaces per indentation level.  No hard tabs.
 
+* Use only 7-bit 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 OK.).
@@ -72,6 +75,14 @@ Conventions`_ PEPs, with the following clarifications and extensions:
 * 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.
+
 * Avoid lambda expressions, which are inherently difficult to
   understand.  Named functions are preferable and superior: they're
   faster (no run-time compilation), and well-chosen names serve to
@@ -106,9 +117,9 @@ Documentation Conventions
        Document Title
       ================
 
-      ------------------------------
-       Document Subtitle (optional)
-      ------------------------------
+      --------------------------------------------
+       Document Subtitle, or Major Division Title
+      --------------------------------------------
 
       Section
       =======
@@ -183,6 +194,8 @@ import.
 Branches
 --------
 
+(These branch policies go into effect with Docutils 0.4.)
+
 The "docutils" directory of the **trunk** (a.k.a. the **Docutils
 core**) is used for active -- but stable, fully tested, and reviewed
 -- development.
@@ -258,7 +271,8 @@ tested_, and `reasonably complete`_.
   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.
+  should be modified with any settings/options defined.  For any
+  non-trivial change, the `HISTORY.txt`_ file should be updated.
 
 * _`Tested` means that unit and/or functional tests, that catch all
   bugs fixed and/or cover all new functionality, have been added to
-- 
cgit v1.2.1


From c4da374a0e2c4a5d6f455382f6a05348596681d3 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 1 Nov 2005 14:09:07 +0000
Subject: added missing target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3993 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 0b3fd757e..3bf3914d0 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -272,7 +272,7 @@ tested_, and `reasonably complete`_.
   `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.  For any
-  non-trivial change, the `HISTORY.txt`_ file should be updated.
+  non-trivial change, the HISTORY.txt_ file should be updated.
 
 * _`Tested` means that unit and/or functional tests, that catch all
   bugs fixed and/or cover all new functionality, have been added to
@@ -311,8 +311,7 @@ mistake is easy to fix.  That's what Subversion is for!
 
 .. _Docutils Front-End Tools: ../user/tools.html
 .. _Docutils Configuration Files: ../user/config.html
-.. _nightly repository tarball:
-   http://svn.berlios.de/svndumps/docutils-repos.gz
+.. _HISTORY.txt: ../../HISTORY.txt
 
 
 Version Numbering
-- 
cgit v1.2.1


From a5566f410d97bd17a755c2bee5ffbdd2bbe72deb Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 2 Nov 2005 01:55:30 +0000
Subject: completed example local variables stanza, and added a real one

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3995 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 3d771f6dd..80c47c2d4 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -280,6 +280,7 @@ Or add this at the end of your documents:
    ..
       Local Variables:
       mode: rst
+      End:
 
 By default, the font-lock colouring is performed lazily.  If you don't like
 this, you can turn this off by setting the value of ``rst-mode-lazy``.  You can
@@ -481,3 +482,12 @@ sink of editors:
 
 .. _Emacs: http://www.gnu.org/emacs FIXME check
 .. _reStructuredText: http://docutils.sf.net/rst.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
-- 
cgit v1.2.1


From 01e516e6af7eb77d8123e3abc51d435183d199e2 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 2 Nov 2005 02:35:04 +0000
Subject: fixed markup

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3996 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 80c47c2d4..93475f3e5 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -275,7 +275,7 @@ rst-mode::
 
    .. -*- mode: rst -*-
 
-Or add this at the end of your documents:
+Or add this at the end of your documents::
 
    ..
       Local Variables:
-- 
cgit v1.2.1


From 9cb76ea8dfc48a41b2a45e04d13ffa9b9d370f6d Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 3 Nov 2005 23:16:02 +0000
Subject: fixed links

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3998 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/substitutions.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt
index 882239086..5ea9562f2 100644
--- a/docs/ref/rst/substitutions.txt
+++ b/docs/ref/rst/substitutions.txt
@@ -106,9 +106,9 @@ isopub.txt_          Publishing
 isotech.txt_         General Technical
 mmlalias.txt_        MathML aliases for entities from other sets
 mmlextra.txt_ [1]_   Extra names added by MathML
-xhtml4-lat1.txt_     XHTML Latin 1
-xhtml4-special.txt_  XHTML Special Characters
-xhtml4-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
+xhtml1-lat1.txt_     XHTML Latin 1
+xhtml1-special.txt_  XHTML Special Characters
+xhtml1-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
 ===================  =================================================
 
 .. [1] There are ``*-wide.txt`` variants for each of these character
@@ -148,9 +148,9 @@ reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
 .. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
 .. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
 .. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
-.. _xhtml4-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml4-lat1.txt
-.. _xhtml4-special.txt: ../../../docutils/parsers/rst/include/xhtml4-special.txt
-.. _xhtml4-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml4-symbol.txt
+.. _xhtml1-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
+.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
+.. _xhtml1-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
 
 
 ..
-- 
cgit v1.2.1


From 7efb57643bcde8d50755fa4c971fc630e2330ef8 Mon Sep 17 00:00:00 2001
From: blais 
Date: Fri, 4 Nov 2005 19:18:35 +0000
Subject: Fixed link in emacs file.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3999 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 93475f3e5..64daf07ac 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -480,7 +480,7 @@ sink of editors:
   that.
 
 
-.. _Emacs: http://www.gnu.org/emacs FIXME check
+.. _Emacs: http://www.gnu.org/software/emacs/emacs.html
 .. _reStructuredText: http://docutils.sf.net/rst.html
 
 
-- 
cgit v1.2.1


From 3fd593f2ae8eac1f19b55a5cc02e786058866f80 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 6 Nov 2005 16:17:56 +0000
Subject: added a link to Alberto's OpenDocument writer

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4000 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index d2127d3dc..4cc8df8cf 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -33,6 +33,8 @@ the box.
 
 * For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
 
+* Alberto Berti is developing an `OpenDocument writer`_.
+
 * xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
   dumps of the document tree (e.g. created with rst2xml.py) back to
   reStructuredText.
@@ -108,6 +110,7 @@ code base.
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _OpenDocument writer: http://article.gmane.org/gmane.text.docutils.devel/3388
 .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
 .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
 .. _ht2html: http://ht2html.sourceforge.net/
-- 
cgit v1.2.1


From 7ed7500d9d9bbf4285b8646ed79d77aaf9872ea7 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 6 Nov 2005 16:23:21 +0000
Subject: link to full thread

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4001 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/links.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/links.txt b/docs/user/links.txt
index 4cc8df8cf..75c0fae0e 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -110,7 +110,7 @@ code base.
 .. _Docutils: http://docutils.sourceforge.net/
 .. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 .. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
-.. _OpenDocument writer: http://article.gmane.org/gmane.text.docutils.devel/3388
+.. _OpenDocument writer: http://thread.gmane.org/gmane.text.docutils.devel/3388
 .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
 .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
 .. _ht2html: http://ht2html.sourceforge.net/
-- 
cgit v1.2.1


From 3bf78b13e2d2829a4aa33f5e0c875f4206dded9f Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 6 Nov 2005 16:50:19 +0000
Subject: added note about HTTP access to the repository

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4002 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/repository.txt | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/repository.txt b/docs/dev/repository.txt
index 568e3c6c9..2c613b10e 100644
--- a/docs/dev/repository.txt
+++ b/docs/dev/repository.txt
@@ -57,10 +57,14 @@ To check out everything (main tree, sandboxes, and web site), type ::
 This will create a working copy of the whole trunk in a new directory
 called ``docutils``.
 
-Note that you should *never* check out
-``svn://svn.berlios.de/docutils`` (without "trunk"), because then
-you'd end up fetching the whole Docutils tree for every branch and tag
-over and over again, wasting your and BerliOS's bandwidth.
+If you cannot use the ``svn`` port, you can also use the HTTP access
+method by substituting "http://svn.berlios.de/svnroot/repos" for
+"svn://svn.berlios.de".
+
+Note that you should *not* check out ``svn://svn.berlios.de/docutils``
+(without "trunk"), because then you'd end up fetching the whole
+Docutils tree for every branch and tag over and over again, wasting
+your and BerliOS's bandwidth.
 
 To update your working copy later on, cd into the working copy and
 type ::
@@ -94,6 +98,10 @@ typing ::
 
 (Again, ```` is your BerliOS user account name.)
 
+If you cannot use the ``ssh`` port, you can also use the HTTPS access
+method by substituting "https://svn.berlios.de" for
+"svn+ssh://svn.berlios.de".
+
 
 Setting Up Your Subversion Client For Development
 `````````````````````````````````````````````````
-- 
cgit v1.2.1


From 6f185bf33fee23aab3ba57a78eeeaeb69867e400 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sun, 6 Nov 2005 19:18:54 +0000
Subject: added possible inline node in raw-wrap role output

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4003 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index ccda16513..f4e9948a6 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1437,12 +1437,15 @@ any knowledge of the Python-Reader origin of these elements.
                     
                 
                     {\color{red}
-                text
+                
+                    text
                 
                     
                 
                     }
 
+    Possibly without the intermediate "inline" node.
+
   - "acronym" and "abbreviation": Associate the full text with a short
     form.  Jason Diamond's description:
 
-- 
cgit v1.2.1


From 747b9ac9bdb4d54a7eacca166ad3865c89bf93e7 Mon Sep 17 00:00:00 2001
From: blais 
Date: Mon, 7 Nov 2005 14:35:10 +0000
Subject: - Changed the default bindings due to the explosion of new   feature:
 we now have a prefix-map, which is bound to 'C-c p',   so the 'C-x p XXXX'
 commands are all for the rst.el file   functions.  I left a few bindings:

  * C-= is still there, because it is the single most useful
    command and it should be invoked with one key (you can get to
    it with 'C-c p a' too).

  * I moved 'C-M-{' to 'C-c n' or 'C-c p n' and did the same for
    the forward movement commands.

  * 'C-c C-l' and 'C-c C-r' have been kept, since they have a
    similar role than those bindings have in progmodes.

- I removed all the bindings from 'C-x ...' prefix map, since we
  should be using the mode-specific map, which is 'C-c ...'.  I'm
  also now using the mode-prefix-map variable, so people who have
  rebound theirs will get the benefits of their customization.

- Started defining some abbrevs, e.g. 'con' for ''.. contents::'

- Changed a lot of 'if's to 'when' and 'unless' clauses.

- I added a function to find the node within the section subtree
  where the cursor lives. This function is used to compute the
  desired location of point in the toc table, which fixes a bug
  with the cursor being off when there were missing nodes.

- The toc insertion now uses the insertion point to determine
  where to start rendering the TOC.  This fixes a problem with
  guessing the titles and subtitles and heuristically removing
  them, simplifies the rst-toc-insert function and this new
  choices automatically supports local tocs.

- Fixed the shifting functions to use markers, so that they can
  be used repeatedly with my repeat-repeatable-command advice.
  This just makes the functions more robust.

- Added an option to automatically fill on shifting a region left
  or right (this needs more work).




git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4004 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 41 +++++++++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 16 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 64daf07ac..219e8e250 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -67,6 +67,9 @@ this use, set it up like this::
 
   (add-hook 'text-mode-hook 'rst-text-mode-bindings)
 
+A prefix map is defined for all the ``rst.el`` commands.  By default,
+it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``.
+
 
 Section Decoration Adjustment
 =============================
@@ -76,9 +79,10 @@ but it contains the ability to recognize the section decorations and to build
 the hierarchy of the document.  What we call section decorations or adornments
 are the underlines or under- and overlines used to mark a section title.
 
-There is a function that helps a great deal to maintain these decorations:
-``rst-adjust`` (bound on ``C-=`` by default).  This function is a Swiss army 
-knife that can be invoked repeatedly and whose behaviour depends on context:
+There is a function that helps a great deal to maintain these
+decorations:  ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
+``C-=`` by default).  This function is a Swiss army knife that can be
+invoked repeatedly and whose behaviour depends on context:
 
 #. If there is an incomplete underline, e.g.::
 
@@ -127,7 +131,7 @@ Viewing the Hierarchy of Section Decorations
 ============================================
 
 You can visualize the hierarchy of the section decorations in the current buffer
-by invoking ``rst-display-decorations-hierarchy``, bound on ``C-u C-x C-=``.  A
+by invoking ``rst-display-decorations-hierarchy``, bound on ``C-c p h``.  A
 temporary buffer will appear with fake section titles rendered in the style of
 the current document.  This can be useful when editing other people's documents
 to find out which section decorations correspond to which levels.
@@ -142,7 +146,7 @@ that quickly parses the document and presents a hierarchically indented table of
 contents of the document in a temporary buffer, in which you can navigate and
 press ``Return`` to go to a specific section.
 
-Invoke this function (``rst-toc``) with ``C-x C-=``.  It should present a
+Invoke this function (``rst-toc``) with ``C-c p t``.  It should present a
 temporary buffer that looks something like this::
 
   Table of Contents: 
@@ -199,16 +203,18 @@ that it is ignored by the parser.  This is the favoured usage::
         5.2  Good Feelings
       6  References
 
-Just place the cursor at the top-left corner where you want to insert the TOC
-and invoke the function with ``C-x +``.  If there is a single top-level section
-level (i.e. the document title), by default it is ignored.  If you have deep
-nesting of sections, you can use a numeric prefix argument to limit the depth of
-rendering of the TOC.
+Just place the cursor at the top-left corner where you want to insert
+the TOC and invoke the function with ``C-c p i``.  The table of
+contents will display all the section titles that are under the
+location where the insertion occurs.  This way you can insert local
+table of contents by placing them in the appropriate location.
+
+If you have deep nesting of sections, you can use a numeric prefix
+argument to limit the depth of rendering of the TOC.
 
-You can also customize the look of the TOC by setting the values of the
-following variables:: ``rst-toc-indent``,
-``rst-toc-insert-always-include-top``, ``rst-toc-insert-style``,
-``rst-toc-insert-max-level``.
+You can also customize the look of the TOC by setting the values of
+the following variables:: ``rst-toc-indent``,
+``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
 
 
 Maintaining the Table of Contents Up-to-date
@@ -223,13 +229,16 @@ configuration::
 
   (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
 
+You can invoke the update on the current buffer with ``C-c p u``.
+
 
 Navigating Between the Section Titles
 =====================================
 
 You can move the cursor between the different sections by using the
-``rst-backward-section`` and ``rst-forward-section`` functions, by default bound
-to the ``C-M-{`` and ``C-M-}`` keys.
+``rst-backward-section`` and ``rst-forward-section`` functions, by
+default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c
+C-p`` and ``C-c C-n``).
 
 
 Shifting Bulleted List Levels
-- 
cgit v1.2.1


From faea343429656d64f59c3a63f5de700fbdd73449 Mon Sep 17 00:00:00 2001
From: blais 
Date: Tue, 8 Nov 2005 16:49:03 +0000
Subject: Removed obsolete comment in emacs description.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4015 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 --
 1 file changed, 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 219e8e250..20edbb6fa 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -482,8 +482,6 @@ sink of editors:
   We could perform this guessing by searching for a valid decoration at the top
   of the document or searching for reStructuredText_ directives further on.
 
-- We would like to support local table of contents insertion.
-
 - The suggested decorations when adjusting should not have to cycle below one
   below the last section decoration level preceding the cursor.  We need to fix
   that.
-- 
cgit v1.2.1


From 8e3232334aa306645df2d8cfbd24a166c6971d76 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 8 Nov 2005 19:30:03 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4016 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 20edbb6fa..971b61638 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -268,7 +268,7 @@ Major Mode for Editing reStructuredText Documents
 =================================================
 
 There is a major mode available for editing and syntax highlighting
-reStructuredText_ constructs.  This mode was written by Stefan Merten [#].  It
+reStructuredText_ constructs.  This mode was written by Stefan Merten [#]_.  It
 mostly provides lazy syntax coloring for many of the constructs that
 reStructuredText_ prescribes.
 
-- 
cgit v1.2.1


From 8394b9a6ca28be76427354ccc492bc79697b0c34 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 8 Nov 2005 19:34:43 +0000
Subject: refilled at column 70

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4017 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 299 +++++++++++++++++++++++++++-------------------------
 1 file changed, 158 insertions(+), 141 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 971b61638..119bf2b41 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -40,30 +40,31 @@
 Introduction
 ============
 
-reStructuredText_ is a series of conventions that allows a toolset--docutils--to
-extract generic document structure from simple text files.  For people who use
-Emacs_, there is a package that adds some support for the conventions that
-reStructuredText_ specifies: ``rst.el``.
+reStructuredText_ is a series of conventions that allows a
+toolset--docutils--to extract generic document structure from simple
+text files.  For people who use Emacs_, there is a package that adds
+some support for the conventions that reStructuredText_ specifies:
+``rst.el``.
 
-This document describes the most important features that it provides, how to
-setup your emacs to use them and how to invoke them.
+This document describes the most important features that it provides,
+how to setup your emacs to use them and how to invoke them.
 
 
 Basic Setup
 ===========
 
-The emacs support is completely provided by the ``rst.el`` emacs package.  In
-order to use these features, you need to put the file in your emacs load-path,
-and to load it with::
+The emacs support is completely provided by the ``rst.el`` emacs
+package.  In order to use these features, you need to put the file in
+your emacs load-path, and to load it with::
 
   (require 'rst)  ;; or (load "rst")
 
-Additional configuration variables can be customized and can be found by
-browsing the source code for ``rst.el``.
+Additional configuration variables can be customized and can be found
+by browsing the source code for ``rst.el``.
 
-Then you will want to bind keys to the most common commands it provides.  A
-standard text-mode hook function is maintained and provided by the package for
-this use, set it up like this::
+Then you will want to bind keys to the most common commands it
+provides.  A standard text-mode hook function is maintained and
+provided by the package for this use, set it up like this::
 
   (add-hook 'text-mode-hook 'rst-text-mode-bindings)
 
@@ -74,13 +75,14 @@ it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``.
 Section Decoration Adjustment
 =============================
 
-The rst package does not completely parse all the reStructuredText_ constructs,
-but it contains the ability to recognize the section decorations and to build
-the hierarchy of the document.  What we call section decorations or adornments
-are the underlines or under- and overlines used to mark a section title.
+The rst package does not completely parse all the reStructuredText_
+constructs, but it contains the ability to recognize the section
+decorations and to build the hierarchy of the document.  What we call
+section decorations or adornments are the underlines or under- and
+overlines used to mark a section title.
 
 There is a function that helps a great deal to maintain these
-decorations:  ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
+decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
 ``C-=`` by default).  This function is a Swiss army knife that can be
 invoked repeatedly and whose behaviour depends on context:
 
@@ -89,65 +91,68 @@ invoked repeatedly and whose behaviour depends on context:
       My Section Title
       ^^
 
-   Invocation will complete the section title.  You can simply enter a few
-   characters of the title and invoke the function to complete it.  It can also
-   be used to adjust the length of the existing decoration when you need to edit
-   the title.
+   Invocation will complete the section title.  You can simply enter a
+   few characters of the title and invoke the function to complete it.
+   It can also be used to adjust the length of the existing decoration
+   when you need to edit the title.
 
-#. If there is no section decoration, a decoration one level under the last
-   encountered section level is added;
+#. If there is no section decoration, a decoration one level under the
+   last encountered section level is added;
 
-#. If there is already a section decoration, it is promoted to the next level.
-   You can invoke it like this repeatedly to cycle the title through the
-   hierarchy of existing decorations.
+#. If there is already a section decoration, it is promoted to the
+   next level.  You can invoke it like this repeatedly to cycle the
+   title through the hierarchy of existing decorations.
 
-Invoking the function with a negative prefix argument, e.g. ``C-- C-=``, will
-effectively reverse the direction of decoration cycling.  To alternate between
-underline-only and over-and-under styles, you can use a regular prefix argument,
-e.g. ``C-u C-=``.  See the documentation of ``rst-adjust`` for more description
-of the prefix arguments to alter the behaviour of the function.
+Invoking the function with a negative prefix argument, e.g. ``C--
+C-=``, will effectively reverse the direction of decoration cycling.
+To alternate between underline-only and over-and-under styles, you can
+use a regular prefix argument, e.g. ``C-u C-=``.  See the
+documentation of ``rst-adjust`` for more description of the prefix
+arguments to alter the behaviour of the function.
 
 
 Promoting and Demoting Many Sections
 ------------------------------------
 
-When you are re-organizing the structure of a document, it can be useful to
-change the level of a number of section titles.  The same key binding can be
-used to do that:  if the region is active when the binding is invoked, all the
-section titles that are within the region are promoted accordingly (or demoted,
-with negative prefix arg).
+When you are re-organizing the structure of a document, it can be
+useful to change the level of a number of section titles.  The same
+key binding can be used to do that: if the region is active when the
+binding is invoked, all the section titles that are within the region
+are promoted accordingly (or demoted, with negative prefix arg).
 
 
 Customizations
 --------------
 
-You can set the variable ``rst-preferred-decorations`` to a list of the
-decorations that you like to use for documents.  Everyone has their preference.
-``rst-default-indent`` can be set to the number of indent spaces preferred for
-the over-and-under decoration style.
+You can set the variable ``rst-preferred-decorations`` to a list of
+the decorations that you like to use for documents.  Everyone has
+their preference.  ``rst-default-indent`` can be set to the number of
+indent spaces preferred for the over-and-under decoration style.
 
 
 Viewing the Hierarchy of Section Decorations
 ============================================
 
-You can visualize the hierarchy of the section decorations in the current buffer
-by invoking ``rst-display-decorations-hierarchy``, bound on ``C-c p h``.  A
-temporary buffer will appear with fake section titles rendered in the style of
-the current document.  This can be useful when editing other people's documents
-to find out which section decorations correspond to which levels.
+You can visualize the hierarchy of the section decorations in the
+current buffer by invoking ``rst-display-decorations-hierarchy``,
+bound on ``C-c p h``.  A temporary buffer will appear with fake
+section titles rendered in the style of the current document.  This
+can be useful when editing other people's documents to find out which
+section decorations correspond to which levels.
 
 
 Table of Contents
 =================
 
-When you are editing long documents, it can be a bit difficult to orient
-yourself in the structure of your text.  To that effect, a function is provided
-that quickly parses the document and presents a hierarchically indented table of
-contents of the document in a temporary buffer, in which you can navigate and
-press ``Return`` to go to a specific section.
+When you are editing long documents, it can be a bit difficult to
+orient yourself in the structure of your text.  To that effect, a
+function is provided that quickly parses the document and presents a
+hierarchically indented table of contents of the document in a
+temporary buffer, in which you can navigate and press ``Return`` to go
+to a specific section.
 
-Invoke this function (``rst-toc``) with ``C-c p t``.  It should present a
-temporary buffer that looks something like this::
+Invoke this function (``rst-toc``) with ``C-c p t``.  It should
+present a temporary buffer that looks something like this::
 
   Table of Contents: 
   Debugging Meta-Techniques
@@ -166,25 +171,26 @@ temporary buffer that looks something like this::
       Good Feelings
     References
 
-When you select a section title, the temporary buffer disappears and you are
-left with the cursor positioned at the chosen section.
+When you select a section title, the temporary buffer disappears and
+you are left with the cursor positioned at the chosen section.
 
 
 Inserting a Table of Contents
 -----------------------------
 
-Oftentimes in long text documents that are meant to be read directly, a Table of
-Contents is inserted at the beginning of the text.  This is the case for most
-internet FAQs, for example.  In reStructuredText_ documents, since the table of
-contents is automatically generated by the parser with the ``.. contents::``
-directive, people generally have not been adding a text table of contents to
-their source documents, and partly because it is too much trouble to edit and
-maintain.
+Oftentimes in long text documents that are meant to be read directly,
+a Table of Contents is inserted at the beginning of the text.  This is
+the case for most internet FAQs, for example.  In reStructuredText_
+documents, since the table of contents is automatically generated by
+the parser with the ``.. contents::`` directive, people generally have
+not been adding a text table of contents to their source documents,
+and partly because it is too much trouble to edit and maintain.
 
-The emacs support for reStructuredText_ provides a function to insert such a
-table of contents in your document.  Since it is not meant to be part of the
-document text, you should place such a table of contents within a comment, so
-that it is ignored by the parser.  This is the favoured usage::
+The emacs support for reStructuredText_ provides a function to insert
+such a table of contents in your document.  Since it is not meant to
+be part of the document text, you should place such a table of
+contents within a comment, so that it is ignored by the parser.  This
+is the favoured usage::
 
   .. contents::
   .. 
@@ -220,11 +226,12 @@ the following variables:: ``rst-toc-indent``,
 Maintaining the Table of Contents Up-to-date
 --------------------------------------------
 
-One issue is that you will probably want to maintain the inserted table of
-contents up-to-date.  There is a function that will automatically look for the
-inserted TOC (``rst-toc-insert-update``) and it can be added to a hook on the
-section decoration adjustment function, so that every time you adjust a section
-title, the TOC is updated. Add this functionality with the following emacs
+One issue is that you will probably want to maintain the inserted
+table of contents up-to-date.  There is a function that will
+automatically look for the inserted TOC (``rst-toc-insert-update``)
+and it can be added to a hook on the section decoration adjustment
+function, so that every time you adjust a section title, the TOC is
+updated. Add this functionality with the following emacs
 configuration::
 
   (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
@@ -244,8 +251,9 @@ C-p`` and ``C-c C-n``).
 Shifting Bulleted List Levels
 =============================
 
-Due to the nature of reStructuredText_, bulleted lists are always indented by
-two characters (unless they are part of a blockquote), e.g. ::
+Due to the nature of reStructuredText_, bulleted lists are always
+indented by two characters (unless they are part of a blockquote),
+e.g. ::
 
    - Fruits
 
@@ -258,19 +266,20 @@ two characters (unless they are part of a blockquote), e.g. ::
      - Zucchini
      - Chick Peas
 
-To this effect, when re-organizing bulleted lists, it can be useful to shift
-regions of text by indents of two characters.  You can use the ``C-c C-r`` and
-``C-c C-l`` to shift the current region.  These bindings are similar to the ones
-provided by python-mode for editing python code and behave similarly.
+To this effect, when re-organizing bulleted lists, it can be useful to
+shift regions of text by indents of two characters.  You can use the
+``C-c C-r`` and ``C-c C-l`` to shift the current region.  These
+bindings are similar to the ones provided by python-mode for editing
+python code and behave similarly.
 
 
 Major Mode for Editing reStructuredText Documents
 =================================================
 
 There is a major mode available for editing and syntax highlighting
-reStructuredText_ constructs.  This mode was written by Stefan Merten [#]_.  It
-mostly provides lazy syntax coloring for many of the constructs that
-reStructuredText_ prescribes.
+reStructuredText_ constructs.  This mode was written by Stefan Merten
+[#]_.  It mostly provides lazy syntax coloring for many of the
+constructs that reStructuredText_ prescribes.
 
 To enable this mode, type ``M-x rst-mode`` or you can set up an
 ``auto-mode-alist`` to automatically turn it on whenever you visit
@@ -278,9 +287,9 @@ reStructuredText_ documents::
 
    (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
 
-If have local variables enabled (see ``enable-local-variables`` in the Emacs
-manual), you can also add the following at the top of your documents to trigger
-rst-mode::
+If have local variables enabled (see ``enable-local-variables`` in the
+Emacs manual), you can also add the following at the top of your
+documents to trigger rst-mode::
 
    .. -*- mode: rst -*-
 
@@ -291,55 +300,58 @@ Or add this at the end of your documents::
       mode: rst
       End:
 
-By default, the font-lock colouring is performed lazily.  If you don't like
-this, you can turn this off by setting the value of ``rst-mode-lazy``.  You can
-also change the various colours (see the source file for the whole list of
-customizable faces).
+By default, the font-lock colouring is performed lazily.  If you don't
+like this, you can turn this off by setting the value of
+``rst-mode-lazy``.  You can also change the various colours (see the
+source file for the whole list of customizable faces).
 
-.. [#]  This mode used to be provided by the file ``rst-mode.el`` and has now
-        been integrated with the rest of the emacs code.
+.. [#] This mode used to be provided by the file ``rst-mode.el`` and
+   has now been integrated with the rest of the emacs code.
 
 
 Converting Documents from Emacs
 ===============================
 
-At the moment there is minimal support for calling the conversion tools from
-within Emacs.  You can add a key binding like this to invoke it::
+At the moment there is minimal support for calling the conversion
+tools from within Emacs.  You can add a key binding like this to
+invoke it::
 
   (local-set-key [(control c)(?9)] 'rst-compile)
 
-This function basically creates a compilation command with the correct output
-name for the current buffer and then invokes Emacs' compile function.  It also
-looks for the presence of a ``docutils.conf`` configuration file in the parent
-directories and adds it to the cmdline options.  You can customize which tool is
-used to perform the conversion and some standard options to always be added as
-well.
+This function basically creates a compilation command with the correct
+output name for the current buffer and then invokes Emacs' compile
+function.  It also looks for the presence of a ``docutils.conf``
+configuration file in the parent directories and adds it to the
+cmdline options.  You can customize which tool is used to perform the
+conversion and some standard options to always be added as well.
 
-Invocation uses the toolset indicated by ``rst-compile-primary-toolset``
-(default is ``'html``).  Invocation with a prefix argument uses
-``rst-compile-secondary-toolset``.
+Invocation uses the toolset indicated by
+``rst-compile-primary-toolset`` (default is ``'html``).  Invocation
+with a prefix argument uses ``rst-compile-secondary-toolset``.
 
 .. note:: 
 
-   In general it is preferred to use a Makefile to automate the conversion of
-   many documents or a hierarchy of documents.  The functionality presented
-   above is meant to be convenient for use on single files.
+   In general it is preferred to use a Makefile to automate the
+   conversion of many documents or a hierarchy of documents.  The
+   functionality presented above is meant to be convenient for use on
+   single files.
 
 
 Other / External Useful Emacs Settings
 ======================================
 
-This section covers general emacs text-mode settings that are useful in the
-context of reStructuredText_ conventions.  These are not provided by ``rst.el``
-but you may find them useful specifically for reStructuredText_ documents.
+This section covers general emacs text-mode settings that are useful
+in the context of reStructuredText_ conventions.  These are not
+provided by ``rst.el`` but you may find them useful specifically for
+reStructuredText_ documents.
 
 
 Settings for Filling Bulleted Lists
 -----------------------------------
 
-One problem with the default text-mode settings is that *filling* long lines in
-bulleted lists that do not have an empty line between them merges them together,
-e.g.::
+One problem with the default text-mode settings is that *filling* long
+lines in bulleted lists that do not have an empty line between them
+merges them together, e.g.::
 
      - Bananas;
      - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
@@ -347,19 +359,20 @@ e.g.::
 
 Becomes::
 
-     - Bananas; One Apple a day keeps the doctor away, and
-     - eating more keeps the pirates at bay; Oranges;
+     - Bananas; One Apple a day keeps the doctor away, and eating more
+     - keeps the pirates at bay; Oranges;
 
 This is usually not what you want. What you want is this::
 
      - Bananas;
-     - One Apple a day keeps the doctor away, and eating more
-       keeps the pirates at bay;
+     - One Apple a day keeps the doctor away, and eating more keeps
+       the pirates at bay;
      - Oranges;
 
-The problem is that emacs does not recognize the various consecutive items as
-forming paragraph boundaries.  You can fix this easily by changing the global
-value of the parapraph boundary detection to recognize such lists, like this::
+The problem is that emacs does not recognize the various consecutive
+items as forming paragraph boundaries.  You can fix this easily by
+changing the global value of the parapraph boundary detection to
+recognize such lists, like this::
 
    (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-+*] "))
 
@@ -367,9 +380,9 @@ value of the parapraph boundary detection to recognize such lists, like this::
 ``text-mode`` Settings
 ----------------------
 
-Consult the Emacs manual for more text-mode customizations.  In particular, you
-may be interested in setting the following variables, functions and modes that
-pertain somewhat to text-mode:
+Consult the Emacs manual for more text-mode customizations.  In
+particular, you may be interested in setting the following variables,
+functions and modes that pertain somewhat to text-mode:
 
 - indent-tabs-mode
 - colon-double-space
@@ -381,8 +394,9 @@ pertain somewhat to text-mode:
 Editing Tables: Emacs table mode
 --------------------------------
 
-You may want to check out `Emacs table mode`_ to create an edit tables, it
-allows creating ascii tables compatible with reStructuredText_.
+You may want to check out `Emacs table mode`_ to create an edit
+tables, it allows creating ascii tables compatible with
+reStructuredText_.
 
 .. _Emacs table mode: http://table.sourceforge.net/
 
@@ -452,39 +466,42 @@ __ http://www.tobias-jung.de/seekingprofont/
 Credits
 =======
 
-- The automatic section adjustment and table of contents features were written
-  by Martin Blais;
-- ``rst-mode`` and its syntax highlighting was implemented by Stefan Merten;
+- The automatic section adjustment and table of contents features were
+  written by Martin Blais;
+- ``rst-mode`` and its syntax highlighting was implemented by Stefan
+  Merten;
 - Various other functions were implemented by David Goodger.
 
 
 Obsolete Files
 ==============
 
-On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and ``rst-mode.el`` were
-merged to form the new ``rst.el``.  You can consider the old files obsolete and
-remove them.
+On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and
+``rst-mode.el`` were merged to form the new ``rst.el``.  You can
+consider the old files obsolete and remove them.
 
 
 Future Work
 ===========
 
-Here are some features and ideas that will be worked on in the future, in those
-frenzied mornings of excitement over the virtues of the one-true-way kitchen
-sink of editors:
+Here are some features and ideas that will be worked on in the future,
+in those frenzied mornings of excitement over the virtues of the
+one-true-way kitchen sink of editors:
 
-- It would be nice to differentiate between text files using reStructuredText_
-  and other general text files.  If we had a function to automatically guess
-  whether a .txt file is following the reStructuredText_ conventions, we could
-  trigger rst-mode without having to hard-code this in every text file, nor
-  forcing the user to add a local mode variable at the top of the file.  
+- It would be nice to differentiate between text files using
+  reStructuredText_ and other general text files.  If we had a
+  function to automatically guess whether a .txt file is following the
+  reStructuredText_ conventions, we could trigger rst-mode without
+  having to hard-code this in every text file, nor forcing the user to
+  add a local mode variable at the top of the file.
 
-  We could perform this guessing by searching for a valid decoration at the top
-  of the document or searching for reStructuredText_ directives further on.
+  We could perform this guessing by searching for a valid decoration
+  at the top of the document or searching for reStructuredText_
+  directives further on.
 
-- The suggested decorations when adjusting should not have to cycle below one
-  below the last section decoration level preceding the cursor.  We need to fix
-  that.
+- The suggested decorations when adjusting should not have to cycle
+  below one below the last section decoration level preceding the
+  cursor.  We need to fix that.
 
 
 .. _Emacs: http://www.gnu.org/software/emacs/emacs.html
-- 
cgit v1.2.1


From d02faf5adc38eec669a143d8a224c53d9c664b3d Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 8 Nov 2005 21:48:57 +0000
Subject: replaced "felixwiemann" with "fwiemann"

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4020 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/release.txt |  6 +++---
 docs/dev/website.txt | 12 ++++++------
 docs/user/links.txt  |  2 +-
 3 files changed, 10 insertions(+), 10 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/release.txt b/docs/dev/release.txt
index b242720d0..fa58bc46f 100644
--- a/docs/dev/release.txt
+++ b/docs/dev/release.txt
@@ -11,9 +11,9 @@
 
 
 (Steps in boldface text are *not* covered by the release script at
-sandbox/felixwiemann/release.sh.  "Not covered" means that you aren't
-even reminded of them.  Note: The release.sh script needs to be
-updated to reflect the recent move to Subversion!)
+sandbox/fwiemann/release.sh.  "Not covered" means that you aren't even
+reminded of them.  Note: The release.sh script needs to be updated to
+reflect the recent move to Subversion!)
 
 * **Announce a check-in freeze on Docutils-develop.  Post a list of
   major changes since the last release and ask for additions.**
diff --git a/docs/dev/website.txt b/docs/dev/website.txt
index 193e9c0f2..d374b1004 100644
--- a/docs/dev/website.txt
+++ b/docs/dev/website.txt
@@ -10,12 +10,12 @@
 
 The Docutils web site, , is
 maintained automatically by the ``docutils-update`` script, run as an
-hourly cron job on shell.berlios.de (by user "felixwiemann").  The
-script will process any .txt file which is newer than the
-corresponding .html file in the project's web directory on
-shell.berlios.de (``/home/groups/docutils/htdocs/aux/htdocs/``) and
-upload the changes to the web site at SourceForge.  For a new .txt
-file, just SSH to ``@shell.berlios.de`` and ::
+hourly cron job on shell.berlios.de (by user "fwiemann").  The script
+will process any .txt file which is newer than the corresponding .html
+file in the project's web directory on shell.berlios.de
+(``/home/groups/docutils/htdocs/aux/htdocs/``) and upload the changes
+to the web site at SourceForge.  For a new .txt file, just SSH to
+``@shell.berlios.de`` and ::
 
     cd /home/groups/docutils/htdocs/aux/htdocs/
     touch filename.html
diff --git a/docs/user/links.txt b/docs/user/links.txt
index 75c0fae0e..3bb2aaa70 100644
--- a/docs/user/links.txt
+++ b/docs/user/links.txt
@@ -115,7 +115,7 @@ code base.
 .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
 .. _ht2html: http://ht2html.sourceforge.net/
 .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
-.. _xhtml2rest: http://docutils.sf.net/sandbox/felixwiemann/xhtml2rest/
+.. _xhtml2rest: http://docutils.sf.net/sandbox/fwiemann/xhtml2rest/
 .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
 .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
 .. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
-- 
cgit v1.2.1


From c04b23630d974d9c6878e84348a0c5e23280f3aa Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 8 Nov 2005 21:51:31 +0000
Subject: partial revert -- the website cron job is still run by felixwiemann;
 sorry

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4021 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/website.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/website.txt b/docs/dev/website.txt
index d374b1004..193e9c0f2 100644
--- a/docs/dev/website.txt
+++ b/docs/dev/website.txt
@@ -10,12 +10,12 @@
 
 The Docutils web site, , is
 maintained automatically by the ``docutils-update`` script, run as an
-hourly cron job on shell.berlios.de (by user "fwiemann").  The script
-will process any .txt file which is newer than the corresponding .html
-file in the project's web directory on shell.berlios.de
-(``/home/groups/docutils/htdocs/aux/htdocs/``) and upload the changes
-to the web site at SourceForge.  For a new .txt file, just SSH to
-``@shell.berlios.de`` and ::
+hourly cron job on shell.berlios.de (by user "felixwiemann").  The
+script will process any .txt file which is newer than the
+corresponding .html file in the project's web directory on
+shell.berlios.de (``/home/groups/docutils/htdocs/aux/htdocs/``) and
+upload the changes to the web site at SourceForge.  For a new .txt
+file, just SSH to ``@shell.berlios.de`` and ::
 
     cd /home/groups/docutils/htdocs/aux/htdocs/
     touch filename.html
-- 
cgit v1.2.1


From d66e00e85902ec5667ba03392be74c625c4efeb3 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 8 Nov 2005 22:06:36 +0000
Subject: added to do list entry about redundancy in pep.css

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4022 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f4e9948a6..9ac05be2a 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1657,6 +1657,15 @@ HTML Writer
   identifying them as such.  Text in Docutils language module.
 
 
+PEP/HTML Writer
+===============
+
+* ``@import`` html4css1.css instead of duplicating it in ``pep.css``.
+
+  Problem: If the stylesheet is embedded, the reference to
+  html4css1.css will break.
+
+
 LaTeX writer
 ============
 
-- 
cgit v1.2.1


From ca0592c455966c669c7258a559fc8e032381d210 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 10 Nov 2005 04:38:48 +0000
Subject: added & modified some entries

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4024 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 9ac05be2a..b79224b6e 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -478,6 +478,17 @@ General
   Seems like a bad idea as long as it isn't independent from the ouput
   format (for example, navigation bars are only useful for web pages).
 
+* docutils_update: Check for a ``Makefile`` in a directory, and run
+  ``make`` if found?  This would allow for variant processing on
+  specific source files, such as running rst2s5.py instead of
+  rst2html.py.
+
+* Improve handing of RCS/CVS/SVN keywords, especially "Date".  Under
+  SVN, the "Date" keyword expands to a huge string: ``2005-11-08
+  00:22:00 -0500 (Tue, 08 Nov 2005)``.  This should be reduced to the
+  IS0 8601 standard ``2005-11-08``, or (perhaps optionally) some other
+  short form.
+
 
 Documentation
 =============
@@ -1660,11 +1671,16 @@ HTML Writer
 PEP/HTML Writer
 ===============
 
-* ``@import`` html4css1.css instead of duplicating it in ``pep.css``.
+* ``@import`` html4css1.css instead of duplicating it in ``pep.css``?
 
   Problem: If the stylesheet is embedded, the reference to
   html4css1.css will break.
 
+  Also, ``pep.css`` really has only one major customer: python.org.
+  The PEP stylesheet serves its purpose well for them.  They have no
+  use for modular, imported stylesheets, which would only increase
+  bandwidth and add complexity.
+
 
 LaTeX writer
 ============
@@ -1808,6 +1824,9 @@ Features & issues:
 * Directive to begin a new slide, continuation, using the same title
   as the previous slide?  (Unnecessary?)
 
+* Have a timeout on incremental items, so the colour goes away after 1
+  second.
+
 Here's an example that I was hoping to show at PyCon DC 2005::
 
     ========================
-- 
cgit v1.2.1


From 08e27cd7865ce0940b2f04e42dba24a38a491a7d Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 10 Nov 2005 18:16:31 +0000
Subject: added comments to to-do list entry about pep.css

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4041 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index b79224b6e..c23c90719 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1674,13 +1674,22 @@ PEP/HTML Writer
 * ``@import`` html4css1.css instead of duplicating it in ``pep.css``?
 
   Problem: If the stylesheet is embedded, the reference to
-  html4css1.css will break.
+  html4css1.css will break.  So it might be better to use a secondary
+  stylesheet for the PEP writer.  I.e., the PEP writer uses the HTML
+  writer's standard stylesheet *plus* the ``pep.css`` stylesheet.
+  (Driving this concept even further, we could allow for three
+  stylesheets [HTML writer, PEP writer, user] or any number of
+  stylesheets.  It's just a bit difficult to come up with a proper
+  option syntax for that.)
 
   Also, ``pep.css`` really has only one major customer: python.org.
   The PEP stylesheet serves its purpose well for them.  They have no
   use for modular, imported stylesheets, which would only increase
   bandwidth and add complexity.
 
+  On the other hand, we don't really want to maintain two stylesheets
+  in parallel.  The redundancy inevitably causes errors.
+
 
 LaTeX writer
 ============
-- 
cgit v1.2.1


From 2dd0fe3fe16bbad8951e92efee11e23601240e6a Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 11 Nov 2005 14:37:18 +0000
Subject: Fixed the DocInfo transform to handle SVN-style expansion of the
 "Date" keyword (this was actually a bug, not a to-do; the correct behavior
 was specified in the docs)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4042 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 6 ------
 1 file changed, 6 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index c23c90719..9e598f205 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -483,12 +483,6 @@ General
   specific source files, such as running rst2s5.py instead of
   rst2html.py.
 
-* Improve handing of RCS/CVS/SVN keywords, especially "Date".  Under
-  SVN, the "Date" keyword expands to a huge string: ``2005-11-08
-  00:22:00 -0500 (Tue, 08 Nov 2005)``.  This should be reduced to the
-  IS0 8601 standard ``2005-11-08``, or (perhaps optionally) some other
-  short form.
-
 
 Documentation
 =============
-- 
cgit v1.2.1


From c2ecc8e9779eb6f004a7e35fd5160669723cd813 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 14 Nov 2005 18:11:32 +0000
Subject: small addition

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4048 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/policies.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/policies.txt b/docs/dev/policies.txt
index 3bf3914d0..25fb4f2e9 100644
--- a/docs/dev/policies.txt
+++ b/docs/dev/policies.txt
@@ -415,6 +415,21 @@ ways to keep the Docutils code accessible during development:
       reinstall the "docutils" package, Python won't see your latest
       changes.
 
+A useful addition to the ``docutils`` top-level directory in branches
+and alternate copies of the code is a ``set-PATHS`` file
+containing the following lines::
+
+    # source this file
+    export PYTHONPATH=$PWD:$PWD/extras
+    export PATH=$PWD/tools:$PATH
+
+Open a shell for this branch, ``cd`` to the ``docutils`` top-level
+directory, and "source" this file.  For example, using the bash
+shell::
+
+    $ cd some-branch/docutils
+    $ . set-PATHS
+
 
 Mailing Lists
 =============
-- 
cgit v1.2.1


From 976c10fa68fc7259c79ba878f947be0db7f0a66e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Mon, 14 Nov 2005 18:53:41 +0000
Subject: added item about citation enhancements; marked item about branch
 policy as done

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4049 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 9e598f205..34e8fa7a1 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -47,7 +47,7 @@ the short term) to include:
 * [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck
   (no longer needed because of the above change).
 
-* Incorporate new branch policy into the docs.  [DavidG]
+* [DONE in rev. 3962] Incorporate new branch policy into the docs.
   ("Development strategy" thread on Docutils-develop)
 
 * Fix East-Asian `double-width characters`_ issue.  [DavidG]
@@ -680,6 +680,9 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* The citation syntax could use some enhancements.  See
+  .
+
 * The current list-recognition logic has too many false positives, as
   in ::
 
-- 
cgit v1.2.1


From 79508c7cfb55418cfd6c7030c99c42b3758dfa20 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 15 Nov 2005 23:59:26 +0000
Subject: minor edits & corrections

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4057 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index db38ac1ab..2f6fa40c8 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -324,9 +324,8 @@ _`output_encoding_error_handler`
     --output-encoding, -o``.
 
 _`record_dependencies`
-
-    Path to a file to which Docutils writes a list of files the input
-    file(s) depends on [#dependencies]_, e.g. due to file
+    Path to a file where Docutils will write a list of files that the
+    input and output depend on [#dependencies]_, e.g. due to file
     inclusion. [#pwd]_ The format is one filename per line.  This
     option is particularly useful in conjunction with programs like
     ``make``.
-- 
cgit v1.2.1


From 5fe7c5067c6c5a2512c4d8747292041247ed4035 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 17 Nov 2005 19:02:41 +0000
Subject: removed to-do list entry about redundancy in pep.css

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4061 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 23 -----------------------
 1 file changed, 23 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 34e8fa7a1..4db433631 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1665,29 +1665,6 @@ HTML Writer
   identifying them as such.  Text in Docutils language module.
 
 
-PEP/HTML Writer
-===============
-
-* ``@import`` html4css1.css instead of duplicating it in ``pep.css``?
-
-  Problem: If the stylesheet is embedded, the reference to
-  html4css1.css will break.  So it might be better to use a secondary
-  stylesheet for the PEP writer.  I.e., the PEP writer uses the HTML
-  writer's standard stylesheet *plus* the ``pep.css`` stylesheet.
-  (Driving this concept even further, we could allow for three
-  stylesheets [HTML writer, PEP writer, user] or any number of
-  stylesheets.  It's just a bit difficult to come up with a proper
-  option syntax for that.)
-
-  Also, ``pep.css`` really has only one major customer: python.org.
-  The PEP stylesheet serves its purpose well for them.  They have no
-  use for modular, imported stylesheets, which would only increase
-  bandwidth and add complexity.
-
-  On the other hand, we don't really want to maintain two stylesheets
-  in parallel.  The redundancy inevitably causes errors.
-
-
 LaTeX writer
 ============
 
-- 
cgit v1.2.1


From 36c37e0532a5e7c81d6104399c53d22525b40030 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 17 Nov 2005 19:48:52 +0000
Subject: documented default 'latex of rst-compile-secondary-toolset

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4063 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 119bf2b41..d5e0ad27b 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -327,7 +327,8 @@ conversion and some standard options to always be added as well.
 
 Invocation uses the toolset indicated by
 ``rst-compile-primary-toolset`` (default is ``'html``).  Invocation
-with a prefix argument uses ``rst-compile-secondary-toolset``.
+with a prefix argument uses ``rst-compile-secondary-toolset`` (default
+is ``'latex``).
 
 .. note:: 
 
-- 
cgit v1.2.1


From b775a81b52fedbb19c60f6b0aff673427eaa0c9e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 17 Nov 2005 22:57:02 +0000
Subject: added reference to older thread about citations

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4067 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 4db433631..387939224 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -681,7 +681,8 @@ Also see the `... Or Not To Do?`__ list.
 __ rst/alternatives.html#or-not-to-do
 
 * The citation syntax could use some enhancements.  See
-  .
+   and
+  .
 
 * The current list-recognition logic has too many false positives, as
   in ::
-- 
cgit v1.2.1


From 64c87695885a0fb6bbab4a6e3579396baa72d21e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 17 Nov 2005 23:24:52 +0000
Subject: use hook instead of direct setq

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4068 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 33 ++++++---------------------------
 1 file changed, 6 insertions(+), 27 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index d5e0ad27b..512c11fb2 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -13,28 +13,6 @@
     instructions are provided.
 
 .. contents::
-..
-    1   Introduction
-    2   Basic Setup
-    3   Section Decoration Adjustment
-      3.1  Promoting and Demoting Many Sections
-      3.2  Customizations
-    4   Viewing the Hierarchy of Section Decorations
-    5   Table of Contents
-      5.1  Inserting a Table of Contents
-      5.2  Maintaining the Table of Contents Up-to-date
-    6   Navigating Between the Section Titles
-    7   Shifting Bulleted List Levels
-    8   Major Mode for Editing reStructuredText Documents
-    9   Converting Documents from Emacs
-    10  Other / External Useful Emacs Settings
-      10.1  Settings for Filling Bulleted Lists
-      10.2  ``text-mode`` Settings
-      10.3  Editing Tables: Emacs table mode
-      10.4  Character Processing
-    11  Credits
-    12  Obsolete Files
-    13  Future Work
 
 
 Introduction
@@ -347,12 +325,12 @@ provided by ``rst.el`` but you may find them useful specifically for
 reStructuredText_ documents.
 
 
-Settings for Filling Bulleted Lists
------------------------------------
+Settings for Filling Lists
+--------------------------
 
 One problem with the default text-mode settings is that *filling* long
-lines in bulleted lists that do not have an empty line between them
-merges them together, e.g.::
+lines in bullet and enumeration lists that do not have an empty line
+between them merges them together, e.g.::
 
      - Bananas;
      - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
@@ -375,7 +353,8 @@ items as forming paragraph boundaries.  You can fix this easily by
 changing the global value of the parapraph boundary detection to
 recognize such lists, like this::
 
-   (setq paragraph-start (concat paragraph-start "\\|[ \t]*[-+*] "))
+   (add-hook 'text-mode-hook
+     (lambda () (setq paragraph-start rst-paragraph-start)))
 
 
 ``text-mode`` Settings
-- 
cgit v1.2.1


From 9c3c37edc8bfbbc040b8d2b7635dcf06d0522210 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Thu, 17 Nov 2005 23:36:02 +0000
Subject: use rst-set-paragraph-separation function for setting
 paragraph-start; removed stuff for filling quoted text -- it breaks for
 trailing quote signs and after all that's what message-mode is for

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4069 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 512c11fb2..4f44ffaf6 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -329,7 +329,7 @@ Settings for Filling Lists
 --------------------------
 
 One problem with the default text-mode settings is that *filling* long
-lines in bullet and enumeration lists that do not have an empty line
+lines in bulleted and enumeration lists that do not have an empty line
 between them merges them together, e.g.::
 
      - Bananas;
@@ -351,10 +351,10 @@ This is usually not what you want. What you want is this::
 The problem is that emacs does not recognize the various consecutive
 items as forming paragraph boundaries.  You can fix this easily by
 changing the global value of the parapraph boundary detection to
-recognize such lists, like this::
+recognize such lists, using the ``rst-set-paragraph-separation``
+function::
 
-   (add-hook 'text-mode-hook
-     (lambda () (setq paragraph-start rst-paragraph-start)))
+   (add-hook 'text-mode-hook 'rst-set-paragraph-separation)
 
 
 ``text-mode`` Settings
-- 
cgit v1.2.1


From 0d6963e76ab125e3fd6a4665dc06453964767f08 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 18 Nov 2005 04:26:30 +0000
Subject: corrected nomenclature

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4070 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/emacs.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/user/emacs.txt b/docs/user/emacs.txt
index 4f44ffaf6..49687f599 100644
--- a/docs/user/emacs.txt
+++ b/docs/user/emacs.txt
@@ -226,10 +226,10 @@ default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c
 C-p`` and ``C-c C-n``).
 
 
-Shifting Bulleted List Levels
-=============================
+Shifting Bullet List Levels
+===========================
 
-Due to the nature of reStructuredText_, bulleted lists are always
+Due to the nature of reStructuredText_, bullet lists are always
 indented by two characters (unless they are part of a blockquote),
 e.g. ::
 
@@ -244,7 +244,7 @@ e.g. ::
      - Zucchini
      - Chick Peas
 
-To this effect, when re-organizing bulleted lists, it can be useful to
+To this effect, when re-organizing bullet lists, it can be useful to
 shift regions of text by indents of two characters.  You can use the
 ``C-c C-r`` and ``C-c C-l`` to shift the current region.  These
 bindings are similar to the ones provided by python-mode for editing
@@ -329,7 +329,7 @@ Settings for Filling Lists
 --------------------------
 
 One problem with the default text-mode settings is that *filling* long
-lines in bulleted and enumeration lists that do not have an empty line
+lines in bullet and enumerated lists that do not have an empty line
 between them merges them together, e.g.::
 
      - Bananas;
-- 
cgit v1.2.1


From 498f4a1bb34f9b1544e7a1fe502e4f62deffdbc1 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Fri, 18 Nov 2005 18:51:36 +0000
Subject: added to do list entry for field lists in list tables

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4075 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 387939224..a4847139b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1035,6 +1035,9 @@ when used in a document.
 * Make the _`directive interface` object-oriented
   (http://article.gmane.org/gmane.text.docutils.user/1871).
 
+* Allow for field lists in list tables.  See
+  .
+  
 * .. _unify tables:
 
   Unify table implementations and unify options of table directives
-- 
cgit v1.2.1


From 27250a4e978bbf3aefad780671b2778e84dfaa5e Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 19 Nov 2005 19:22:56 +0000
Subject: added to-do list entry for different report levels

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4080 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index a4847139b..dded29d0d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -104,6 +104,9 @@ for inclusion in the Python standard library.
 General
 =======
 
+* Allow different report levels for STDERR and system_messages inside
+  the document?
+
 * Change the docutils-update script (in sandbox/infrastructure), to
   support arbitrary branch snapshots.
 
-- 
cgit v1.2.1


From 1b0ec60ec58759a103692f6ebd276d3738fb4ca2 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 19 Nov 2005 21:47:11 +0000
Subject: added to-do list entry about degenerate lists

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4081 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index dded29d0d..507e688dc 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -683,6 +683,10 @@ Also see the `... Or Not To Do?`__ list.
 
 __ rst/alternatives.html#or-not-to-do
 
+* Treat enumerated lists that are not arabic and consist of only one
+  item in a single line as ordinary paragraphs.  See
+  .
+
 * The citation syntax could use some enhancements.  See
    and
   .
-- 
cgit v1.2.1


From ced6843a40a4b84b50b10c1106edfe80e088fbaa Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Sat, 19 Nov 2005 23:48:04 +0000
Subject: allow escaped colons inside of fields

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4083 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 507e688dc..26f9ff237 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -912,13 +912,11 @@ __ rst/alternatives.html#or-not-to-do
 
   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, ``:\:`` is misinterpreted as a field name
-  (name ``\``; **bug**).  Assuming this bug is 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 "::"::
+  (There's one problem with this concession: If one wants a definition
+  list item which defines the term "::", we'd have to escape it.)  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::
-- 
cgit v1.2.1


From 96c5fe444943f9e2d940e12b4a4b0a97d28ae632 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 20 Nov 2005 06:18:08 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4087 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 26f9ff237..05d12007b 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -486,6 +486,9 @@ General
   specific source files, such as running rst2s5.py instead of
   rst2html.py.
 
+* Add a "disable table of contents" setting?  The S5 writer could set
+  it as a default.
+
 
 Documentation
 =============
-- 
cgit v1.2.1


From ccac3b33bd345ea21e0cbbda824f99ddcf11adb1 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Mon, 21 Nov 2005 19:50:32 +0000
Subject: updated spec to reflect that escaped colons inside of field names are
 now allowed; added history entry

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4092 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index d503d9054..e0cee6031 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -813,15 +813,16 @@ see `Bibliographic Fields`_ below, or the "image_" and "meta_"
 directives in `reStructuredText Directives`_.
 
 Field lists are mappings from field names to field bodies, modeled on
-RFC822_ headers.  A field name is made up of one or more letters,
-numbers, whitespace, and punctuation, except colons (":").  Inline
-markup is parsed in field names.  Field names are case-insensitive
-when further processed or transformed.  The field name, along with a
-single colon prefix and suffix, together form the field marker.  The
-field marker is followed by whitespace and the field body.  The field
-body may contain multiple body elements, indented relative to the
-field marker.  The first line after the field name marker determines
-the indentation of the field body.  For example::
+RFC822_ headers.  A field name may consist of any characters, but
+colons (":") inside of field names must be escaped with a backslash.
+Inline markup is parsed in field names.  Field names are
+case-insensitive when further processed or transformed.  The field
+name, along with a single colon prefix and suffix, together form the
+field marker.  The field marker is followed by whitespace and the
+field body.  The field body may contain multiple body elements,
+indented relative to the field marker.  The first line after the field
+name marker determines the indentation of the field body.  For
+example::
 
     :Date: 2001-08-16
     :Version: 1
-- 
cgit v1.2.1


From e5ba1950c904e32f886b52106e876f5c7de33a7c Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Mon, 21 Nov 2005 21:35:32 +0000
Subject: added to-do list entry for multiple stylesheets; re-added to-do list
 entry for separating PEP-specific stuff in pep.css

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4095 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 05d12007b..3fd9b55c6 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1658,6 +1658,9 @@ Unimplemented Transforms
 HTML Writer
 ===========
 
+* Add support for _`multiple stylesheets`.  See
+  .
+
 * Add more support for  elements, especially for navigation
   bars.
 
@@ -1677,6 +1680,15 @@ HTML Writer
   identifying them as such.  Text in Docutils language module.
 
 
+PEP/HTML Writer
+===============
+
+* Remove the generic style information (duplicated from html4css1.css)
+  from pep.css to avoid redundancy.
+
+  We need support for `multiple stylesheets`_ before, though.
+
+
 LaTeX writer
 ============
 
-- 
cgit v1.2.1


From 80230d4c0a272847d5181dcc78b1161be8f1e494 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 25 Nov 2005 05:01:36 +0000
Subject: added idea for config directories; clarified disable-ToC setting
 rationale

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4099 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 3fd9b55c6..36c450868 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -474,6 +474,13 @@ General
 
 * Add support for _`plugins`.
 
+* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
+  /etc/docutils.conf are read as configuration files.  Proposal: make
+  ~/.docutils/ into a configuration *directory*, along with
+  /etc/docutils/ and ./docutils.conf/.  Within these directories,
+  check for config.txt files.  We can also have subdirectories here,
+  for plugins, S5 themes, components (readers/writers/parsers) etc.
+
 * Add support for document decorations other than headers & footers?
   For example, top/bottom/side navigation bars for web pages.  Generic
   decorations?
@@ -487,7 +494,14 @@ General
   rst2html.py.
 
 * Add a "disable table of contents" setting?  The S5 writer could set
-  it as a default.
+  it as a default.  Rationale:
+
+      The ``contents`` (table of contents) directive must not be used
+      [in S5/HTML documents].  It changes the CSS class of headings
+      and they won't show up correctly in the screen presentation.
+
+      -- `Easy Slide Shows With reStructuredText & S5
+         <../user/slide-shows.html>`_
 
 
 Documentation
-- 
cgit v1.2.1


From b5d3261cc76590df360d65281f8cf7d6370eb4a8 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Fri, 25 Nov 2005 21:46:28 +0000
Subject: added bug about block quote attributions; fixed typo in todo.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4105 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 36c450868..e9561c488 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -501,7 +501,7 @@ General
       and they won't show up correctly in the screen presentation.
 
       -- `Easy Slide Shows With reStructuredText & S5
-         <../user/slide-shows.html>`_
+      <../user/slide-shows.html>`_
 
 
 Documentation
-- 
cgit v1.2.1


From 312ae3b66e2a73eb282566124c5a964e6954159b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 28 Nov 2005 00:33:23 +0000
Subject: added examples & elaboration for custom "directive" directive;
 whitespace & minor tweaks

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4106 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 39 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 34 insertions(+), 5 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index e9561c488..468ef32d1 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -475,12 +475,15 @@ General
 * Add support for _`plugins`.
 
 * _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
-  /etc/docutils.conf are read as configuration files.  Proposal: make
-  ~/.docutils/ into a configuration *directory*, along with
+  /etc/docutils.conf are read as configuration files.  Proposal: allow
+  ~/.docutils to be a a configuration *directory*, along with
   /etc/docutils/ and ./docutils.conf/.  Within these directories,
   check for config.txt files.  We can also have subdirectories here,
   for plugins, S5 themes, components (readers/writers/parsers) etc.
 
+  Docutils will continue to support configuration files for backwards
+  compatibility.
+
 * Add support for document decorations other than headers & footers?
   For example, top/bottom/side navigation bars for web pages.  Generic
   decorations?
@@ -740,7 +743,7 @@ __ rst/alternatives.html#or-not-to-do
 
       quote 2
 
-      ---Attrib 2  
+      ---Attrib 2
 
 * Change the specification so that more punctuation is allowed
   before/after inline markup start/end string
@@ -1059,7 +1062,7 @@ when used in a document.
 
 * Allow for field lists in list tables.  See
   .
-  
+
 * .. _unify tables:
 
   Unify table implementations and unify options of table directives
@@ -1196,7 +1199,33 @@ when used in a document.
   - _`misc.gather`: Gather (move, or copy) all instances of a specific
     element.  A generalization of the "endnotes" & "citations" ideas.
 
-  - Add a "directive" directive, equivalent to "role"?
+  - Add a custom "directive" directive, equivalent to "role"?  For
+    example::
+
+        .. directive:: incr
+
+           .. class:: incremental
+
+        .. incr::
+
+        "``.. incr::``" above is equivalent to "``.. class:: incremental``".
+
+    Another example::
+
+        .. directive:: printed-links
+
+           .. topic:: Links
+              :class: print-block
+
+              .. target-notes::
+                 :class: print-inline
+
+    This acts like macros.  The directive contents will have to be
+    evaluated when referenced, not when defined.  
+
+    * Call the directive "macro"?
+    * What to do with directive arguments & options when the
+      macro/directive is referenced?
 
   - .. _conditional directives:
 
-- 
cgit v1.2.1


From c6b28c3a2265fe50a0db10d79706a2872dbb63fb Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 1 Dec 2005 00:56:35 +0000
Subject: removed "qa" directive idea from docs/dev/todo.txt; added it to
 docs/dev/rst/alternatives.txt ("not implemented"); added FAQ entry about
 marking up FAQs

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4120 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/rst/alternatives.txt | 44 ++++++++++++++++++++++++++++++++++++++++++-
 docs/dev/todo.txt             | 44 ++++++++-----------------------------------
 2 files changed, 51 insertions(+), 37 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt
index d6e0957e7..12874c5fb 100644
--- a/docs/dev/rst/alternatives.txt
+++ b/docs/dev/rst/alternatives.txt
@@ -2095,6 +2095,49 @@ the "auto-symbol footnote" concept, which has been added.  Citations
 and citation references have also been added.
 
 
+Syntax for 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::
+
+    
+    
+    
+    
+    
+
+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.
+
+As described in the FAQ__, no special syntax or directive is needed
+for this application.
+
+__ http://docutils.sf.net/FAQ.html
+   #how-can-i-mark-up-a-faq-or-other-list-of-questions-answers
+
+
 --------
  Tabled
 --------
@@ -3076,7 +3119,6 @@ idea, and there is no "tool tip" in formats other than HTML.
 Add a "term" role for unfamiliar or specialized terminology?  Probably
 not; there is no real use case, and emphasis is enough for most cases.
 
-
 
 ..
    Local Variables:
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 468ef32d1..993b54813 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1284,42 +1284,6 @@ when used in a document.
            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::
-
-        
-        
-        
-        
-        
-
-    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.
@@ -1704,6 +1668,14 @@ HTML Writer
 * Add support for _`multiple stylesheets`.  See
   .
 
+* Idea for field-list rendering: hanging indent::
+
+      Field name (bold): First paragraph of field body begins
+          with the field name inline.
+
+          If the first item of a field body is not a paragraph,
+          it would begin on the following line.
+
 * Add more support for  elements, especially for navigation
   bars.
 
-- 
cgit v1.2.1


From 507cddee06eea200d202f38761c960815a814517 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 5 Dec 2005 17:41:58 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4142 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 993b54813..364b783db 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1223,7 +1223,7 @@ when used in a document.
     This acts like macros.  The directive contents will have to be
     evaluated when referenced, not when defined.  
 
-    * Call the directive "macro"?
+    * Needs a better name?  "Macro", "substitution"?
     * What to do with directive arguments & options when the
       macro/directive is referenced?
 
-- 
cgit v1.2.1


From 2c7be05e9e776313b36c539c205a63295ace5107 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 7 Dec 2005 23:45:52 +0000
Subject: minor fix

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4151 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 364b783db..06ce321f1 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -50,7 +50,12 @@ the short term) to include:
 * [DONE in rev. 3962] Incorporate new branch policy into the docs.
   ("Development strategy" thread on Docutils-develop)
 
-* Fix East-Asian `double-width characters`_ issue.  [DavidG]
+* [DONE in rev. 4152] Added East-Asian double-width character support.
+
+* Merge the S5 branch.
+
+* Convert ``docutils/writers/support/*`` to individual writer
+  packages.
 
 Anything else?
 
@@ -764,22 +769,8 @@ __ rst/alternatives.html#or-not-to-do
 * Add test for ":figwidth: image" option of "figure" directive.  (Test
   code needs to check if PIL is available on the system.)
 
-* 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.
-
-  Especially the table parsers suffer from this problem.
-
-  We need to use the ``unicodedata.east_asian_width`` function,
-  introduced in Python 2.4.
-
-  From `Unicode Standard Annex #11: East Asian Width
-  `_:
-
-      In a broad sense, wide characters include W, F, and A (when in
-      EA context), while narrow characters include N, Na, H, and A
-      (when not in EA context).
+* Add support for CJK double-width whitespace & punctuation
+  characters?
 
 * Add motivation sections for constructs in spec.
 
@@ -1701,7 +1692,7 @@ PEP/HTML Writer
 * Remove the generic style information (duplicated from html4css1.css)
   from pep.css to avoid redundancy.
 
-  We need support for `multiple stylesheets`_ before, though.
+  We need support for `multiple stylesheets`_ first, though.
 
 
 LaTeX writer
-- 
cgit v1.2.1


From 118dd3d2aa36cf563590197e28830c1a905f9cd8 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 8 Dec 2005 04:43:13 +0000
Subject: merged branches/s5 changes r4011:4155 into trunk/docutils

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt              |  19 +-
 docs/index.txt                    |   5 +-
 docs/ref/rst/definitions.txt      | 180 +++++++
 docs/ref/rst/directives.txt       |   8 +-
 docs/ref/rst/substitutions.txt    | 162 -------
 docs/user/config.txt              |  68 ++-
 docs/user/images/big-black.png    | Bin 0 -> 19823 bytes
 docs/user/images/big-white.png    | Bin 0 -> 25697 bytes
 docs/user/images/default.png      | Bin 0 -> 59358 bytes
 docs/user/images/happy_monkey.png | Bin 0 -> 5202 bytes
 docs/user/images/medium-black.png | Bin 0 -> 24021 bytes
 docs/user/images/medium-white.png | Bin 0 -> 33756 bytes
 docs/user/images/rsp-all.png      | Bin 0 -> 32565 bytes
 docs/user/images/rsp-breaks.png   | Bin 0 -> 17754 bytes
 docs/user/images/rsp-covers.png   | Bin 0 -> 19080 bytes
 docs/user/images/rsp-cuts.png     | Bin 0 -> 20751 bytes
 docs/user/images/rsp-empty.png    | Bin 0 -> 4900 bytes
 docs/user/images/rsp-objects.png  | Bin 0 -> 21291 bytes
 docs/user/images/rsp.svg          | 636 ++++++++++++++++++++++++
 docs/user/images/s5-files.png     | Bin 0 -> 25404 bytes
 docs/user/images/s5-files.svg     | 639 +++++++++++++++++++++++++
 docs/user/images/small-black.png  | Bin 0 -> 41144 bytes
 docs/user/images/small-white.png  | Bin 0 -> 41120 bytes
 docs/user/slide-shows.txt         | 984 ++++++++++++++++++++++++++++++++++++++
 docs/user/tools.txt               | 142 +++++-
 25 files changed, 2652 insertions(+), 191 deletions(-)
 create mode 100644 docs/ref/rst/definitions.txt
 delete mode 100644 docs/ref/rst/substitutions.txt
 create mode 100644 docs/user/images/big-black.png
 create mode 100644 docs/user/images/big-white.png
 create mode 100644 docs/user/images/default.png
 create mode 100644 docs/user/images/happy_monkey.png
 create mode 100644 docs/user/images/medium-black.png
 create mode 100644 docs/user/images/medium-white.png
 create mode 100644 docs/user/images/rsp-all.png
 create mode 100644 docs/user/images/rsp-breaks.png
 create mode 100644 docs/user/images/rsp-covers.png
 create mode 100644 docs/user/images/rsp-cuts.png
 create mode 100644 docs/user/images/rsp-empty.png
 create mode 100644 docs/user/images/rsp-objects.png
 create mode 100644 docs/user/images/rsp.svg
 create mode 100644 docs/user/images/s5-files.png
 create mode 100644 docs/user/images/s5-files.svg
 create mode 100644 docs/user/images/small-black.png
 create mode 100644 docs/user/images/small-white.png
 create mode 100644 docs/user/slide-shows.txt

(limited to 'docs')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 6963f6541..82e9ed31c 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -193,12 +193,21 @@ file name (relative to ``functional/output/`` and
 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.
+If defined, ``_test_more`` must be a function with the following
+signature::
 
-Note that ``settings_overrides`` is already initialized as a
-dictionary *before* the execution of the config file.
+    def _test_more(expected_dir, output_dir, test_case, parameters):
+
+This function is called from the test case to perform tests beyond the
+simple comparison of expected and actual output files.
+
+``test_source`` and ``test_destination`` are removed from the
+namespace, as are all variables whose names begin with an underscore
+("_").  The remaining names 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 a dictionary *before*
+the execution of the config file.
 
 
 Creating New Tests
diff --git a/docs/index.txt b/docs/index.txt
index 69cceb717..e25d66e07 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -79,6 +79,7 @@ top level of the Docutils project directory.
 Docutils-general:
 
 * `Docutils Front-End Tools `__
+* `Easy Slide Shows With reStructuredText & S5 `__
 * `Docutils Configuration Files `__
 * `Docutils LaTeX Writer `__
 * `Docutils Mailing Lists `__
@@ -128,8 +129,8 @@ reStructuredText_:
 * `reStructuredText Markup Specification `__
 * `reStructuredText Directives `__
 * `reStructuredText Interpreted Text Roles `__
-* `reStructuredText Standard Substitution Definition Sets
-  `_
+* `reStructuredText Standard Definition Files
+  `_
 
 Prehistoric:
 
diff --git a/docs/ref/rst/definitions.txt b/docs/ref/rst/definitions.txt
new file mode 100644
index 000000000..78a2bf8da
--- /dev/null
+++ b/docs/ref/rst/definitions.txt
@@ -0,0 +1,180 @@
+============================================
+ reStructuredText Standard Definition Files
+============================================
+:Author: David Goodger
+:Contact: goodger@python.org
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+This document describes standard definition files, such as sets of
+substitution definitions and interpreted text roles, that can be
+included in reStructuredText documents.  The `"include" directive`__
+has a special syntax for these standard definition files, angle
+brackets around the file name::
+
+    .. include:: 
+
+__ directives.html#include
+
+The individual data files are stored with the Docutils source code in
+the "docutils" package, in the ``docutils/parsers/rst/include``
+directory.
+
+
+Substitution Definitions
+========================
+
+Many of the standard definition files contain sets of `substitution
+definitions`__, which can be used in documents via `substitution
+references`__.  For example, the copyright symbol is defined in
+``isonum.txt`` as "copy"::
+
+    .. include:: 
+
+    Copyright |copy| 2003 by John Q. Public, all rights reserved.
+
+__ restructuredtext.html#substitution-definitions
+__ restructuredtext.html#substitution-references
+
+Individual substitution definitions can also be copied from definition
+files and pasted into documents.  This has two advantages: it removes
+dependencies, and it saves processing of unused definitions.  However,
+multiple substitution definitions add clutter to the document.
+
+Substitution references require separation from the surrounding text
+with whitespace or punctuation.  To use a substitution without
+intervening whitespace, you can use the disappearing-whitespace escape
+sequence, backslash-space::
+
+    .. include:: isonum.txt
+
+    Copyright |copy| 2003, BogusMegaCorp\ |trade|.
+
+Custom substitution definitions may use the `"unicode" directive`__.
+Whitespace is ignored and removed, effectively sqeezing together the
+text::
+
+    .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
+
+    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+
+__ directives.html#unicode
+
+In addition, the "ltrim", "rtrim", and "trim" options may be used with
+the "unicode" directive to automatically trim spaces from the left,
+right, or both sides (respectively) of substitution references::
+
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
+
+
+Character Entity Sets
+---------------------
+
+The following files contain substitution definitions corresponding to
+XML character entity sets, from the following standards: ISO 8879 &
+ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
+the ``tools/dev/unicode2rstsubs.py`` program from the input file
+unicode.xml__, which is maintained as part of the MathML 2
+Recommentation XML source.
+
+__ http://www.w3.org/2003/entities/xml/
+
+===================  =================================================
+Entity Set File      Description
+===================  =================================================
+isoamsa.txt_         Added Mathematical Symbols: Arrows
+isoamsb.txt_         Added Mathematical Symbols: Binary Operators
+isoamsc.txt_         Added Mathematical Symbols: Delimiters
+isoamsn.txt_         Added Mathematical Symbols: Negated Relations
+isoamso.txt_         Added Mathematical Symbols: Ordinary
+isoamsr.txt_         Added Mathematical Symbols: Relations
+isobox.txt_          Box and Line Drawing
+isocyr1.txt_         Russian Cyrillic
+isocyr2.txt_         Non-Russian Cyrillic
+isodia.txt_          Diacritical Marks
+isogrk1.txt_         Greek Letters
+isogrk2.txt_         Monotoniko Greek
+isogrk3.txt_         Greek Symbols
+isogrk4.txt_  [1]_   Alternative Greek Symbols
+isolat1.txt_         Added Latin 1
+isolat2.txt_         Added Latin 2
+isomfrk.txt_  [1]_   Mathematical Fraktur
+isomopf.txt_  [1]_   Mathematical Openface (Double-struck)
+isomscr.txt_  [1]_   Mathematical Script
+isonum.txt_          Numeric and Special Graphic
+isopub.txt_          Publishing
+isotech.txt_         General Technical
+mmlalias.txt_        MathML aliases for entities from other sets
+mmlextra.txt_ [1]_   Extra names added by MathML
+xhtml1-lat1.txt_     XHTML Latin 1
+xhtml1-special.txt_  XHTML Special Characters
+xhtml1-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
+===================  =================================================
+
+.. [1] There are ``*-wide.txt`` variants for each of these character
+   entity set files, containing characters outside of the Unicode
+   basic multilingual plane or BMP (wide-Unicode; code points greater
+   than U+FFFF).  Most pre-built Python distributions are "narrow" and
+   do not support wide-Unicode characters.  Python *can* be built with
+   wide-Unicode support though; consult the Python build instructions
+   for details.
+
+For example, the copyright symbol is defined as the XML character
+entity ``©``.  The equivalent reStructuredText substitution
+reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
+``|copy|``.
+
+.. _isoamsa.txt:        ../../../docutils/parsers/rst/include/isoamsa.txt
+.. _isoamsb.txt:        ../../../docutils/parsers/rst/include/isoamsb.txt
+.. _isoamsc.txt:        ../../../docutils/parsers/rst/include/isoamsc.txt
+.. _isoamsn.txt:        ../../../docutils/parsers/rst/include/isoamsn.txt
+.. _isoamso.txt:        ../../../docutils/parsers/rst/include/isoamso.txt
+.. _isoamsr.txt:        ../../../docutils/parsers/rst/include/isoamsr.txt
+.. _isobox.txt:         ../../../docutils/parsers/rst/include/isobox.txt
+.. _isocyr1.txt:        ../../../docutils/parsers/rst/include/isocyr1.txt
+.. _isocyr2.txt:        ../../../docutils/parsers/rst/include/isocyr2.txt
+.. _isodia.txt:         ../../../docutils/parsers/rst/include/isodia.txt
+.. _isogrk1.txt:        ../../../docutils/parsers/rst/include/isogrk1.txt
+.. _isogrk2.txt:        ../../../docutils/parsers/rst/include/isogrk2.txt
+.. _isogrk3.txt:        ../../../docutils/parsers/rst/include/isogrk3.txt
+.. _isogrk4.txt:        ../../../docutils/parsers/rst/include/isogrk4.txt
+.. _isolat1.txt:        ../../../docutils/parsers/rst/include/isolat1.txt
+.. _isolat2.txt:        ../../../docutils/parsers/rst/include/isolat2.txt
+.. _isomfrk.txt:        ../../../docutils/parsers/rst/include/isomfrk.txt
+.. _isomopf.txt:        ../../../docutils/parsers/rst/include/isomopf.txt
+.. _isomscr.txt:        ../../../docutils/parsers/rst/include/isomscr.txt
+.. _isonum.txt:         ../../../docutils/parsers/rst/include/isonum.txt
+.. _isopub.txt:         ../../../docutils/parsers/rst/include/isopub.txt
+.. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
+.. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
+.. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
+.. _xhtml1-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
+.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
+.. _xhtml1-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
+
+
+S5/HTML Definitions
+===================
+
+The "s5defs.txt_" standard definition file contains interpreted text
+roles (classes) and other definitions for documents destined to become
+`S5/HTML slide shows`_.  
+
+.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt
+.. _S5/HTML slide shows: ../../user/slide-shows.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 58fa324cf..12959e86d 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1065,7 +1065,7 @@ Target Footnotes
 :Directive Type: "target-notes"
 :Doctree Elements: pending, footnote, footnote_reference
 :Directive Arguments: None.
-:Directive Options: None.
+:Directive Options: Possible.
 :Directive Content: None.
 
 The "target-notes" directive creates a footnote for each external
@@ -1074,6 +1074,12 @@ reference.  For every explicit target (of the form, ``.. _target name:
 URL``) in the text, a footnote will be generated containing the
 visible URL as content.
 
+The following option is recognized:
+
+``class`` : text
+    Set a "class" attribute value on all footnote_reference elements.
+    See the class_ directive below.
+
 
 Footnotes
 =========
diff --git a/docs/ref/rst/substitutions.txt b/docs/ref/rst/substitutions.txt
deleted file mode 100644
index 5ea9562f2..000000000
--- a/docs/ref/rst/substitutions.txt
+++ /dev/null
@@ -1,162 +0,0 @@
-========================================================
- reStructuredText Standard Substitution Definition Sets
-========================================================
-:Author: David Goodger
-:Contact: goodger@python.org
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-.. contents::
-
-
-The data files described below contain sets of reStructuredText
-`substitution definitions`__.  They can be included in documents using
-the `"include" directive's`__ special syntax for standard data files,
-angle brackets around the file name::
-
-    .. include:: 
-
-__ restructuredtext.html#substitution-definitions
-__ directives.html#include
-
-The definitions can then be used in documents using `substitution
-references`__.  For example, the copyright symbol is defined in
-``isonum.txt`` as "copy"::
-
-    .. include:: 
-
-    Copyright |copy| 2003 by John Q. Public, all rights reserved.
-
-__ restructuredtext.html#substitution-references
-
-Individual definitions can also be copied from these data files and
-pasted into documents.  This has two advantages: it removes
-dependencies, and it saves processing of unused definitions.  However,
-multiple substitution definitions add clutter to the document.
-
-Substitution references require separation from the surrounding text
-with whitespace or punctuation.  To use a substitution without
-intervening whitespace, you can use the disappearing-whitespace escape
-sequence, backslash-space::
-
-    .. include:: isonum.txt
-
-    Copyright |copy| 2003, BogusMegaCorp\ |trade|.
-
-Custom definitions may use the `"unicode" directive`__.  Whitespace is
-ignored and removed, effectively sqeezing together the text::
-
-    .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
-    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
-       .. with trademark sign
-
-    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
-
-__ directives.html#unicode
-
-In addition, the "ltrim", "rtrim", and "trim" options may be used with
-the "unicode" directive to automatically trim spaces from the left,
-right, or both sides (respectively) of substitution references::
-
-    .. |---| unicode:: U+02014 .. em dash
-       :trim:
-
-The individual data files are stored with the Docutils source code in
-the "docutils" package, in the ``docutils/parsers/rst/include``
-directory.
-
-
-Character Entity Sets
-=====================
-
-The following files contain substitution definitions corresponding to
-XML character entity sets, from the following standards: ISO 8879 &
-ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
-the ``tools/dev/unicode2rstsubs.py`` program from the input file
-unicode.xml__, which is maintained as part of the MathML 2
-Recommentation XML source.
-
-__ http://www.w3.org/2003/entities/xml/
-
-===================  =================================================
-Entity Set File      Description
-===================  =================================================
-isoamsa.txt_         Added Mathematical Symbols: Arrows
-isoamsb.txt_         Added Mathematical Symbols: Binary Operators
-isoamsc.txt_         Added Mathematical Symbols: Delimiters
-isoamsn.txt_         Added Mathematical Symbols: Negated Relations
-isoamso.txt_         Added Mathematical Symbols: Ordinary
-isoamsr.txt_         Added Mathematical Symbols: Relations
-isobox.txt_          Box and Line Drawing
-isocyr1.txt_         Russian Cyrillic
-isocyr2.txt_         Non-Russian Cyrillic
-isodia.txt_          Diacritical Marks
-isogrk1.txt_         Greek Letters
-isogrk2.txt_         Monotoniko Greek
-isogrk3.txt_         Greek Symbols
-isogrk4.txt_  [1]_   Alternative Greek Symbols
-isolat1.txt_         Added Latin 1
-isolat2.txt_         Added Latin 2
-isomfrk.txt_  [1]_   Mathematical Fraktur
-isomopf.txt_  [1]_   Mathematical Openface (Double-struck)
-isomscr.txt_  [1]_   Mathematical Script
-isonum.txt_          Numeric and Special Graphic
-isopub.txt_          Publishing
-isotech.txt_         General Technical
-mmlalias.txt_        MathML aliases for entities from other sets
-mmlextra.txt_ [1]_   Extra names added by MathML
-xhtml1-lat1.txt_     XHTML Latin 1
-xhtml1-special.txt_  XHTML Special Characters
-xhtml1-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
-===================  =================================================
-
-.. [1] There are ``*-wide.txt`` variants for each of these character
-   entity set files, containing characters outside of the Unicode
-   basic multilingual plane or BMP (wide-Unicode; code points greater
-   than U+FFFF).  Most pre-built Python distributions are "narrow" and
-   do not support wide-Unicode characters.  Python *can* be built with
-   wide-Unicode support though; consult the Python build instructions
-   for details.
-
-For example, the copyright symbol is defined as the XML character
-entity ``©``.  The equivalent reStructuredText substitution
-reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
-``|copy|``.
-
-.. _isoamsa.txt:        ../../../docutils/parsers/rst/include/isoamsa.txt
-.. _isoamsb.txt:        ../../../docutils/parsers/rst/include/isoamsb.txt
-.. _isoamsc.txt:        ../../../docutils/parsers/rst/include/isoamsc.txt
-.. _isoamsn.txt:        ../../../docutils/parsers/rst/include/isoamsn.txt
-.. _isoamso.txt:        ../../../docutils/parsers/rst/include/isoamso.txt
-.. _isoamsr.txt:        ../../../docutils/parsers/rst/include/isoamsr.txt
-.. _isobox.txt:         ../../../docutils/parsers/rst/include/isobox.txt
-.. _isocyr1.txt:        ../../../docutils/parsers/rst/include/isocyr1.txt
-.. _isocyr2.txt:        ../../../docutils/parsers/rst/include/isocyr2.txt
-.. _isodia.txt:         ../../../docutils/parsers/rst/include/isodia.txt
-.. _isogrk1.txt:        ../../../docutils/parsers/rst/include/isogrk1.txt
-.. _isogrk2.txt:        ../../../docutils/parsers/rst/include/isogrk2.txt
-.. _isogrk3.txt:        ../../../docutils/parsers/rst/include/isogrk3.txt
-.. _isogrk4.txt:        ../../../docutils/parsers/rst/include/isogrk4.txt
-.. _isolat1.txt:        ../../../docutils/parsers/rst/include/isolat1.txt
-.. _isolat2.txt:        ../../../docutils/parsers/rst/include/isolat2.txt
-.. _isomfrk.txt:        ../../../docutils/parsers/rst/include/isomfrk.txt
-.. _isomopf.txt:        ../../../docutils/parsers/rst/include/isomopf.txt
-.. _isomscr.txt:        ../../../docutils/parsers/rst/include/isomscr.txt
-.. _isonum.txt:         ../../../docutils/parsers/rst/include/isonum.txt
-.. _isopub.txt:         ../../../docutils/parsers/rst/include/isopub.txt
-.. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
-.. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
-.. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
-.. _xhtml1-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
-.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
-.. _xhtml1-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   End:
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 2f6fa40c8..cbd874972 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -345,7 +345,8 @@ _`sectnum_xform`
     Enable or disable the section numbering transform
     (docutils.transforms.parts.SectNum).
 
-    Default: enabled (1).  Options: ``--no-section-numbering``.
+    Default: enabled (1).  Options: ``--section-numbering``,
+    ``--no-section-numbering``.
 
 _`source_link`
     Include a "View document source" link in the document footer.  URL
@@ -584,16 +585,18 @@ _`cloak_email_addresses`
 _`compact_lists`
     Remove extra vertical whitespace between items of bullet lists and
     enumerated lists, when list items are "simple" (i.e., all items
-    each contain one paragraph and/or one "simple" sublist only).
+    each contain one paragraph and/or one "simple" sublist only).  The
+    behaviour can be specified directly via "class" attributes (values
+    "compact" and "open") in the document.
 
     Default: enabled (1).  Options: ``--compact-lists,
     --no-compact-lists``.
 
 _`compact_field_lists`
-
     Remove extra vertical whitespace between items of field lists that
     are "simple" (i.e., all field bodies each contain at most one
-    paragraph).
+    paragraph).  The behaviour can be specified directly via "class"
+    attributes (values "compact" and "open") in the document.
 
     Default: enabled (1).  Options: ``--compact-field-lists,
     --no-compact-field-lists``.
@@ -643,9 +646,9 @@ _`option_limit`
 .. _stylesheet [html4css1 writer]:
 
 stylesheet
-    CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
-    [#override]_.  Pass an empty string to deactivate stylesheet
-    inclusion.
+    CSS stylesheet URL, used verbatim.  Overrides the
+    "stylesheet_path" setting [#override]_.  Pass an empty string to
+    deactivate stylesheet inclusion.
 
     Default: None.  Options: ``--stylesheet``.
 
@@ -656,10 +659,9 @@ stylesheet
 .. _stylesheet_path [html4css1 writer]:
 
 stylesheet_path
-    Path to CSS stylesheet [#pwd]_.  Overrides "stylesheet" URL
-    setting (``--stylesheet``) [#override]_.  Path is adjusted
-    relative to the output HTML file.  Also defined for the `LaTeX
-    Writer`__.
+    Path to CSS stylesheet [#pwd]_.  Overrides the "stylesheet" URL
+    setting [#override]_.  Path is adjusted relative to the output
+    HTML file.  Also defined for the `LaTeX Writer`__.
 
     Default: "html4css1.css" in the docutils/writers/support directory
     (installed automatically; for the exact machine-specific path, use
@@ -720,6 +722,50 @@ _`python_home`
     Default: parent directory ("..").  Options: ``--python-home``.
 
 
+[s5_html writer]
+.................
+
+The S5/HTML Writer derives from the standard HTML Writer, and shares
+all settings defined in the `[html4css1 writer]`_ section.  The
+"[html4css1 writer]" section of configuration files is processed
+before the "[s5_html writer]" section.
+
+The S5/HTML Writer's default for the ``compact_lists`` setting differs
+from that of the standard HTML Writer: the default here is to disable
+compact lists.
+
+_`current_slide`
+
+    Enable or disable the current slide indicator ("1/15").
+
+    Default: disabled (None).  Options: ``--current-slide``,
+    ``--no-current-slide``.
+
+_`overwrite_theme_files`
+    Allow or prevent the overwriting of existing theme files in the
+    ``ui/`` directory.  This has no effect if "theme_url_" is
+    used.
+
+    Default: keep existing theme files (None).  Options:
+    ``--keep-theme-files``, ``--overwrite-theme-files``.
+
+_`theme`
+    Name of an installed S5 theme, to be copied into a ``ui/``
+    subdirectory, beside the destination file (output HTML).  Note
+    that existing theme files will not be overwritten; the existing
+    theme directory you must be deleted manually.  Overrides the
+    "theme_url_" setting [#override]_.
+
+    Default: "default".  Option: ``--theme``.
+
+_`theme-url`
+    The URL of an S5 theme directory.  The destination file (output
+    HTML) will link to this theme; nothing will be copied.  Overrides
+    the "theme_" setting [#override]_.
+
+    Default: None.  Option: ``--theme-url``.
+
+
 [latex2e writer]
 ````````````````
 
diff --git a/docs/user/images/big-black.png b/docs/user/images/big-black.png
new file mode 100644
index 000000000..869a0cf9f
Binary files /dev/null and b/docs/user/images/big-black.png differ
diff --git a/docs/user/images/big-white.png b/docs/user/images/big-white.png
new file mode 100644
index 000000000..1ce6d7d7d
Binary files /dev/null and b/docs/user/images/big-white.png differ
diff --git a/docs/user/images/default.png b/docs/user/images/default.png
new file mode 100644
index 000000000..509eeddad
Binary files /dev/null and b/docs/user/images/default.png differ
diff --git a/docs/user/images/happy_monkey.png b/docs/user/images/happy_monkey.png
new file mode 100644
index 000000000..2164c06dd
Binary files /dev/null and b/docs/user/images/happy_monkey.png differ
diff --git a/docs/user/images/medium-black.png b/docs/user/images/medium-black.png
new file mode 100644
index 000000000..f851e679e
Binary files /dev/null and b/docs/user/images/medium-black.png differ
diff --git a/docs/user/images/medium-white.png b/docs/user/images/medium-white.png
new file mode 100644
index 000000000..e5a465a56
Binary files /dev/null and b/docs/user/images/medium-white.png differ
diff --git a/docs/user/images/rsp-all.png b/docs/user/images/rsp-all.png
new file mode 100644
index 000000000..3e5f5ede3
Binary files /dev/null and b/docs/user/images/rsp-all.png differ
diff --git a/docs/user/images/rsp-breaks.png b/docs/user/images/rsp-breaks.png
new file mode 100644
index 000000000..f2a31b098
Binary files /dev/null and b/docs/user/images/rsp-breaks.png differ
diff --git a/docs/user/images/rsp-covers.png b/docs/user/images/rsp-covers.png
new file mode 100644
index 000000000..597c2c2a8
Binary files /dev/null and b/docs/user/images/rsp-covers.png differ
diff --git a/docs/user/images/rsp-cuts.png b/docs/user/images/rsp-cuts.png
new file mode 100644
index 000000000..aa46b3876
Binary files /dev/null and b/docs/user/images/rsp-cuts.png differ
diff --git a/docs/user/images/rsp-empty.png b/docs/user/images/rsp-empty.png
new file mode 100644
index 000000000..f6b93c38b
Binary files /dev/null and b/docs/user/images/rsp-empty.png differ
diff --git a/docs/user/images/rsp-objects.png b/docs/user/images/rsp-objects.png
new file mode 100644
index 000000000..43ce276f1
Binary files /dev/null and b/docs/user/images/rsp-objects.png differ
diff --git a/docs/user/images/rsp.svg b/docs/user/images/rsp.svg
new file mode 100644
index 000000000..03445d3bc
--- /dev/null
+++ b/docs/user/images/rsp.svg
@@ -0,0 +1,636 @@
+
+
+
+  
+    
+    
+    
+    
+    
+      
+      
+      
+    
+    
+    
+    
+      
+      
+    
+    
+    
+    
+      
+      
+    
+    
+    
+      
+      
+      
+      
+    
+    
+    
+      
+      
+    
+    
+    
+    
+    
+    
+  
+  
+  
+    
+      
+        image/svg+xml
+        
+      
+    
+  
+  
+    
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+    
+  
+  
+    
+      
+        
+      
+      
+    
+  
+  
+    
+      
+      
+      
+      
+      
+      
+      
+      
+      
+    
+  
+  
+    
+      
+        
+      
+      
+    
+  
+  
+    
+      
+      
+      
+      
+    
+  
+  
+    
+      
+        
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
diff --git a/docs/user/images/s5-files.png b/docs/user/images/s5-files.png
new file mode 100644
index 000000000..53cbbf250
Binary files /dev/null and b/docs/user/images/s5-files.png differ
diff --git a/docs/user/images/s5-files.svg b/docs/user/images/s5-files.svg
new file mode 100644
index 000000000..a3e644a22
--- /dev/null
+++ b/docs/user/images/s5-files.svg
@@ -0,0 +1,639 @@
+
+
+
+  
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+  
+  
+  
+    
+      
+        image/svg+xml
+        
+      
+    
+  
+  
+    
+      
+        
+          
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+        
+        
+          
+          
+          
+          
+          
+          
+          
+        
+      
+      
+        
+          
+            
+            
+          
+          s5-core.css
+        
+        
+          
+            
+            
+          
+          framing.css
+        
+        
+          
+            
+            
+          
+          pretty.css
+        
+      
+      
+        
+          
+            
+            
+          
+          iepngfix.htc
+        
+        
+          
+            
+            
+          
+          blank.gif
+        
+      
+      
+        
+          
+            
+            
+          
+          outline.css
+        
+        
+          
+            
+            
+          
+          print.css
+        
+        
+          
+            
+            
+          
+          opera.css
+        
+        
+          
+            
+            
+          
+          slides.js
+        
+        
+          
+            
+            
+          
+          slides.css
+        
+      
+      
+        
+          
+          
+        
+        *.htmloutput
+      
+    
+  
+  
+
diff --git a/docs/user/images/small-black.png b/docs/user/images/small-black.png
new file mode 100644
index 000000000..f8d80d387
Binary files /dev/null and b/docs/user/images/small-black.png differ
diff --git a/docs/user/images/small-white.png b/docs/user/images/small-white.png
new file mode 100644
index 000000000..65f96895d
Binary files /dev/null and b/docs/user/images/small-white.png differ
diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
new file mode 100644
index 000000000..1fdd8398b
--- /dev/null
+++ b/docs/user/slide-shows.txt
@@ -0,0 +1,984 @@
+.. include:: 
+
+=============================================
+ Easy Slide Shows With reStructuredText & S5
+=============================================
+
+:Authors:   David Goodger & Chris Liechti
+:Date:      $Date$
+
+.. This document has been placed in the public domain.
+
+.. class:: handout
+
+   This document serves both as a user manual and as a usage example
+   of the s5_html.py writer and the rst2s5.py front end.
+
+.. contents::
+   :class: handout
+
+How to create quick, good-looking presentation slide shows with
+Docutils_/reStructuredText_ and S5_.
+
+.. class:: small
+
+* Use the arrow keys to navigate.
+
+* Click the "|mode|" button to switch between presentation &
+  handout/outline modes.
+
+.. container:: handout
+
+   In presentation mode, mouse over to the lower right-hand corner to
+   display the controls.
+
+   The first slide of a presentation consists of all visible text up
+   to the first section title.  The document title is also added to
+   the footer of all slides.
+
+   The "footer" directive is used to specify part of the slide footer
+   text.  It is currently limited to one short line (one paragraph).
+
+   There is no support for the "header" directive in the themes
+   included with Docutils.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _S5: http://meyerweb.com/eric/tools/s5/
+.. |bullet| unicode:: U+02022
+.. |mode| unicode:: U+00D8 .. capital o with stroke
+.. footer:: Location |bullet| Date
+
+
+Introduction
+============
+
+.. class:: handout
+
+   ``rst2s5.py`` is a Docutils_ front end that outputs HTML for use
+   with S5_, a "Simple Standards-based Slide Show System" by Eric
+   Meyer.
+
+.. topic:: Installation
+   :class: handout
+
+   Prerequisites: Python and the Docutils_ package have to be
+   installed.  See the `Docutils README`__ file for installation
+   instructions.
+
+   __ http://docutils.sourceforge.net/README.html
+
+* reStructuredText
+
+  .. class:: handout
+
+  Uses normal reStructuredText as input.
+
+* One section per slide
+
+  .. class:: handout
+
+  Each first-level section is converted into a single slide.
+
+* (X)HTML output
+
+  .. class:: handout
+
+  Presentations can be viewed using any modern graphical web browser.
+  The browser must support CSS, JavaScript, and XHTML.  S5 even works
+  with IE!
+
+* Themes
+
+  .. class:: handout
+
+  A variety of themes are available.  See `Example Themes`_, below.
+
+* ``rst2s5.py``
+
+  .. class:: handout
+
+  The front-end tool to generate S5 slide shows.
+
+.. topic:: Keyboard Controls
+   :class: handout
+
+   The following apply in any supporting browser besides Opera, which
+   uses the default Opera Show controls instead.
+
+   .. list-table::
+      :header-rows: 1
+
+      * - Action
+        - Key(s)
+      * - Go to the next slide
+        - * [Space bar]
+          * [Return]
+          * [Enter]
+          * [Right arrow]
+          * [Down arrow]
+          * [Page down]
+          * Click the left mouse button outside of the control area,
+            Flash object, or movie
+      * - Go to the previous slide
+        - * [Left arrow]
+          * [Up arrow]
+          * [Page up]
+      * - Go to the title (first) slide
+        - [Home]
+      * - Go to the last slide
+        - [End]
+      * - Jump directly to a slide
+        - Type the slide number, then hit [Return] or [Enter]
+      * - Skip forward *n* slides
+        - Type the number of slides to skip, then hit any "go to next"
+          key (except [Return] or [Enter])
+      * - Skip backward *n* slides
+        - Type the number of slides to skip, then hit any "go to
+          previous" key
+      * - Switch between slideshow and outline view
+        - * [T]
+          * Click the |mode| button
+      * - Show/hide slide controls
+        - * [C]
+          * Move the mouse pointer over the control area
+
+   Further details of the S5 user interface can be found at `Eric
+   Meyer's S5 page`__.
+
+   __ S5_
+
+
+Features (1)
+============
+
+.. container:: handout
+
+   The S5/HTML Writer supports all the standard Docutils HTML
+   features.
+
+S5-specific features:
+
+.. class:: incremental
+
+* The document title is duplicated on each slide in the S5 footer.
+
+* The ``footer`` directive may be used to define additional text in
+  the S5 footer.
+
+  .. container:: handout
+
+     But it is limited to one line of text.
+
+     This is useful for information such as the date of the
+     presentation and/or the location.  The field in the footer is
+     left blank if no ``footer`` directive is used.
+
+     Example::
+
+         .. footer:: Location - Date
+
+* Incremental display.
+
+  .. class:: handout
+
+  An "incremental" class can be assigned to lists and other elements
+  to get one-item-at-a-time behavior (like this list).
+
+
+Features (2): Handouts
+======================
+
+````
+
+.. container:: handout
+
+   The contents of any element with a "class" attribute value of
+   "handout" are hidden in the slide presentation, and are only
+   visible when the presentation is printed, or viewed in outline
+   mode.  "Handout"-class elements can appear anywhere in the text, as
+   often as needed.
+
+   This means that the slides and extra handout material can be
+   combined in one document.  The handout can be printed directly from
+   the browser, and it will contain more than just silly framed
+   slides.  This can be used to provide more detailed information, or
+   for speaker's notes.
+
+.. class:: incremental
+
+* Use the "class" directive::
+
+      .. class:: handout
+
+  .. container:: handout
+
+     The ``.. class:: handout`` directive can be used to tag
+     individual paragraphs and other elements.  The "class" directive
+     applies to the first element immediately following::
+
+         .. class:: handout
+
+         This paragraph will get a ``class="handout"`` attribute.
+
+         This paragraph will not be affected.
+
+     It also applies to multiple elements in the directive content::
+
+         .. class:: handout
+
+            These paragraphs are the content of the "class" directive.
+            And as such...
+
+            Both paragraphs will *individually* receive
+            ``class="handout"`` attributes.
+
+* Use the "container" directive::
+
+      .. container:: handout
+
+  .. container:: handout
+
+     Arbitrary handout blocks can be created using the ``container``
+     directive.  The content is treated as one.
+
+* Add a "class" option to certain directives::
+
+      .. topic:: Extra Material For Handouts
+         :class: handout
+
+.. container:: handout
+
+   The following directives support "class" options:
+
+   * all admonition directives ("admonition", "note", "hint", etc.)
+   * "image" & "figure"
+   * "topic"
+   * "sidebar"
+   * "line-block"
+   * "parsed-literal"
+   * "rubric"
+   * "compound"
+   * "table", "csv-table", & "list-table"
+   * "target-notes" (more about that below)
+   * "role" (pre-defined; more below)
+
+   Handout contents are also visible on the screen if the S5 view mode
+   is toggled from "slide show" to "outline" mode.
+
+
+Caveats
+=======
+
+.. class:: incremental
+
+1. Some Docutils features are not supported by some themes.
+
+   .. container:: handout
+
+      For example, header rendering is not supported by the themes
+      supplied with Docutils.
+
+      The "header" directive is used to set header text.  S5
+      automatically inserts section/slide titles into the "header"
+      area of a slide.  If both Docutils headers and S5 headers (slide
+      titles) exist simultaneously, they interfere with each other.
+
+2. Care must be taken with the "contents" directive.
+
+   .. container:: handout
+
+      The ``--no-toc-backlinks`` option is the default for the S5/HTML
+      writer (``toc_backlinks=0`` setting).  Other values for this
+      setting will change the CSS class of headings such that they
+      won't show up correctly in the slide show.
+
+      Use the ``:class: handout`` option on the "contents" directive
+      to limit the table of contents to the handout/outline mode
+      only::
+
+          .. contents::
+             :class: handout
+
+
+.. class:: incremental
+
+3. Subsections ...
+------------------
+
+... may be used, sparingly.
+
+.. container:: handout
+
+   Only first-level sections become slides.  Not many levels of
+   subsections can fit on a slide.
+
+   Subsections (of any level) work normally in handouts though.  Add
+   "``.. class:: handout``" before a subsection (or sub-subsection, or
+   ...), and the entire subsection will only appear in the handout.
+
+
+Generating a Slide Show (1)
+===========================
+
+.. class:: incremental
+
+1. Open a console (terminal, command shell) and go to the folder
+   containing your file, ``presentation.txt``.
+
+2. Run the command::
+
+       rst2s5.py presentation.txt \
+                 presentation.html
+
+3. Specify an S5 theme with the ``--theme`` option.
+
+   .. class:: handout
+
+   Docutils will copy the S5 theme files into a ``ui/`` folder
+   beside the output HTML file.  A slide show can also link to an
+   existing theme using the ``--theme-url`` option.
+
+
+Generating a Slide Show (2)
+===========================
+
+.. class:: incremental
+
+4. Include a copy of any linked stylesheet.
+
+   .. class:: handout
+
+   The default Docutils stylesheet, ``html4css1.css``, will normally
+   be embedded in the output HTML.  If you choose to link to a
+   stylesheet instead of embedding, you must include a copy (suggested
+   location: in the ``ui/`` directory).
+
+5. Open ``presentation.html`` in a web browser.
+
+6. Expand the browser window to full-screen mode, and speak.
+
+   .. class:: handout
+
+   The `Web Developer`__ extension for Firefox is very useful.  With
+   it, you can resize your browser window to the exact dimensions of
+   the projector you'll be using, so you can test beforehand.  There
+   are many other useful features as well.
+
+   __ http://chrispederick.com/work/webdeveloper/
+
+7. Profit!
+
+
+Examples (1)
+============
+
+.. sidebar:: Hint
+
+   Admonitions, tables, sidebars, and other elements can be used in
+   on-screen presentations in handouts.  Images too!
+
+   .. image:: images/happy_monkey.png
+       :alt: sample image
+
+=====  =====  ======
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   False  True
+False  True   True
+True   True   True
+=====  =====  ======
+
+
+Examples (2): Incremental Text
+==============================
+
+.. class:: incremental
+
+   Paragraphs can be displayed one at a time...
+
+   .. container::
+
+      ... or a bunch at a time.
+
+      This second paragraph is displayed together with the previous
+      one by grouping them with the "container" directive.
+
+| `We can also display` `one` `word` `at` `a` `time,`
+| `or a phrase` `at a time,`
+| `or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
+|
+| `(But the markup ain't pretty.)`
+
+
+Examples (3): Incr. Graphics
+============================
+
+Let's play... Rock, Scissors, Paper
+
+.. container:: animation
+
+   .. image:: images/rsp-empty.png
+
+   .. class:: incremental
+
+      .. image:: images/rsp-objects.png
+      .. image:: images/rsp-cuts.png
+      .. image:: images/rsp-covers.png
+      .. image:: images/rsp-breaks.png
+      .. image:: images/rsp-all.png
+
+
+Themes
+======
+
+.. class:: incremental
+
+* Several themes are available, and they're easy to adapt.
+
+  .. container:: handout
+
+     Themes from the `S5 tutorial`__ can be used.  These themes are in
+     the public domain and may be redistributed freely.
+
+     __ http://meyerweb.com/eric/tools/s5/s5blank.zip
+
+     Sites with other S5 themes:
+
+     * http://meyerweb.com/eric/tools/s5/themes/
+     * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs
+     * http://lachy.id.au/dev/mozilla/firefox/s5/
+
+     S5 is becoming more popular every day.  Do a web search for "S5
+     theme" and you're bound to find plenty of choices.
+
+* "``--theme``" option.
+
+  .. container:: handout
+
+     The theme can be specified with the "``--theme``" command-line
+     option.
+
+     Example::
+
+         rst2s5 --theme big-black presentation.txt presentation.html
+
+     The default theme is "default".
+
+* "``theme``" setting.
+
+  .. class:: handout
+
+  You can set the theme with the "``theme``" configuration file
+  setting.
+
+* Copied to ``./ui//``.
+
+  .. class:: handout
+
+  Themes are copied into a ``ui/`` folder inside the folder
+  containing the presentation.
+
+* Link with "``--theme-url``" option.
+
+  .. class:: handout
+
+  Link to a theme on the same or another web site, using the
+  "``--theme-url``" option or "``theme_url``" configuration file
+  setting.
+
+
+Example Themes
+==============
+
+.. class:: handout
+
+   The default theme, "default", is a simplified version of S5's
+   default theme.  It accommodates up to 13 lines of text.
+
+.. class:: center
+
+   "default"
+
+   .. image:: images/default.png
+      :align: center
+
+
+Example Themes: Small Text
+==========================
+
+.. class:: handout
+
+   The "small-white" and "small-black" themes are simplifications of
+   the default theme (**small** black text on a **white** background,
+   and **small** black text on a **white** background, respectively).
+   They each accommodate up to 15 lines of text.
+
+.. list-table::
+   :class: borderless
+
+   * - "small-white"
+
+       .. image:: images/small-white.png
+
+     - "small-black"
+
+       .. image:: images/small-black.png
+
+
+Example Themes: Large Text
+==========================
+
+.. class:: handout
+
+   The "big-white" and "big-black" themes feature very large, bold
+   text, with no footers.  Only five short lines of large text fits
+   per slide.
+
+.. list-table::
+   :class: borderless
+
+   * - "big-white"
+
+       .. image:: images/big-white.png
+
+     - "big-black"
+
+       .. image:: images/big-black.png
+
+
+Example Themes: Medium Text
+===========================
+
+.. class:: handout
+
+   The "medium-white" and "medium-black" themes feature medium-sized
+   text.  Up to 8 lines of text are accommodated.
+
+.. list-table::
+   :class: borderless
+
+   * - "medium-white"
+
+       .. image:: images/medium-white.png
+
+     - "medium-black"
+
+       .. image:: images/medium-black.png
+
+
+S5 Theme Files
+==============
+
+An S5 theme consists of a directory containing several files --
+stylesheets, JavaScript, and graphics:
+
+.. image:: images/s5-files.png
+   :align: center
+
+.. container:: handout
+
+   The generated HTML contains the entire slide show text.  It also
+   contains links to the following files:
+
+   * slides.css simply contains import links to:
+
+     - s5-core.css: Default styles critical to the proper functioning
+       of the slide show; don't touch this!
+
+     - framing.css: Sets the basic layout of slide components (header,
+       footer, controls, etc.  This file is the often edited.
+
+     - pretty.css: Presentation styles that give the slide show a
+       unique look and feel.  This is the file that you're most likely
+       to edit for a custom theme.  You can make a whole new theme
+       just by editing this file, and not touching the others.
+
+   * outline.css: Styles for outline mode.
+
+   * print.css: Styles for printing; hides most layout elements, and
+     may display others.
+
+   * opera.css: Styles necessary for the proper functioning of S5 in
+     Opera Show.
+
+   * slides.js: the JavaScript that drives the dynamic side of the
+     slide show (actions and navigation controls).  It automatically
+     IDs the slides when the document loads, builds the navigation
+     menu, handles the hiding and showing of slides, and so on.  The
+     code also manages the fallback to Opera Show if you're using
+     the Opera web browser.
+
+     Two files are included to support PNG transparency (alpha
+     channels) in Internet Explorer:
+
+     - iepngfix.htc
+     - blank.gif
+
+
+Making a Custom Theme
+=====================
+
+.. class:: incremental
+
+1. Run "``rst2s5.py --theme  .txt .html``".
+
+   .. class:: handout
+
+   This initializes the ``ui`` directory with the base theme files.
+
+2. Copy ``ui/`` to ``ui/``.
+
+3. Edit the styles.
+
+   .. class:: handout
+
+   Start with ``pretty.css``; edit ``framing.css`` if you need to make
+   layout changes.
+
+4. Run "``rst2s5.py --theme  .txt .html``".
+
+   .. class:: handout
+
+   Open your ``.html`` in a browser to test the new theme.
+
+5. Rinse & repeat.
+
+   .. class:: handout
+
+   Repeat from step 3 until you're satisfied.
+
+.. TODO: What to do next:
+
+   * add a ``__base__`` file
+   * create a personal reusable theme (plugin)
+   * submit the new theme to Docutils
+
+  ``docutils/writers/support/s5_html/``
+
+.. container:: handout
+
+   Resources:
+
+   * W3C's `Learning CSS `__
+
+   * `Creating An S5 Theme `__
+
+   * A short tutorial on how to create themes (in German):
+     `Eigenes Theme erstellen `__
+
+
+Classes: Incremental (1)
+========================
+
+.. class:: handout
+
+   Several "class" attribute values have built-in support in the
+   themes supplied with Docutils.
+
+.. class:: incremental
+
+   As described earlier,
+
+   * ``.. class:: incremental``
+
+   * ``.. container:: incremental``
+
+   * ::
+
+         .. sidebar:: title
+            :class: incremental
+
+
+Classes: Incremental (2)
+========================
+
+The "incremental" interpreted text role is also supported:
+
+.. class:: incremental
+
+   ::
+
+       :incremental:`This will appear first,` `and
+       this will appear second.`:incremental:
+
+   Requires "``.. include:: ``".
+
+.. container:: handout
+
+   As you can see, this markup is not very convenient.
+
+.. class:: incremental
+
+   | But ``s5defs.txt`` includes this useful definition:
+   | "``.. default-role:: incremental``".  So:
+
+   ::
+
+       `This` `is` `all` `we` `need`
+
+`This` `is` `all` `we` `need` `to mark up incremental text.`
+
+
+Classes: Incremental (3)
+========================
+
+.. class:: handout
+
+   The "animation" class is provided to support incremental graphics.
+   This is how the example earlier was done:
+
+::
+
+    .. container:: animation
+
+       .. image:: images/rsp-empty.png
+
+       .. class:: incremental
+
+          .. image:: images/rsp-objects.png
+          .. image:: images/rsp-cuts.png
+          .. image:: images/rsp-covers.png
+          .. image:: images/rsp-breaks.png
+          .. image:: images/rsp-all.png
+
+.. admonition:: Caveat
+   :class: handout
+
+   The animation effects are caused by placing successive images at
+   the same location, laying each image over the last.  For best
+   results, all images should be the same size, and the positions of
+   image elements should be consistent.  Use image transparency (alpha
+   channels) to get overlay effects.
+
+   Absolute positioning is used, which means that the images take up
+   no space in the flow.  If you want text to follow the images, you
+   have to specify the image sizes.  Otherwise, the images and any
+   following text will overlap.
+
+
+Classes: Text Size
+==================
+
+.. class:: incremental
+
+   * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```")
+   * :small:`small` ("small")
+   * normal (unstyled)
+   * :big:`big` ("big")
+   * :huge:`huge` ("huge")
+
+   Requires "``.. include:: ``".
+
+
+Classes: Alignment
+==================
+
+.. class:: incremental
+
+   .. class:: left
+
+   Left (class name: "left")
+
+   .. class:: center
+
+   Center ("center" & "centre")
+
+   .. class:: right
+
+   Right ("right")
+
+.. class:: handout
+
+   These classes apply to block-level elements only.  They cannot be
+   used for inline text (i.e., they're not interpreted text roles).
+
+.. class:: incremental
+
+   Example::
+
+       .. class:: center
+
+       Text to be centered.
+
+
+Classes: Text Colours
+=====================
+
+:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white`
+[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`,
+:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`,
+:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`,
+:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`,
+:purple:`purple`
+
+The class names and role names are the same as the colour names.  For
+example, "``:orange:`text```" produces ":orange:`text`".
+
+.. class:: incremental
+
+Requires "``.. include:: ``".
+
+
+Classes: Borderless Tables
+==========================
+
+.. class:: handout
+
+   Here's an ordinary, unstyled table:
+
+.. class:: incremental
+
+   =========  =======
+   Sometimes  borders
+   ---------  -------
+   are        useful.
+   =========  =======
+
+   And after applying "``.. class:: borderless``":
+
+   .. class:: borderless
+
+   =======  ==========  =======
+   But      sometimes,  borders
+   -------  ----------  -------
+   are      **not**     wanted.
+   =======  ==========  =======
+
+
+Classes: Print-Only
+===================
+
+.. class:: handout
+
+   Two classes are provided that only display their contents in
+   hardcopy.  The "print-block" class applies to block-level elements
+   (like paragraphs, lists, and topics).  The "print-inline" class
+   applies to text within paragraphs.
+
+.. class:: incremental
+
+   | "print-block" for block elements
+   | "print-inline" for inline text
+
+   Example: the "target-notes" directive::
+
+       .. topic:: Links
+          :class: print-block
+
+          .. target-notes::
+             :class: print-inline
+
+.. container:: handout
+
+   One good example, used in this document, is the "target-notes"
+   directive.  For each external target (hyperlink) in the text, this
+   directive generates a footnote containing the visible URL as
+   content.  Footnote references are placed after each hyperlink
+   reference.
+
+   The "topic" directive is given a "class" attribute with value
+   "print-block"; the entire topic will only be displayed when
+   printed.  The "target-notes" assigns a "class" attribute with value
+   "print-inline" to each of the footnote references it inserts
+   throughout the text; they will only show up when printed.
+
+.. class:: incremental
+
+   Other uses may require "``.. include:: ``".
+
+
+Chained Presentations
+=====================
+
+.. class:: handout
+
+   Presentation slide shows can be chained together.  This is useful
+   for including all or part of one presentation in another, and for
+   changing themes.  Slide numbers are not carried over, unless you
+   fake a continuous multi-themed presentation:
+
+   1. Generate slide show HTML files with two different names from
+      different themes but from the same source text.
+
+   2. Include a link to the **next** slide, in the **second** theme's
+      file.
+
+   3. To return to the first theme, include a link to the **next**
+      slide, in the **first** theme.
+
+From one theme, `to another...`__
+
+__ slide-shows-alt.html#chained-presentations-2
+
+
+Chained Presentations (2)
+=========================
+
+... and `back again...`__
+
+__ slide-shows.html#chained-presentations-3
+
+
+Chained Presentations (3)
+=========================
+
+... back to the first theme.
+
+.. container:: handout
+
+   Now we're back where we started from, back in the first theme, but
+   two slides further on.
+
+   In this way, any number of themes can be chained together.
+
+`Or you could cheat.`
+
+.. container:: handout
+
+   Just prepare the browser in advance, with all the slide show files
+   set up at the right slide in separate tabs in your browser, in the
+   right order.  Closing one tab will reveal the next.
+
+
+To Do
+=====
+
+.. class:: incremental
+
+   * Multi-display support:
+
+     - speaker's notes on the laptop screen
+     - slides on the projector
+     - two views stay in sync
+     - presentation controlled from either display
+
+   * Add timeout to incremental style.
+
+     .. class:: handout
+
+     I.e., incremental-specific style should go away (revert to
+     normal) after a certain interval.
+
+   These will require some serious JavaScript-fu!
+
+
+That's All, Folks!
+==================
+
+.. class:: huge
+
+   Further information:
+   http://docutils.sf.net
+
+   Docutils users' mailing list:
+   docutils-users@lists.sf.net
+
+   `Any questions?`
+
+
+.. topic:: Links
+   :class: print-block
+
+   .. target-notes:: :class: print-inline
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 48105e1ba..6f39b5021 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -3,7 +3,7 @@
 ==========================
 
 :Author: David Goodger
-:Contact: goodger@users.sourceforge.net
+:Contact: goodger@python.org
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
@@ -11,8 +11,9 @@
 .. contents::
 
 
-Introduction
-============
+--------------
+ Introduction
+--------------
 
 Once the Docutils package is unpacked, you will discover a "``tools``"
 directory containing several front ends for common Docutils
@@ -40,7 +41,7 @@ input (stdin) is used for the source as well.
 
 
 Getting Help
-------------
+============
 
 First, try the "``--help``" option each front-end tool has.
 
@@ -51,8 +52,12 @@ list.
 .. _Docutils-users: mailing-lists.html#docutils-users
 
 
-The Tools
-=========
+-----------
+ The Tools
+-----------
+
+HTML-Generating Tools
+=====================
 
 buildhtml.py
 ------------
@@ -154,6 +159,116 @@ For example, to process a PEP into HTML::
     rstpep2html.py pep-0287.txt pep-0287.html
 
 
+rst2s5.py
+---------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: S5/HTML
+
+The ``rst2s5.py`` front end reads standalone reStructuredText source
+files and produces (X)HTML output compatible with S5_, the "Simple
+Standards-based Slide Show System" by Eric Meyer.  A theme is required
+for proper rendering; several are distributed with Docutils and others
+are available; see Themes_ below.
+
+For example, to process a reStructuredText file "``slides.txt``" into
+S5/HTML::
+
+    rst2s5.py slides.txt slides.html
+
+Now open the "``slides.html``" file in your favorite browser, switch
+to full-screen mode, and enjoy the results.
+
+.. _S5: http://meyerweb.com/eric/tools/s5/
+
+
+Themes
+``````
+
+Each S5 theme consists of a directory containing several files:
+stylesheets, JavaScript, and graphics.  These are copied into a
+``ui/`` directory beside the generated HTML.  A theme is chosen
+using the "``--theme``" option (for themes that come with Docutils) or
+the "``--theme-url``" option (for themes anywhere).  For example, the
+"medium-black" theme can be specified as follows::
+
+    rst2s5.py --theme medium-black slides.txt slides.html
+
+The theme will be copied to the ``ui/medium-black`` directory.
+
+Several themes are included with Docutils:
+
+``default``
+    This is a simplified version of S5's default theme.
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 13 lines
+    :Headers: light blue, bold sans-serif text on a dark blue
+              background; titles are limited to one line
+    :Footers: small, gray, bold sans-serif text on a dark blue
+              background
+
+``small-white``
+    (Small text on a white background.)
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 15 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``small-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 15 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``medium-white``
+    :Main content: black serif text on a white background
+    :Text capacity: about 9 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``medium-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 9 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``big-white``
+    :Main content: black, bold sans-serif text on a white background
+    :Text capacity: about 5 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: not displayed
+
+``big-black``
+    :Main content: white, bold sans-serif text on a black background
+    :Text capacity: about 5 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: not displayed
+
+If a theme directory contains a file named ``__base__``, the name of
+the theme's base theme will be read from it.  Files are accumulated
+from the named theme, any base themes, and the "default" theme (which
+is the implicit base of all themes).
+
+For details, please see `Easy Slide Shows With reStructuredText &
+S5 `_.
+
+
+LaTeX-Generating Tools
+======================
+
 rst2latex.py
 ------------
 
@@ -181,6 +296,9 @@ Some limitations and difference apply:
 - Not all constructs are possible, see `Generating LaTeX with Docutils`_.
 
 
+XML-Generating Tools
+====================
+
 rst2xml.py
 ----------
 
@@ -193,6 +311,9 @@ This can be transformed with standard XML tools such as XSLT
 processors into arbitrary final forms.
 
 
+Testing/Debugging Tools
+=======================
+
 rst2pseudoxml.py
 ----------------
 
@@ -228,11 +349,12 @@ document.  Various forms output are possible:
 
 
 
-Customization
-=============
+---------------
+ Customization
+---------------
 
 Command-Line Options
---------------------
+====================
 
 Each front-end tool supports command-line options for one-off
 customization.  For persistent customization, use `configuration
@@ -248,7 +370,7 @@ corresponding configuration file entry names are listed in the
 .. _configuration file:
 
 Configuration Files
--------------------
+===================
 
 Configuration files are used for persistent customization; they can be
 set once and take effect every time you use a front-end tool.
-- 
cgit v1.2.1


From 8a891a65f7556aef612161e8d179403d6924c336 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 8 Dec 2005 05:02:38 +0000
Subject: typo fix

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4159 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index cbd874972..32165c280 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -758,7 +758,7 @@ _`theme`
 
     Default: "default".  Option: ``--theme``.
 
-_`theme-url`
+_`theme_url`
     The URL of an S5 theme directory.  The destination file (output
     HTML) will link to this theme; nothing will be copied.  Overrides
     the "theme_" setting [#override]_.
-- 
cgit v1.2.1


From c2737d5c145b4715cf6ed0b4fd9362e07d50b86b Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 9 Dec 2005 04:21:34 +0000
Subject: Converted ``docutils/writers/support/`` into individual writer
 packages; updated docs & refs.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4163 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/distributing.txt       |  2 +-
 docs/dev/hacking.txt            |  2 +-
 docs/dev/testing.txt            |  2 +-
 docs/dev/todo.txt               |  9 +++++----
 docs/howto/html-stylesheets.txt |  2 +-
 docs/peps/pep-0258.txt          | 22 +++++++++++++---------
 docs/user/config.txt            | 11 +++++------
 docs/user/slide-shows.txt       |  2 +-
 docs/user/tools.txt             | 18 +++++++++---------
 9 files changed, 37 insertions(+), 33 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/distributing.txt b/docs/dev/distributing.txt
index 498a9fa34..c81807279 100644
--- a/docs/dev/distributing.txt
+++ b/docs/dev/distributing.txt
@@ -86,7 +86,7 @@ generate HTML for all documentation files, go to the ``tools/``
 directory and run::
 
     # Place html4css1.css in base directory.
-    cp ../docutils/writers/support/html4css1.css ..
+    cp ../docutils/writers/html4css1/html4css1.css ..
     ./buildhtml.py --stylesheet-path=../html4css1.css ..
 
 Then install the following files to ``/usr/share/doc/docutils/`` (or
diff --git a/docs/dev/hacking.txt b/docs/dev/hacking.txt
index dcbc80943..d0ec9a3fb 100644
--- a/docs/dev/hacking.txt
+++ b/docs/dev/hacking.txt
@@ -166,7 +166,7 @@ For HTML output, we can test this using the ``rst2html.py`` tool::
     
     
     
-    
+    
     
     
     
    
diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 82e9ed31c..bde54116f 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -184,7 +184,7 @@ For example, ``functional/tests/some_test.py`` could read like this::
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
     # Relative to main ``test/`` directory.
-    settings_overrides['stylesheet_path'] = '../docutils/writers/support/html4css1.css'
+    settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 06ce321f1..1074daf33 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1,3 +1,4 @@
+
 ======================
  Docutils_ To Do List
 ======================
@@ -44,6 +45,9 @@ the short term) to include:
 
 * [DONE in rev. 3901] Move support files to docutils/writers/support.
 
+* [DONE in rev. 4163] Convert ``docutils/writers/support/*`` into
+  individual writer packages.
+
 * [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck
   (no longer needed because of the above change).
 
@@ -52,10 +56,7 @@ the short term) to include:
 
 * [DONE in rev. 4152] Added East-Asian double-width character support.
 
-* Merge the S5 branch.
-
-* Convert ``docutils/writers/support/*`` to individual writer
-  packages.
+* [DONE in rev. 4156] Merge the S5 branch.
 
 Anything else?
 
diff --git a/docs/howto/html-stylesheets.txt b/docs/howto/html-stylesheets.txt
index 1f61bab5d..9369f2d3c 100644
--- a/docs/howto/html-stylesheets.txt
+++ b/docs/howto/html-stylesheets.txt
@@ -13,7 +13,7 @@
 
 The look of Docutils' HTML output is customizable via a CSS
 stylesheet.  The default stylesheet is called ``html4css1.css`` and
-can be found in the ``writers/support/`` directory of the Docutils
+can be found in the ``writers/html4css1/`` directory of the Docutils
 installation.  Use the command ``rst2html.py --help`` and look at the
 description of the ``--stylesheet-path`` command-line option for the
 exact machine-specific location.
diff --git a/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt
index 47ede6c21..0d646bb82 100644
--- a/docs/peps/pep-0258.txt
+++ b/docs/peps/pep-0258.txt
@@ -416,12 +416,18 @@ Docutils Package Structure
       by name.  Class "Writer" is the base class of specific writers.
       (``docutils/writers/__init__.py``)
 
-    - Module "docutils.writers.html4css1" is a simple HyperText Markup
-      Language document tree writer for HTML 4.01 and CSS1.
+    - Package "docutils.writers.html4css1" is a simple HyperText
+      Markup Language document tree writer for HTML 4.01 and CSS1.
 
-    - Module "docutils.writers.latex2e" writes LaTeX.
+    - Package "docutils.writers.pep_html" generates HTML from
+      reStructuredText PEPs.
 
-    - Module "docutils.writers.newlatex2e" also writes LaTeX; it is a
+    - Package "docutils.writers.s5_html" generates S5/HTML slide
+      shows.
+
+    - Package "docutils.writers.latex2e" writes LaTeX.
+
+    - Package "docutils.writers.newlatex2e" also writes LaTeX; it is a
       new implementation.
 
     - Module "docutils.writers.docutils_xml" writes the internal
@@ -438,12 +444,10 @@ Docutils Package Structure
       such as DocBook), PDF, plaintext, reStructuredText, and perhaps
       others.
 
-    See `Writers`_ above.
+    Subpackages of "docutils.writers" contain modules and data files
+    (such as stylesheets) that support the individual writers.
 
-  - Package "docutils.writers.support": modules and data files that
-    support the various writers.  The names of subdirectories and
-    basenames of files immediately within the support/ directory must
-    match the corresponding writer module names.
+    See `Writers`_ above.
 
   - Package "docutils.transforms": tree transform classes.
 
diff --git a/docs/user/config.txt b/docs/user/config.txt
index 32165c280..c5ec73492 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -663,9 +663,9 @@ stylesheet_path
     setting [#override]_.  Path is adjusted relative to the output
     HTML file.  Also defined for the `LaTeX Writer`__.
 
-    Default: "html4css1.css" in the docutils/writers/support directory
-    (installed automatically; for the exact machine-specific path, use
-    the ``--help`` option).  Options: ``--stylesheet-path``.
+    Default: "html4css1.css" in the docutils/writers/html4css1/
+    directory (installed automatically; for the exact machine-specific
+    path, use the ``--help`` option).  Options: ``--stylesheet-path``.
 
     __ `stylesheet_path [latex2e writer]`_
 
@@ -694,9 +694,8 @@ before the "[pep_html writer]" section.
 
 The PEP/HTML Writer's default for the ``stylesheet_path`` setting
 differs from that of the standard HTML Writer:
-``docutils/writers/support/pep_html/pep.css`` in the installation
-directory is used.  For the exact machine-specific path, use the
-``--help`` option.
+``docutils/writers/pep_html/pep.css`` in the installation directory is
+used.  For the exact machine-specific path, use the ``--help`` option.
 
 _`no_random`
     Do not use a random banner image.  Mainly used to get predictable
diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 1fdd8398b..6a0f6655f 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -655,7 +655,7 @@ Making a Custom Theme
    * create a personal reusable theme (plugin)
    * submit the new theme to Docutils
 
-  ``docutils/writers/support/s5_html/``
+  ``docutils/writers/s5_html/themes/``
 
 .. container:: handout
 
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
index 6f39b5021..20f5a3b2f 100644
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -127,14 +127,14 @@ Stylesheets
 ``rst2html.py`` inserts into the generated HTML a cascading stylesheet
 (or a link to a stylesheet, when passing the "``--link-stylesheet``"
 option).  A stylesheet is required for proper rendering.  The default
-stylesheet (``docutils/writers/support/html4css1.css``, located in the
-installation directory) is provided for basic use.  To use a different
-stylesheet, you must specify the stylesheet's location with a
-"``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a local
-file) command-line option, or with `configuration file`_ settings
-(e.g. ``./docutils.conf`` or ``~/.docutils``).  To experiment with
-styles, please see the `guide to writing HTML (CSS) stylesheets for
-Docutils`__.
+stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
+the installation directory) is provided for basic use.  To use a
+different stylesheet, you must specify the stylesheet's location with
+a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a
+local file) command-line option, or with `configuration file`_
+settings (e.g. ``./docutils.conf`` or ``~/.docutils``).  To experiment
+with styles, please see the `guide to writing HTML (CSS) stylesheets
+for Docutils`__.
 
 __ ../howto/html-stylesheets.html
 
@@ -150,7 +150,7 @@ rstpep2html.py
 reStructuredText) and produces HTML.  It requires a template file and
 a stylesheet.  By default, it makes use of a "``pep-html-template``"
 file and the "``pep.css``" stylesheet (both in the
-``docutils/writers/support/`` directory), but these can be overridden
+``docutils/writers/pep_html/`` directory), but these can be overridden
 by command-line options or configuration files.
 
 For example, to process a PEP into HTML::
-- 
cgit v1.2.1


From 80011753fd1709a99e6c165a7ca5a8839ac526b7 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 9 Dec 2005 04:53:19 +0000
Subject: for generating slide shows (temporary?)

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile | 9 +++++++++
 1 file changed, 9 insertions(+)
 create mode 100644 docs/user/Makefile

(limited to 'docs')

diff --git a/docs/user/Makefile b/docs/user/Makefile
new file mode 100644
index 000000000..167cea097
--- /dev/null
+++ b/docs/user/Makefile
@@ -0,0 +1,9 @@
+all: slide-shows.html slide-shows-alt.html
+
+slide-shows.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.html --config ../../docutils.conf \
+		--link-stylesheet
+
+slide-shows-alt.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows-alt.html --config ../../docutils.conf \
+		--theme small-black --link-stylesheet
-- 
cgit v1.2.1


From 36e9cd14219fd41732160e7690d524ede0757d30 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Fri, 9 Dec 2005 04:55:20 +0000
Subject: refined the list

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4166 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index e25d66e07..16d918379 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -79,12 +79,15 @@ top level of the Docutils project directory.
 Docutils-general:
 
 * `Docutils Front-End Tools `__
-* `Easy Slide Shows With reStructuredText & S5 `__
 * `Docutils Configuration Files `__
-* `Docutils LaTeX Writer `__
 * `Docutils Mailing Lists `__
 * `Docutils Link List `__
 
+Writer-specific:
+
+* `Easy Slide Shows With reStructuredText & S5 `__
+* `Docutils LaTeX Writer `__
+
 `reStructuredText `_:
 
 * `A ReStructuredText Primer (HTML) `__ (or
-- 
cgit v1.2.1


From aca97da13d1057d7ef64f64911c54742ba8342d3 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 21:52:20 +0000
Subject: automate S5/HTML rendering

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4170 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile b/docs/user/Makefile
index 167cea097..7f2517ba1 100644
--- a/docs/user/Makefile
+++ b/docs/user/Makefile
@@ -1,9 +1,14 @@
-all: slide-shows.html slide-shows-alt.html
+all: slide-shows.s5.html slide-shows-alt.s5.html
 
-slide-shows.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows.html --config ../../docutils.conf \
+slide-shows.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.html \
+		--config ../../docutils.conf \
+		--overwrite-theme-files \
 		--link-stylesheet
 
-slide-shows-alt.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.html --config ../../docutils.conf \
-		--theme small-black --link-stylesheet
+slide-shows-alt.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows-alt.html \
+		--config ../../docutils.conf \
+		--theme small-black \
+		--overwrite-theme-files \
+		--link-stylesheet
-- 
cgit v1.2.1


From bcfb7c5ff1d8302e76cdcb570bf9c03bda9a1c8f Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 21:54:57 +0000
Subject: clarifications & minor fixes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4171 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 90 +++++++++++++++++++++++++++++++++--------------
 1 file changed, 63 insertions(+), 27 deletions(-)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 6a0f6655f..21f97979f 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -1,15 +1,18 @@
 .. include:: 
 
-=============================================
- Easy Slide Shows With reStructuredText & S5
-=============================================
+=================================
+ Easy Slide Shows With reST & S5
+=================================
 
-:Authors:   David Goodger & Chris Liechti
-:Date:      $Date$
+:Authors: David Goodger & Chris Liechti
+:Date:    $Date$
 
 .. This document has been placed in the public domain.
 
-.. class:: handout
+.. container:: handout
+
+   How to create quick, good-looking presentation slide shows with
+   Docutils_/reStructuredText_ and S5_.
 
    This document serves both as a user manual and as a usage example
    of the s5_html.py writer and the rst2s5.py front end.
@@ -17,21 +20,20 @@
 .. contents::
    :class: handout
 
-How to create quick, good-looking presentation slide shows with
-Docutils_/reStructuredText_ and S5_.
+.. class:: tiny
 
-.. class:: small
+* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
 
-* Use the arrow keys to navigate.
+* Best viewed in Firefox, Safari, Konqueror.  Click the "|mode|"
+  button to switch between presentation & handout/outline modes.  Hit
+  the "C" key to display the navigation controls, or mouse over the
+  lower right-hand corner.
 
-* Click the "|mode|" button to switch between presentation &
-  handout/outline modes.
+* Functionality is limited in Opera.  Switch to full-screen mode (F11
+  key) to activate Opera Show.
 
 .. container:: handout
 
-   In presentation mode, mouse over to the lower right-hand corner to
-   display the controls.
-
    The first slide of a presentation consists of all visible text up
    to the first section title.  The document title is also added to
    the footer of all slides.
@@ -47,6 +49,7 @@ Docutils_/reStructuredText_ and S5_.
 .. _S5: http://meyerweb.com/eric/tools/s5/
 .. |bullet| unicode:: U+02022
 .. |mode| unicode:: U+00D8 .. capital o with stroke
+
 .. footer:: Location |bullet| Date
 
 
@@ -80,13 +83,20 @@ Introduction
 
   Each first-level section is converted into a single slide.
 
-* (X)HTML output
+* XHTML output
 
-  .. class:: handout
+  .. container:: handout
+
+     Presentations can be viewed using most modern graphical web
+     browsers.  The browser must support CSS, JavaScript, and XHTML.
+     S5 even works with IE!
 
-  Presentations can be viewed using any modern graphical web browser.
-  The browser must support CSS, JavaScript, and XHTML.  S5 even works
-  with IE!
+     S5 was designed to add the functionality of the `Opera Show`_
+     standard (without Opera Show's limitations) to non-Opera
+     browsers.  Unfortunately, most of S5's CSS and JavaScript
+     extensions don't function in the Opera browser.
+
+  .. _Opera Show: http://www.opera.com/support/tutorials/operashow/
 
 * Themes
 
@@ -155,7 +165,7 @@ Features (1)
 .. container:: handout
 
    The S5/HTML Writer supports all the standard Docutils HTML
-   features.
+   features.  S5 has been released to the Public Domain.
 
 S5-specific features:
 
@@ -178,12 +188,25 @@ S5-specific features:
 
          .. footer:: Location - Date
 
+     There is also a progress indicator (slide counter) in the footer
+     that can be enabled.  It's disabled by default.
+
 * Incremental display.
 
   .. class:: handout
 
   An "incremental" class can be assigned to lists and other elements
-  to get one-item-at-a-time behavior (like this list).
+  to get one-item-at-a-time behavior (like this list).  Incremental
+  display does not work in the Opera browser.
+
+* Text auto-scaling.
+
+  .. class:: handout
+
+  The text size adjusts relative to the size of your browser window
+  automatically.  You may need to reload the document after resizing
+  the window.  The browser and platform affect the font used; be sure
+  to test the slide show on the presentation system.
 
 
 Features (2): Handouts
@@ -219,7 +242,8 @@ Features (2): Handouts
 
          .. class:: handout
 
-         This paragraph will get a ``class="handout"`` attribute.
+         This paragraph will get a
+         ``class="handout"`` attribute.
 
          This paragraph will not be affected.
 
@@ -227,8 +251,8 @@ Features (2): Handouts
 
          .. class:: handout
 
-            These paragraphs are the content of the "class" directive.
-            And as such...
+            These paragraphs are the content
+            of the "class" directive.  And as such...
 
             Both paragraphs will *individually* receive
             ``class="handout"`` attributes.
@@ -910,7 +934,7 @@ Chained Presentations
 
 From one theme, `to another...`__
 
-__ slide-shows-alt.html#chained-presentations-2
+__ slide-shows-alt.s5.html#chained-presentations-2
 
 
 Chained Presentations (2)
@@ -918,7 +942,7 @@ Chained Presentations (2)
 
 ... and `back again...`__
 
-__ slide-shows.html#chained-presentations-3
+__ slide-shows.s5.html#chained-presentations-3
 
 
 Chained Presentations (3)
@@ -942,6 +966,18 @@ Chained Presentations (3)
    right order.  Closing one tab will reveal the next.
 
 
+Useful Extensions For Firefox
+=============================
+
+* `Autohide`__
+
+  __ http://www.krickelkrackel.de/autohide/autohide.htm
+
+* `Web Developer`__
+
+  __ http://chrispederick.com/work/webdeveloper/
+
+
 To Do
 =====
 
-- 
cgit v1.2.1


From 595cd14a9cfd3a0f7e525e1eacdbe8a85e3b5230 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 22:20:33 +0000
Subject: fixed bugs in script; narrow applicability

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4174 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile          | 14 --------------
 docs/user/Makefile.docutils | 14 ++++++++++++++
 2 files changed, 14 insertions(+), 14 deletions(-)
 delete mode 100644 docs/user/Makefile
 create mode 100644 docs/user/Makefile.docutils

(limited to 'docs')

diff --git a/docs/user/Makefile b/docs/user/Makefile
deleted file mode 100644
index 7f2517ba1..000000000
--- a/docs/user/Makefile
+++ /dev/null
@@ -1,14 +0,0 @@
-all: slide-shows.s5.html slide-shows-alt.s5.html
-
-slide-shows.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows.html \
-		--config ../../docutils.conf \
-		--overwrite-theme-files \
-		--link-stylesheet
-
-slide-shows-alt.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.html \
-		--config ../../docutils.conf \
-		--theme small-black \
-		--overwrite-theme-files \
-		--link-stylesheet
diff --git a/docs/user/Makefile.docutils b/docs/user/Makefile.docutils
new file mode 100644
index 000000000..7f2517ba1
--- /dev/null
+++ b/docs/user/Makefile.docutils
@@ -0,0 +1,14 @@
+all: slide-shows.s5.html slide-shows-alt.s5.html
+
+slide-shows.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.html \
+		--config ../../docutils.conf \
+		--overwrite-theme-files \
+		--link-stylesheet
+
+slide-shows-alt.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows-alt.html \
+		--config ../../docutils.conf \
+		--theme small-black \
+		--overwrite-theme-files \
+		--link-stylesheet
-- 
cgit v1.2.1


From 91c076647000a3078b8b5bc3c176a515e5e1d2ba Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 22:23:54 +0000
Subject: further narrowed applicability

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4175 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils        | 14 --------------
 docs/user/Makefile.docutils-update | 14 ++++++++++++++
 2 files changed, 14 insertions(+), 14 deletions(-)
 delete mode 100644 docs/user/Makefile.docutils
 create mode 100644 docs/user/Makefile.docutils-update

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils b/docs/user/Makefile.docutils
deleted file mode 100644
index 7f2517ba1..000000000
--- a/docs/user/Makefile.docutils
+++ /dev/null
@@ -1,14 +0,0 @@
-all: slide-shows.s5.html slide-shows-alt.s5.html
-
-slide-shows.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows.html \
-		--config ../../docutils.conf \
-		--overwrite-theme-files \
-		--link-stylesheet
-
-slide-shows-alt.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.html \
-		--config ../../docutils.conf \
-		--theme small-black \
-		--overwrite-theme-files \
-		--link-stylesheet
diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
new file mode 100644
index 000000000..7f2517ba1
--- /dev/null
+++ b/docs/user/Makefile.docutils-update
@@ -0,0 +1,14 @@
+all: slide-shows.s5.html slide-shows-alt.s5.html
+
+slide-shows.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.html \
+		--config ../../docutils.conf \
+		--overwrite-theme-files \
+		--link-stylesheet
+
+slide-shows-alt.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows-alt.html \
+		--config ../../docutils.conf \
+		--theme small-black \
+		--overwrite-theme-files \
+		--link-stylesheet
-- 
cgit v1.2.1


From ae958cfe8759ddbf00122710ac9e97eea401e34e Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 22:29:49 +0000
Subject: typo

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4176 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 7f2517ba1..774f3a152 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -1,13 +1,13 @@
 all: slide-shows.s5.html slide-shows-alt.s5.html
 
 slide-shows.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows.html \
+	rst2s5.py slide-shows.txt slide-shows.s5.html \
 		--config ../../docutils.conf \
 		--overwrite-theme-files \
 		--link-stylesheet
 
 slide-shows-alt.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.html \
+	rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
 		--config ../../docutils.conf \
 		--theme small-black \
 		--overwrite-theme-files \
-- 
cgit v1.2.1


From 29ca63b742c360c26f8a06862504a546a7ffedb7 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 22:55:09 +0000
Subject: added links to slide show versions

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4178 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 21f97979f..3622bb672 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -17,6 +17,10 @@
    This document serves both as a user manual and as a usage example
    of the s5_html.py writer and the rst2s5.py front end.
 
+   To view this document as a slide show see
+   http://docutils.sf.net/docs/user/slide-shows.s5.html (absolute URL;
+   or `local `__).
+
 .. contents::
    :class: handout
 
-- 
cgit v1.2.1


From 47e5feb6957544d209332fa2a297dc8687474ff5 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Sun, 11 Dec 2005 23:01:02 +0000
Subject: corrected path to config file

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4180 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 774f3a152..1a097ddc9 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -2,13 +2,13 @@ all: slide-shows.s5.html slide-shows-alt.s5.html
 
 slide-shows.s5.html: slide-shows.txt
 	rst2s5.py slide-shows.txt slide-shows.s5.html \
-		--config ../../docutils.conf \
+		--config ../../tools/docutils.conf \
 		--overwrite-theme-files \
 		--link-stylesheet
 
 slide-shows-alt.s5.html: slide-shows.txt
 	rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
-		--config ../../docutils.conf \
+		--config ../../tools/docutils.conf \
 		--theme small-black \
 		--overwrite-theme-files \
 		--link-stylesheet
-- 
cgit v1.2.1


From 2bfa216fe93f6d7c3d25a41af9af32cb08afb990 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 12 Dec 2005 00:20:23 +0000
Subject: silence "make" when there is nothing to be done, but report built
 files

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4182 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 1a097ddc9..597887916 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -1,13 +1,15 @@
 all: slide-shows.s5.html slide-shows-alt.s5.html
 
 slide-shows.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows.s5.html \
+	@echo docs/user/slide-shows.s5.html
+	@rst2s5.py slide-shows.txt slide-shows.s5.html \
 		--config ../../tools/docutils.conf \
 		--overwrite-theme-files \
 		--link-stylesheet
 
 slide-shows-alt.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
+	@echo docs/user/slide-shows-alt.s5.html
+	@rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
 		--config ../../tools/docutils.conf \
 		--theme small-black \
 		--overwrite-theme-files \
-- 
cgit v1.2.1


From e329a521a11f62212d4504d25cb1a3c5c76dfc18 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Mon, 12 Dec 2005 04:12:02 +0000
Subject: Added the universal.StripComments transform, the "strip_comments"
 setting, and the --strip-comments/--leave-comments options.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4183 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt       | 7 -------
 docs/ref/transforms.txt | 2 ++
 docs/user/config.txt    | 6 ++++++
 3 files changed, 8 insertions(+), 7 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 1074daf33..dbe28d2ca 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1,4 +1,3 @@
-
 ======================
  Docutils_ To Do List
 ======================
@@ -116,12 +115,6 @@ General
 * Change the docutils-update script (in sandbox/infrastructure), to
   support arbitrary branch snapshots.
 
-* Add a --strip-comments command-line option (& strip_comments runtime
-  setting), declared in docutils/frontend.py, and implemented as a
-  transform.  This feature isn't specific to rst2html.py, or to the
-  HTML Writer, or to the reST parser; it applies to Docutils as a
-  whole.  See .
-
 * Add a generic "container" element, equivalent to "inline", to which
   a "class" attribute can be attached.  Will require a reST directive
   also.
diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt
index 0595175b4..54446f8dd 100644
--- a/docs/ref/transforms.txt
+++ b/docs/ref/transforms.txt
@@ -63,6 +63,8 @@ parts.SectNum                   "sectnum" (d/p)               710
 parts.Contents                  "contents" (d/p),             720
                                 peps.Contents (t/p)
 
+universal.StripComments         Reader (r)                    740
+
 peps.PEPZero                    peps.Headers (t/p)            760
 
 components.Filter               "meta" (d/p)                  780
diff --git a/docs/user/config.txt b/docs/user/config.txt
index c5ec73492..a3b79b510 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -369,6 +369,12 @@ _`strict_visitor`
     Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
     for development use only).
 
+_`strip_comments`
+    Enable the removal of comment elements from the document tree.
+
+    Default: disabled (None).  Options: ``--strip-comment``,
+    ``--leave-comments``.
+
 _`title`
     The document title as metadata, which does not become part of the
     document body.  It overrides a document-supplied title.  For
-- 
cgit v1.2.1


From 5417696256226604baa27c74ef08bece4b86e207 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 13 Dec 2005 00:30:28 +0000
Subject: tweaked & expanded

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4189 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 113 ++++++++++++++++++++++++++++------------------
 1 file changed, 70 insertions(+), 43 deletions(-)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 3622bb672..f9f25ab26 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -216,8 +216,6 @@ S5-specific features:
 Features (2): Handouts
 ======================
 
-````
-
 .. container:: handout
 
    The contents of any element with a "class" attribute value of
@@ -270,7 +268,7 @@ Features (2): Handouts
      Arbitrary handout blocks can be created using the ``container``
      directive.  The content is treated as one.
 
-* Add a "class" option to certain directives::
+* Use the "class" option of directives that support it::
 
       .. topic:: Extra Material For Handouts
          :class: handout
@@ -433,11 +431,11 @@ Examples (2): Incremental Text
       This second paragraph is displayed together with the previous
       one by grouping them with the "container" directive.
 
-| `We can also display` `one` `word` `at` `a` `time,`
-| `or a phrase` `at a time,`
-| `or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
-|
-| `(But the markup ain't pretty.)`
+`We can also display` `one` `word` `at` `a` `time,`
+`or a phrase` `at a time,`
+`or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
+
+`(But the markup ain't pretty.)`
 
 
 Examples (3): Incr. Graphics
@@ -448,14 +446,17 @@ Let's play... Rock, Scissors, Paper
 .. container:: animation
 
    .. image:: images/rsp-empty.png
+      :class: hidden slide-display
 
-   .. class:: incremental
+   .. class:: incremental hidden slide-display
 
       .. image:: images/rsp-objects.png
       .. image:: images/rsp-cuts.png
       .. image:: images/rsp-covers.png
       .. image:: images/rsp-breaks.png
-      .. image:: images/rsp-all.png
+
+   .. image:: images/rsp-all.png
+      :class: incremental
 
 
 Themes
@@ -561,8 +562,7 @@ Example Themes: Large Text
 .. class:: handout
 
    The "big-white" and "big-black" themes feature very large, bold
-   text, with no footers.  Only five short lines of large text fits
-   per slide.
+   text, with no footers.  Only five short lines fit in a slide.
 
 .. list-table::
    :class: borderless
@@ -752,27 +752,26 @@ The "incremental" interpreted text role is also supported:
 Classes: Incremental (3)
 ========================
 
-.. class:: handout
-
-   The "animation" class is provided to support incremental graphics.
-   This is how the example earlier was done:
+.. class:: small
 
 ::
 
     .. container:: animation
 
-       .. image:: images/rsp-empty.png
+       .. image:: images/empty.png
+          :class: hidden slide-display
 
-       .. class:: incremental
+       .. class:: incremental hidden slide-display
 
-          .. image:: images/rsp-objects.png
-          .. image:: images/rsp-cuts.png
-          .. image:: images/rsp-covers.png
-          .. image:: images/rsp-breaks.png
-          .. image:: images/rsp-all.png
+          .. image:: images/1.png
+          .. image:: images/2.png
 
-.. admonition:: Caveat
-   :class: handout
+       .. image:: images/3.png
+          :class: incremental
+
+.. container:: handout
+
+   This is how the example works.
 
    The animation effects are caused by placing successive images at
    the same location, laying each image over the last.  For best
@@ -782,8 +781,30 @@ Classes: Incremental (3)
 
    Absolute positioning is used, which means that the images take up
    no space in the flow.  If you want text to follow the images, you
-   have to specify the image sizes.  Otherwise, the images and any
-   following text will overlap.
+   have to specify the total size of the container via a style.
+   Otherwise, the images and any following text will overlap.
+
+   These class values do the work:
+
+   animation
+       This wraps the container with styles that position the images
+       absolutely, overlaying them over each other.  Only useful on a
+       container.
+
+   hidden
+       Unless overridden (by "slide-display", for example), these
+       elements will not be displayed.  Only the last image will be
+       displayed in handout mode, when print, or when processed to
+       ordinary HTML, because it does *not* carry a "hidden" class.
+
+   slide-display
+       In conjunction with "hidden", these elements will only appear
+       on the slide, preventing clutter in the handout.
+
+   incremental
+       The second and subsequent images will appear one at a time.
+       The first image will already be present when the slide is
+       displayed, because it does *not* carry an "incremental" class.
 
 
 Classes: Text Size
@@ -880,23 +901,18 @@ Classes: Print-Only
 
 .. class:: handout
 
-   Two classes are provided that only display their contents in
-   hardcopy.  The "print-block" class applies to block-level elements
-   (like paragraphs, lists, and topics).  The "print-inline" class
-   applies to text within paragraphs.
+   Elements with ``class="print"`` attributes display their contents
+   when printed, overriding ``class="hidden"``.
 
 .. class:: incremental
 
-   | "print-block" for block elements
-   | "print-inline" for inline text
-
    Example: the "target-notes" directive::
 
        .. topic:: Links
-          :class: print-block
+          :class: hidden print
 
           .. target-notes::
-             :class: print-inline
+             :class: hidden print
 
 .. container:: handout
 
@@ -906,11 +922,12 @@ Classes: Print-Only
    content.  Footnote references are placed after each hyperlink
    reference.
 
-   The "topic" directive is given a "class" attribute with value
-   "print-block"; the entire topic will only be displayed when
-   printed.  The "target-notes" assigns a "class" attribute with value
-   "print-inline" to each of the footnote references it inserts
-   throughout the text; they will only show up when printed.
+   The "topic" directive is given a "class" attribute with values
+   "hidden" and "print", so the entire topic will only be displayed
+   when printed.  The "target-notes" directive also assigns a "class"
+   attributes with values "hidden" and "print" to each of the footnote
+   references it inserts throughout the text; they will only show up
+   when printed.
 
 .. class:: incremental
 
@@ -975,10 +992,20 @@ Useful Extensions For Firefox
 
 * `Autohide`__
 
+  .. class:: handout
+
+  Automatically hides toolbars in full-screen mode.
+
   __ http://www.krickelkrackel.de/autohide/autohide.htm
 
 * `Web Developer`__
 
+  .. class:: handout
+
+  Adds a context submenu and a toolbar with a lot of useful
+  functionality, including the viewing and live editing of
+  stylesheets, and sizing the browser window.
+
   __ http://chrispederick.com/work/webdeveloper/
 
 
@@ -1019,6 +1046,6 @@ That's All, Folks!
 
 
 .. topic:: Links
-   :class: print-block
+   :class: hidden print
 
-   .. target-notes:: :class: print-inline
+   .. target-notes:: :class: hidden print
-- 
cgit v1.2.1


From f7f89ab7334bc2ecdcc7fa95c0b5c8bf213c9cc0 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 13 Dec 2005 00:30:45 +0000
Subject: prevent extra footer content

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4190 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 597887916..2d6aa3ce8 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -5,7 +5,8 @@ slide-shows.s5.html: slide-shows.txt
 	@rst2s5.py slide-shows.txt slide-shows.s5.html \
 		--config ../../tools/docutils.conf \
 		--overwrite-theme-files \
-		--link-stylesheet
+		--link-stylesheet \
+		--no-generator --no-datestamp --no-source-link
 
 slide-shows-alt.s5.html: slide-shows.txt
 	@echo docs/user/slide-shows-alt.s5.html
@@ -13,4 +14,5 @@ slide-shows-alt.s5.html: slide-shows.txt
 		--config ../../tools/docutils.conf \
 		--theme small-black \
 		--overwrite-theme-files \
-		--link-stylesheet
+		--link-stylesheet \
+		--no-generator --no-datestamp --no-source-link
-- 
cgit v1.2.1


From 695864cadad3ab95e2d84555c11f52478b3c6398 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Tue, 13 Dec 2005 02:22:14 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4193 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index f9f25ab26..67ad8ba4f 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -18,8 +18,8 @@
    of the s5_html.py writer and the rst2s5.py front end.
 
    To view this document as a slide show see
-   http://docutils.sf.net/docs/user/slide-shows.s5.html (absolute URL;
-   or `local `__).
+   http://docutils.sf.net/docs/user/slide-shows.s5.html (or `your
+   local copy `__).
 
 .. contents::
    :class: handout
@@ -28,7 +28,11 @@
 
 * Use the space bar to advance, Page Up/Down & arrow keys to navigate.
 
-* Best viewed in Firefox, Safari, Konqueror.  Click the "|mode|"
+* S5 themes are designed for full-screen display areas with a 4:3
+  aspect ratio.  If the slide text doesn't fit in your browser window,
+  try decreasing the text size.
+
+* Best viewed in Firefox, Safari, and Konqueror.  Click the "|mode|"
   button to switch between presentation & handout/outline modes.  Hit
   the "C" key to display the navigation controls, or mouse over the
   lower right-hand corner.
-- 
cgit v1.2.1


From 4df5283616746e894e33ad8d8b58d3a318fce2f3 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Tue, 13 Dec 2005 22:38:28 +0000
Subject: added RELEASE-NOTES.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4204 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index 16d918379..08a11e7a3 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -59,7 +59,8 @@ top level of the Docutils project directory.
            question or issue, there's a good chance it's already
            answered here.
 :BUGS.txt_: A list of known bugs, and how to report a bug.
-:HISTORY.txt_: Change history log.
+:RELEASE-NOTES.txt_: List of major changes for each Docutils release.
+:HISTORY.txt_: Detailed change history log.
 :THANKS.txt_: Acknowledgements.
 
 .. _README.txt: ../README.html
@@ -67,6 +68,7 @@ top level of the Docutils project directory.
 .. _COPYING.txt: ../COPYING.html
 .. _Docutils FAQ:
 .. _FAQ.txt: ../FAQ.html
+.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html
 .. _HISTORY.txt: ../HISTORY.html
 .. _THANKS.txt: ../THANKS.html
 
-- 
cgit v1.2.1


From 567f1ce60b8466e38a028a04f92bec99af71a490 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 14 Dec 2005 02:10:34 +0000
Subject: removed excess instructions from the option help, & tweak

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4207 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/user/config.txt b/docs/user/config.txt
index a3b79b510..0413dd5be 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -590,7 +590,7 @@ _`cloak_email_addresses`
 
 _`compact_lists`
     Remove extra vertical whitespace between items of bullet lists and
-    enumerated lists, when list items are "simple" (i.e., all items
+    enumerated lists, when list items are all "simple" (i.e., items
     each contain one paragraph and/or one "simple" sublist only).  The
     behaviour can be specified directly via "class" attributes (values
     "compact" and "open") in the document.
-- 
cgit v1.2.1


From 0b718c86ce872823b2c22f1024f8df83bff797a7 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 14 Dec 2005 02:12:38 +0000
Subject: clarification

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4209 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index dbe28d2ca..f732e8030 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -763,8 +763,8 @@ __ rst/alternatives.html#or-not-to-do
 * Add test for ":figwidth: image" option of "figure" directive.  (Test
   code needs to check if PIL is available on the system.)
 
-* Add support for CJK double-width whitespace & punctuation
-  characters?
+* Add support for CJK double-width whitespace (indentation) &
+  punctuation characters (markup; e.g. double-width "*", "-", "+")?
 
 * Add motivation sections for constructs in spec.
 
-- 
cgit v1.2.1


From b4b456c4c3d9694d96f039d15b4ea63a809b5fa1 Mon Sep 17 00:00:00 2001
From: wiemann 
Date: Wed, 14 Dec 2005 13:45:04 +0000
Subject: removed echo, made "make" echo the rst2s5.py command

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4210 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 2d6aa3ce8..0e1dd35ab 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -1,16 +1,14 @@
 all: slide-shows.s5.html slide-shows-alt.s5.html
 
 slide-shows.s5.html: slide-shows.txt
-	@echo docs/user/slide-shows.s5.html
-	@rst2s5.py slide-shows.txt slide-shows.s5.html \
+	rst2s5.py slide-shows.txt slide-shows.s5.html \
 		--config ../../tools/docutils.conf \
 		--overwrite-theme-files \
 		--link-stylesheet \
 		--no-generator --no-datestamp --no-source-link
 
 slide-shows-alt.s5.html: slide-shows.txt
-	@echo docs/user/slide-shows-alt.s5.html
-	@rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
+	rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
 		--config ../../tools/docutils.conf \
 		--theme small-black \
 		--overwrite-theme-files \
-- 
cgit v1.2.1


From a241c06056bb47592dc8ebc10d85ecb16cfbb722 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 14 Dec 2005 17:37:07 +0000
Subject: tweak

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4215 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/index.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/index.txt b/docs/index.txt
index 08a11e7a3..18761f312 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -59,7 +59,7 @@ top level of the Docutils project directory.
            question or issue, there's a good chance it's already
            answered here.
 :BUGS.txt_: A list of known bugs, and how to report a bug.
-:RELEASE-NOTES.txt_: List of major changes for each Docutils release.
+:RELEASE-NOTES.txt_: Summary of the major changes in recent releases.
 :HISTORY.txt_: Detailed change history log.
 :THANKS.txt_: Acknowledgements.
 
-- 
cgit v1.2.1


From dc616707d25625af41a0efc922f49ebdffc526f9 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 15 Dec 2005 23:47:19 +0000
Subject: tweaks

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4221 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 67ad8ba4f..13b94e343 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -26,13 +26,13 @@
 
 .. class:: tiny
 
-* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
-
 * S5 themes are designed for full-screen display areas with a 4:3
   aspect ratio.  If the slide text doesn't fit in your browser window,
   try decreasing the text size.
 
-* Best viewed in Firefox, Safari, and Konqueror.  Click the "|mode|"
+* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
+
+* Best viewed in Firefox_, Safari, and Konqueror.  Click the "|mode|"
   button to switch between presentation & handout/outline modes.  Hit
   the "C" key to display the navigation controls, or mouse over the
   lower right-hand corner.
@@ -40,6 +40,8 @@
 * Functionality is limited in Opera.  Switch to full-screen mode (F11
   key) to activate Opera Show.
 
+* S5 works in Internet Explorer, but it may look ugly.
+
 .. container:: handout
 
    The first slide of a presentation consists of all visible text up
@@ -55,6 +57,7 @@
 .. _Docutils: http://docutils.sourceforge.net/
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _S5: http://meyerweb.com/eric/tools/s5/
+.. _Firefox: http://www.mozilla.com/firefox/
 .. |bullet| unicode:: U+02022
 .. |mode| unicode:: U+00D8 .. capital o with stroke
 
@@ -354,12 +357,11 @@ Generating a Slide Show (1)
 .. class:: incremental
 
 1. Open a console (terminal, command shell) and go to the folder
-   containing your file, ``presentation.txt``.
+   containing your file, ``slides.txt``.
 
 2. Run the command::
 
-       rst2s5.py presentation.txt \
-                 presentation.html
+       rst2s5.py slides.txt slides.html
 
 3. Specify an S5 theme with the ``--theme`` option.
 
@@ -384,7 +386,7 @@ Generating a Slide Show (2)
    stylesheet instead of embedding, you must include a copy (suggested
    location: in the ``ui/`` directory).
 
-5. Open ``presentation.html`` in a web browser.
+5. Open ``slides.html`` in a web browser.
 
 6. Expand the browser window to full-screen mode, and speak.
 
@@ -495,7 +497,7 @@ Themes
 
      Example::
 
-         rst2s5 --theme big-black presentation.txt presentation.html
+         rst2s5 --theme big-black slides.txt slides.html
 
      The default theme is "default".
 
-- 
cgit v1.2.1


From 7f25bde833b6535ca317143446ea90d342fea63d Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 21 Dec 2005 02:01:15 +0000
Subject: removed instructions for chained presentations; too flakey

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4227 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/slide-shows.txt | 53 -----------------------------------------------
 1 file changed, 53 deletions(-)

(limited to 'docs')

diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
index 13b94e343..6732f4f44 100644
--- a/docs/user/slide-shows.txt
+++ b/docs/user/slide-shows.txt
@@ -940,59 +940,6 @@ Classes: Print-Only
    Other uses may require "``.. include:: ``".
 
 
-Chained Presentations
-=====================
-
-.. class:: handout
-
-   Presentation slide shows can be chained together.  This is useful
-   for including all or part of one presentation in another, and for
-   changing themes.  Slide numbers are not carried over, unless you
-   fake a continuous multi-themed presentation:
-
-   1. Generate slide show HTML files with two different names from
-      different themes but from the same source text.
-
-   2. Include a link to the **next** slide, in the **second** theme's
-      file.
-
-   3. To return to the first theme, include a link to the **next**
-      slide, in the **first** theme.
-
-From one theme, `to another...`__
-
-__ slide-shows-alt.s5.html#chained-presentations-2
-
-
-Chained Presentations (2)
-=========================
-
-... and `back again...`__
-
-__ slide-shows.s5.html#chained-presentations-3
-
-
-Chained Presentations (3)
-=========================
-
-... back to the first theme.
-
-.. container:: handout
-
-   Now we're back where we started from, back in the first theme, but
-   two slides further on.
-
-   In this way, any number of themes can be chained together.
-
-`Or you could cheat.`
-
-.. container:: handout
-
-   Just prepare the browser in advance, with all the slide show files
-   set up at the right slide in separate tabs in your browser, in the
-   right order.  Closing one tab will reveal the next.
-
-
 Useful Extensions For Firefox
 =============================
 
-- 
cgit v1.2.1


From fec0a36bc5fb049147de33e97a2701b785011599 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 22 Dec 2005 23:46:04 +0000
Subject: added "Directives for Substitution Definitions" section, including
 docs for new "date" directive

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4228 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/directives.txt | 232 +++++++++++++++++++++++++-------------------
 1 file changed, 134 insertions(+), 98 deletions(-)

(limited to 'docs')

diff --git a/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt
index 12959e86d..af88a3d4e 100644
--- a/docs/ref/rst/directives.txt
+++ b/docs/ref/rst/directives.txt
@@ -1177,6 +1177,140 @@ Imagemap
 Non-standard element: imagemap.
 
 
+-----------------------------------------
+ Directives for Substitution Definitions
+-----------------------------------------
+
+The directives in this section may only be used in substitution
+definitions.  They may not be used directly, in standalone context.
+The `image`_ directive may be used both in substitution definitions
+and in the standalone context.
+
+
+.. _replace:
+
+Replacement Text
+================
+
+:Directive Type: "replace"
+:Doctree Element: Text & inline elements
+:Directive Arguments: None.
+:Directive Options: None.
+:Directive Content: A single paragraph; may contain inline markup.
+
+The "replace" directive is used to indicate replacement text for a
+substitution reference.  It may be used within substitution
+definitions only.  For example, this directive can be used to expand
+abbreviations::
+
+    .. |reST| replace:: reStructuredText
+
+    Yes, |reST| is a long word, so I can't blame anyone for wanting to
+    abbreviate it.
+
+As reStructuredText doesn't support nested inline markup, the only way
+to create a reference with styled text is to use substitutions with
+the "replace" directive::
+
+    I recommend you try |Python|_.
+
+    .. |Python| replace:: Python, *the* best language around
+    .. _Python: http://www.python.org/
+
+
+.. _unicode:
+
+Unicode Character Codes
+=======================
+
+:Directive Type: "unicode"
+:Doctree Element: Text
+:Directive Arguments: One or more, required (Unicode character codes,
+                      optional text, and comments).
+:Directive Options: Possible.
+:Directive Content: None.
+
+The "unicode" directive converts Unicode character codes (numerical
+values) to characters, and may be used in substitution definitions
+only.
+
+The arguments, separated by spaces, can be:
+
+* **character codes** as
+
+  - decimal numbers or
+
+  - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
+    ``u``, or ``\u`` or as XML-style hexadecimal character entities,
+    e.g. ``ᨫ``
+
+* **text**, which is used as-is.
+
+Text following " .. " is a comment and is ignored.  The spaces between
+the arguments are ignored and thus do not appear in the output.
+Hexadecimal codes are case-insensitive.
+
+For example, the following text::
+
+    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
+    all rights reserved.
+
+    .. |copy| unicode:: 0xA9 .. copyright sign
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
+
+results in:
+
+    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
+    all rights reserved.
+
+    .. |copy| unicode:: 0xA9 .. copyright sign
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
+
+The following options are recognized:
+
+``ltrim`` : flag
+    Whitespace to the left of the substitution reference is removed.
+
+``rtrim`` : flag
+    Whitespace to the right of the substitution reference is removed.
+
+``trim`` : flag
+    Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
+    of the substitution reference is removed.
+
+
+Date
+====
+
+:Directive Type: "date"
+:Doctree Element: Text
+:Directive Arguments: One, optional (date format).
+:Directive Options: None.
+:Directive Content: None.
+
+The "date" directive generates the current local date and inserts it
+into the document as text.  This directive may be used in substitution
+definitions only.
+
+The optional directive content is interpreted as the desired date
+format, using the same codes as Python's time.strftime function.  The
+default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also
+be used.  Examples::
+
+    .. |date| date::
+    .. |time| date:: %H:%M
+
+    Today's date is |date|.
+
+    This document was generated on |date| at |time|.
+
+
 ---------------
  Miscellaneous
 ---------------
@@ -1321,104 +1455,6 @@ The following options are recognized:
     Defaults to the document's encoding (if specified).
 
 
-.. _replace:
-
-Replacement Text
-================
-
-:Directive Type: "replace"
-:Doctree Element: Text & inline elements
-:Directive Arguments: None.
-:Directive Options: None.
-:Directive Content: A single paragraph; may contain inline markup.
-
-The "replace" directive is used to indicate replacement text for a
-substitution reference.  It may be used within substitution
-definitions only.  For example, this directive can be used to expand
-abbreviations::
-
-    .. |reST| replace:: reStructuredText
-
-    Yes, |reST| is a long word, so I can't blame anyone for wanting to
-    abbreviate it.
-
-As reStructuredText doesn't support nested inline markup, the only way
-to create a reference with styled text is to use substitutions with
-the "replace" directive::
-
-    I recommend you try |Python|_.
-
-    .. |Python| replace:: Python, *the* best language around
-    .. _Python: http://www.python.org/
-
-
-.. _unicode:
-
-Unicode Character Codes
-=======================
-
-:Directive Type: "unicode"
-:Doctree Element: Text
-:Directive Arguments: One or more, required (Unicode character codes,
-                      optional text, and comments).
-:Directive Options: Possible.
-:Directive Content: None.
-
-The "unicode" directive converts Unicode character codes (numerical
-values) to characters, and may be used in substitution definitions
-only.
-
-The arguments, separated by spaces, can be:
-
-* **character codes** as
-
-  - decimal numbers or
-
-  - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
-    ``u``, or ``\u`` or as XML-style hexadecimal character entities,
-    e.g. ``ᨫ``
-
-* **text**, which is used as-is.
-
-Text following " .. " is a comment and is ignored.  The spaces between
-the arguments are ignored and thus do not appear in the output.
-Hexadecimal codes are case-insensitive.
-
-For example, the following text::
-
-    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
-    all rights reserved.
-
-    .. |copy| unicode:: 0xA9 .. copyright sign
-    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
-       .. with trademark sign
-    .. |---| unicode:: U+02014 .. em dash
-       :trim:
-
-results in:
-
-    Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
-    all rights reserved.
-
-    .. |copy| unicode:: 0xA9 .. copyright sign
-    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
-       .. with trademark sign
-    .. |---| unicode:: U+02014 .. em dash
-       :trim:
-
-The following options are recognized:
-
-``ltrim`` : flag
-    Whitespace to the left of the substitution reference is removed.
-
-``rtrim`` : flag
-    Whitespace to the right of the substitution reference is removed.
-
-``trim`` : flag
-    Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
-    of the substitution reference is removed.
-
-
 Class
 =====
 
-- 
cgit v1.2.1


From 8a4a3988a2cd67973071f5d774c268ed88bf3cf5 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 22 Dec 2005 23:46:16 +0000
Subject: added "date" directive, tests, & translations

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4229 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/todo.txt | 16 ----------------
 1 file changed, 16 deletions(-)

(limited to 'docs')

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index f732e8030..6f1c6291d 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -1358,22 +1358,6 @@ when used in a document.
     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:: 
-
-          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.]
-- 
cgit v1.2.1


From e93547173673882828123eac84df449a8cfeec9a Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 22 Dec 2005 23:47:07 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4230 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/rst/cheatsheet.txt | 1 +
 1 file changed, 1 insertion(+)

(limited to 'docs')

diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
index 3a2a488d1..dfea5bcb7 100644
--- a/docs/user/rst/cheatsheet.txt
+++ b/docs/user/rst/cheatsheet.txt
@@ -99,6 +99,7 @@ include           Read an external reST file as if it were inline
 raw               Non-reST data passed untouched to the Writer
 replace           Replacement text for substitution definitions
 unicode           Unicode character code conversion for substitution defs
+date              Generates today's date; for substitution defs
 class             Set a "class" attribute on the next element
 role              Create a custom interpreted text role [0.3.2]
 default-role      Set the default interpreted text role [0.3.10]
-- 
cgit v1.2.1


From a4dc6c54aafa689141243e1e837dc2bc3b236939 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Wed, 28 Dec 2005 23:48:48 +0000
Subject: Fixed bug with circular substitution definitions that put Docutils
 into an infinite loop.  Circular substitution definitions are now detected &
 reported.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4233 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/ref/rst/restructuredtext.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs')

diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index e0cee6031..1445619b3 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -2027,7 +2027,7 @@ Substitution definitions are indicated by an explicit markup start
 vertical bar, whitespace, and the definition block.  Substitution text
 may not begin or end with whitespace.  A substitution definition block
 contains an embedded inline-compatible directive (without the leading
-".. "), such as an image_.  For example::
+".. "), such as "image_" or "replace_".  For example::
 
     The |biohazard| symbol must be used on containers used to
     dispose of medical waste.
-- 
cgit v1.2.1


From ba12a299518b0f5914eed2cef345fe5a88150d58 Mon Sep 17 00:00:00 2001
From: goodger 
Date: Thu, 5 Jan 2006 12:56:20 +0000
Subject: remove alternate slide show

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4239 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/user/Makefile.docutils-update | 10 ----------
 1 file changed, 10 deletions(-)

(limited to 'docs')

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
index 0e1dd35ab..89097b5ff 100644
--- a/docs/user/Makefile.docutils-update
+++ b/docs/user/Makefile.docutils-update
@@ -1,16 +1,6 @@
-all: slide-shows.s5.html slide-shows-alt.s5.html
-
 slide-shows.s5.html: slide-shows.txt
 	rst2s5.py slide-shows.txt slide-shows.s5.html \
 		--config ../../tools/docutils.conf \
 		--overwrite-theme-files \
 		--link-stylesheet \
 		--no-generator --no-datestamp --no-source-link
-
-slide-shows-alt.s5.html: slide-shows.txt
-	rst2s5.py slide-shows.txt slide-shows-alt.s5.html \
-		--config ../../tools/docutils.conf \
-		--theme small-black \
-		--overwrite-theme-files \
-		--link-stylesheet \
-		--no-generator --no-datestamp --no-source-link
-- 
cgit v1.2.1