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/todo.txt | 385 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 docs/dev/todo.txt (limited to 'docs/dev/todo.txt') 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: -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/todo.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') 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 ================== -- 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/dev/todo.txt') 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 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 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 111 insertions(+), 79 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 34973b112ed65c6fc0285a71104f2b6e94b82224 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 31 May 2002 00:52:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@165 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 71 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 26 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f0ab9880c..0faeb4552 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -76,6 +76,13 @@ General structure: single file or string, vs. directory/package or tree of strings. Simple string I/O is default? +- Fix tests to run standalone. I.e., allow:: + + cd test/test_rst + test_inline_markup.py + + Raises an exception with path processing on GNU/Linux. + Specification ------------- @@ -404,44 +411,53 @@ Directives Unimplemented Transforms ------------------------ -- Footnote Gathering +Footnote Gathering +`````````````````` - Collect and move footnotes to the end of a document. +Collect and move footnotes to the end of a document. -- Hyperlink Target Gathering +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. +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 +Reference Merging +````````````````` - When merging two or more subdocuments (such as docstrings), - conflicting references may need to be resolved. There may be: +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. +- 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? +Should this be done before or after reference-resolving transforms +are applied? What about references from within one subdocument to +inside another? -- Document Splitting +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. References will +have to be adjusted. - (HTML only?) +(HTML only? For now, yes.) -- Navigation +Navigation +`````````` + +If a document is split up, each segment will need navigation links: +parent, children (small TOC), previous (preorder), next (preorder). +Part of `Document Splitting`_? - If a document is split up, each segment will need navigation links: - parent, children (small TOC), previous (preorder), next (preorder). +Others +`````` -- Index +Index HTML Writer @@ -510,6 +526,9 @@ a common option-processing module, as described below. - Added/removed dynamically (during option processing)? Is this possible with Optik? Is it desirable? (See dynamic_ below.) + - Perhaps each component could have an ``init_options`` method, + which can do surgery on the option list? + - Common and component-specific options must not conflict. Reserve short options for the core, and restrict components to long options? @@ -586,7 +605,7 @@ least important): - Lines should be no more than 78 characters long. -- Use "CamelCase" 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, -- cgit v1.2.1 From 545bb4ccc830105d91375a47eb953ee239e81a53 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 1 Jun 2002 02:04:24 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@175 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0faeb4552..19a9622b9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -100,7 +100,7 @@ Specification - 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? +- Add layout component to framework? Or part of the writer? - Once doctree.txt is fleshed out, how about breaking (most of) it up and putting it into nodes.py as docstrings? @@ -408,6 +408,7 @@ Directives either by running it at the command line with a ``--help`` option or through an exposed API. [Suggestion for Optik.] + Unimplemented Transforms ------------------------ @@ -416,6 +417,7 @@ Footnote Gathering Collect and move footnotes to the end of a document. + Hyperlink Target Gathering `````````````````````````` @@ -424,6 +426,7 @@ 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 ````````````````` @@ -438,6 +441,7 @@ Should this be done before or after reference-resolving transforms are applied? What about references from within one subdocument to inside another? + Document Splitting `````````````````` @@ -447,6 +451,7 @@ have to be adjusted. (HTML only? For now, yes.) + Navigation `````````` @@ -454,6 +459,7 @@ If a document is split up, each segment will need navigation links: parent, children (small TOC), previous (preorder), next (preorder). Part of `Document Splitting`_? + Others `````` @@ -475,10 +481,10 @@ 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 a "View source text" link. +- Add an option to generate a "View source text" link. (Done.) -- @@ Add an option to generate a "Generated by Docutils [from - reStructuredText source?]" message, with links. +- Add an option to generate a "Generated by Docutils [from + reStructuredText source?]" message, with links. (Done.) - If a list's items contain single paragraphs only, omit the

tags? Recursively? (if item == list whose items are single paragraphs @@ -499,9 +505,9 @@ a common option-processing module, as described below. - Named docutils.frontend.OptionParser. Supporting parameters have been added to docutils.core.Publisher/publish(): ``argv`` & - ``usage``. + ``usage``. (Done.) - - Use Optik to do modular command-line option processing. + - Use Optik to do modular command-line option processing. (Done.) - An Optik 'option Values' object is attached to the document. @@ -517,9 +523,10 @@ a common option-processing module, as described below. pub.publish() - The core supports all common options (--verbose, --date, etc.). + (Done.) - Each component adds its own specific options (HTML: --stylesheet, - etc.). + etc.). (Done.) - Disables common options that don't apply? @@ -536,7 +543,7 @@ a common option-processing module, as described below. - Build an OptionParser dynamically based on the known Reader & Writer. Store a data structure in each component containing its specific options, merge with the common option data, and - instantiate an OptionParser. + instantiate an OptionParser. (Done.) - 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 @@ -573,9 +580,7 @@ a common option-processing module, as described below. 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. +- Implement command-line options. Common options: --encoding=name. Project Policies -- cgit v1.2.1 From 682398e24b9262bb39c4e3aaefe6903f1031e51c Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 13 Jun 2002 03:35:39 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@185 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 19a9622b9..b7a974d19 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -76,6 +76,11 @@ General structure: single file or string, vs. directory/package or tree of strings. Simple string I/O is default? +- Name ideas: importer/exporter. Perhaps reader/writer should be + applied to lower-level tasks? "PySource Reader" or "PySource + Importer"? "HTML Writer" or "HTML Exporter"? If we stick with the + status quo, what to call the components that do low-level I/O? + - Fix tests to run standalone. I.e., allow:: cd test/test_rst @@ -314,8 +319,20 @@ Directives lists). Without special syntax, this directive becomes low priority. - - _`body.columns`: Multi-column table/list, with number of columns - as argument. + - _`body.columns`: Multi-column table/list. Number of columns as + argument? Perhaps a variation on `table syntax alternative 2`__:: + + 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 paragraph of row 3, + column 2 + + __ problems.html#tables - @@ _`body.verse`: Paragraphs with linebreaks preserved, *and* inline markup support too. Use cases: verse (poetry, song lyrics, @@ -632,11 +649,10 @@ 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. +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. 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 adaac3281b2d8453669df76025e2f6b2491768d0 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 13 Jun 2002 22:33:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@188 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b7a974d19..890b7cc1e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -257,7 +257,7 @@ Directives - _`parts.citations` - - _`parts.topic` + - _`parts.topic` (maybe "body.topic") - _`parts.sectnum` (section numbering; add support to .contents; could be cmdline option also) @@ -286,7 +286,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 (optional attribute "qa" done). New elements would be required. Perhaps:: @@ -320,7 +320,8 @@ Directives priority. - _`body.columns`: Multi-column table/list. Number of columns as - argument? Perhaps a variation on `table syntax alternative 2`__:: + argument? Perhaps a variation on `table syntax alternative 2`__, + combined with bullet list syntax to indicate rows:: col 1 col 2 ===== ===== @@ -404,6 +405,10 @@ Directives textart, text, linetext. 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. (Maybe "admonitions.example"?) + - _`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 c004505fe4f0fe0afda4e39cf488a4204e01e343 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 14 Jun 2002 23:14:14 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@192 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 890b7cc1e..c2f6e94f1 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -15,6 +15,9 @@ Priority items are marked with "@" symbols. The more @s, the higher the priority. Items in question form (containing "?") are ideas which require more thought and debate; they are potential to-do's. +Many of these items are awaiting champions. If you see something +you'd like to tackle, please do! + General ------- @@ -238,6 +241,32 @@ __ http://docutils.sf.net/spec/rst/alternatives.html#or-not-to-do - Continue to report (info, level 1) enumerated lists whose start value is not ordinal-1? +- Generalize the "doctest block" construct (which is overly + Python-centric) to other interactive sessions? "Doctest block" + could be renamed to "I/O block" or "interactive block", and each of + these could also be recognized as such by the parser: + + - Shell sessions:: + + $ cat example1.txt + A block beginning with a "$ " prompt is interpreted as a shell + session interactive block. As with Doctest blocks, the + interactive block ends with the first blank line, and wouldn't + have to be indented. + + - Root shell sessions:: + + # cat example2.txt + A block beginning with a "# " prompt is interpreted as a root + shell session (the user is or has to be logged in as root) + interactive block. Again, the block ends with a blank line. + + Other standard (and unambiguous) interactive session prompts could + easily be added (such as "> " for WinDOS). + + Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread + "docutils feedback"). + Directives `````````` -- cgit v1.2.1 From 7f675ec43766d8805ba70f87064e330912f90ec3 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 19 Jun 2002 02:54:38 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@197 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 53 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c2f6e94f1..c22c65e08 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -68,10 +68,47 @@ 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? + To determine the encoding, use these heuristics in order: + + - Try the encoding specified by a command-line option, if any. + + - Try the encoding specified by an "encoding" directive, and/or an + "encoding" field in field lists & PEP headers, if any. (The same + could apply to "language".) + + - Try ASCII. + + - Try the locale default encoding. + + - Try UTF-8. + + - Try Latin-1. + + From Skip Montanaro's "Using Unicode in Python":: + + def encode_heuristically(s, enc=None): + "try interpreting s using several possible encodings" + try: + x = unicode(s, "ascii") + # if it's ascii, just return the plain string + return s + # you might want to return a Unicode object instead + # return x + except UnicodeError: + encodings = ["cp1252", "utf-8", "iso-8859-15", "iso-8859-1"] + # try any caller-provided encoding first + if enc: encodings.insert(0, enc) + for enc in encodings: + try: + x = unicode(s , enc) + except UnicodeError: + pass + else: + return x + # punt + return s + +- 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 @@ -84,6 +121,14 @@ General Importer"? "HTML Writer" or "HTML Exporter"? If we stick with the status quo, what to call the components that do low-level I/O? + - IOReader, IOWriter + - StreamReader, StreamWriter + - DataReader, DataWriter + - Inputter, Outputter + - Scanner, Recorder? + - Lector?, Scribe + - Loader, Storer/Recorder (maybe subclasses of Storage) + - Fix tests to run standalone. I.e., allow:: cd test/test_rst -- cgit v1.2.1 From 7169009358ab112b33e8c0fb9d37ff902eb0892c Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 27 Jun 2002 01:26:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@214 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 189 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 155 insertions(+), 34 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c22c65e08..38f6be2d5 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -19,6 +19,41 @@ Many of these items are awaiting champions. If you see something you'd like to tackle, please do! +Bugs +---- + +- (Fixed, I think.) When there are duplicate implicit target names + (e.g., section headers), a named hyperlink will link to the last of + them. It shouldn't link to any at all, and should report an error. + + - nodes.document.nameids maps names to IDs. When there is a + duplicate, the last one stays. Idea: have a parallel + nodes.document.nametype mapping, name -> boolean (explicit name?). + :: + + ==== ===== ======== ======== ======= ==== ===== ===== + Old State Input Action New State Notes + ----------- -------- ----------------- ----------- + id type new type sys.msg. dupname id type + ==== ===== ======== ======== ======= ==== ===== ===== + -- -- 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 + ==== ===== ======== ======== ======= ==== ===== ===== + + (The above is an example of `table syntax alternative 3`__; not + implemented yet, but I'm thinking about it.) + + __ rst/problems.html#tables + + General ------- @@ -73,8 +108,8 @@ General - Try the encoding specified by a command-line option, if any. - Try the encoding specified by an "encoding" directive, and/or an - "encoding" field in field lists & PEP headers, if any. (The same - could apply to "language".) + "encoding" field in field lists & PEP headers, if any. See the + misc.encoding_ directive below. - Try ASCII. @@ -118,23 +153,36 @@ General - Name ideas: importer/exporter. Perhaps reader/writer should be applied to lower-level tasks? "PySource Reader" or "PySource - Importer"? "HTML Writer" or "HTML Exporter"? If we stick with the - status quo, what to call the components that do low-level I/O? + Importer"? "HTML Writer" or "HTML Exporter"? I like the names + "Reader" & "Writer" for the high-level classes. So if we stick with + the status quo, what to call the components that do low-level I/O? - IOReader, IOWriter - - StreamReader, StreamWriter - DataReader, DataWriter - Inputter, Outputter - Scanner, Recorder? - Lector?, Scribe - - Loader, Storer/Recorder (maybe subclasses of Storage) + - Loader, Storer/Stower/Recorder + - InputStorage, OutputStorage + - Input, Output + - Source, Destination + + Perhaps subclasses of a single class, a abstraction for + file/string/etc. reading & writing. + + - Storage + - IO + + Implement as a single module (``docutils/storage.py``)? Or as a + subpackage (``docutils/storage/*.py``)? - Fix tests to run standalone. I.e., allow:: cd test/test_rst test_inline_markup.py - Raises an exception with path processing on GNU/Linux. + Raises an exception with path processing on GNU/Linux (but only + sometimes?). Specification @@ -164,7 +212,7 @@ reStructuredText Parser Also see the `... Or Not To Do?`__ list. -__ http://docutils.sf.net/spec/rst/alternatives.html#or-not-to-do +__ rst/alternatives.html#or-not-to-do - Add motivation sections for constructs in spec. @@ -214,7 +262,7 @@ __ http://docutils.sf.net/spec/rst/alternatives.html#or-not-to-do - 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 +- 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. @@ -357,6 +405,20 @@ Directives time or at substitution time? Dangerous? Perhaps limit to canned macros; see text.date_ below. + - _`misc.encoding`: Specify the character encoding of the input + data. But there are problems: + + - When it sees the directive, the parser will already have read + the input data, and encoding determination will already have + been done. + + - If a file with an "encoding" directive is edited and saved with + a different encoding, the directive may cause data corruption. + + - _`misc.language`: Specify the language of a document. There is a + problem similar to the first problem listed for misc.encoding_, + although to a lesser degree. + - _`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?) @@ -394,20 +456,10 @@ Directives priority. - _`body.columns`: Multi-column table/list. Number of columns as - argument? Perhaps a variation on `table syntax alternative 2`__, - combined with bullet list syntax to indicate rows:: - - 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. + argument? Several `alternative syntaxes`__ are proposed that + might not need a directive.. - Second paragraph of row 3, - column 2 - - __ problems.html#tables + __ rst/problems.html#tables - @@ _`body.verse`: Paragraphs with linebreaks preserved, *and* inline markup support too. Use cases: verse (poetry, song lyrics, @@ -490,7 +542,9 @@ 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. 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 misc.include_, implement canned macros? E.g.:: @@ -500,6 +554,9 @@ Directives 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.] @@ -682,6 +739,40 @@ a common option-processing module, as described below. 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. + + Coding Conventions ------------------ @@ -693,8 +784,8 @@ it probably will be accepted. But don't be surprised if the 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 +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 @@ -720,8 +811,9 @@ least important): - 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 +.. _Style Guide for Python Code: + http://www.python.org/peps/pep-0008.html +.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html Copyrights and Licensing @@ -775,17 +867,28 @@ 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, untried code. - See `Additions to Docutils`_ and `The Sandbox`_ below. +- 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. -Please consider subscribing to the appropriate `mailing lists`_. +- 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 abberations 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/ -.. _mailing lists: ../index.html#mailing-lists Additions to Docutils @@ -826,6 +929,24 @@ It's easy to move code over to the main source tree once it's closer to completion. +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 ----------- @@ -835,9 +956,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, or -given name + family initial). It's OK to make a mess! But please, -play nice. +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. 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 0991966cd6eef900dfbb455ef3a3f643445410f8 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 27 Jun 2002 01:30:38 +0000 Subject: fixed git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@215 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 38f6be2d5..580d9fcdd 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -758,7 +758,7 @@ his essay `The Magic Cauldron`_: through to contribute. .. _The Magic Cauldron: - http://www.tuxedo.org/~esr/writings/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, -- cgit v1.2.1 From 61e25d656ee75dc1924eca96b0ac8fd00cfe1b17 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 27 Jun 2002 01:53:03 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@216 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 580d9fcdd..69f5770d4 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -51,8 +51,15 @@ Bugs (The above is an example of `table syntax alternative 3`__; not implemented yet, but I'm thinking about it.) + 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 an identical + URI. The new target is invalidated regardless. + __ rst/problems.html#tables +- The "::" before the table above should be removed completely from + the output. A single ":" is being left behind. + General ------- -- cgit v1.2.1 From 4118aed4449182d2c89612f83ed0d36e0562ed57 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 28 Jun 2002 04:21:01 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@222 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 104 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 20 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 69f5770d4..4ba150157 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -57,9 +57,6 @@ Bugs __ rst/problems.html#tables -- The "::" before the table above should be removed completely from - the output. A single ":" is being left behind. - General ------- @@ -107,26 +104,64 @@ General - 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. +- @@ Add _`support for character set encodings` on input & output, + Unicode internally. To determine the encoding, use these heuristics in order: - Try the encoding specified by a command-line option, if any. - + - Try the encoding specified by an "encoding" directive, and/or an "encoding" field in field lists & PEP headers, if any. See the misc.encoding_ directive below. - - Try ASCII. - - - Try the locale default encoding. - + - Try the locale's encoding. + - Try UTF-8. - - - Try Latin-1. - - From Skip Montanaro's "Using Unicode in Python":: + + - Try platform-specific encodings: CP-1252 on Windows, Mac-Roman on + MacOS, perhaps Latin-9 (iso-8859-15) otherwise. + + Some questions: + + - Does the application have to call + ``locale.setlocale(locale.LC_ALL, '')``, and if so, where? Is it OK + to call setlocale from within the decoding function, or should it be + left up to the client application? + + - Should I use the result of ``locale.getlocale()``? On + Win2K/Python2.2.1, I get this:: + + >>> import locale + >>> locale.getlocale() + (None, None) + >>> locale.getdefaultlocale() + ('en_US', 'cp1252') + + Looks good so far. + + >>> locale.setlocale(locale.LC_ALL, '') + 'English_United States.1252' + >>> locale.getlocale() + ['English_United States', '1252'] + + "1252"? What happened to the "cp"? + + >>> s='abcd' + >>> s.decode('1252') + Traceback (most recent call last): + File "", line 1, in ? + LookupError: unknown encoding + + How can I use ``locale.getlocale()`` when it doesn't return a + known encoding? Or put another way, how can I get a known + encoding out of ``locale.getlocale()``? + + - Does ``locale.getdefaultlocale()[1]`` reliably produce the + platform-specific encoding? + + From Skip Montanaro's `Using Unicode in Python`_ ("Console Input" + section):: def encode_heuristically(s, enc=None): "try interpreting s using several possible encodings" @@ -150,6 +185,28 @@ General # punt return s + .. _Using Unicode in Python: + http://manatee.mojam.com/~skip/unicode/unicode/ + + Windows CP-1252 and MacOS Mac-Roman are full 8-bit encodings, so + there's no point trying anything after them; they'll match any byte + string. UTF-8 is almost a full 8-bit encoding; it only uses up to + 0xFD but 0xFE & 0xFF are likely unused by most texts in other + encodings anyhow (a notable exception is UTF-16, in which 0xFEFF is + used as a "byte order mark"; but we'll ignore UTF-16 as it's + incompatible with ASCII). UTF-8 does have the advantage of a + verifyable encoding scheme, which is unlikely to be achieved by + accident in an 8-bit text. (I assume the UTF-8 codec verifies the + encoding.) So it makes sense to check for UTF-8 before + platform-dependent encodings (like CP-1252). + + ISO-8859-15 is an update of ISO-8859-1, and they share the same code + space (0x00-0x7F, 0xA0-0xFF), so there's no point in checking for + both. If one succeeds, the other one inevitably will too. + + `Introduction to i18n`_ by Tomohiro KUBOTA is a good reference + (http://www.debian.org/doc/manuals/intro-i18n/). + - Need a Unicode -> HTML entities codec for HTML writer? - Distributor/filer object passed to Writer, equivalent passed to @@ -177,11 +234,14 @@ General Perhaps subclasses of a single class, a abstraction for file/string/etc. reading & writing. - - Storage - - IO + - Storage (thus InputStorage/OutputStorage) + - IO (SourceIO/DestIO; InputIO/OutputIO) Implement as a single module (``docutils/storage.py``)? Or as a - subpackage (``docutils/storage/*.py``)? + subpackage (``docutils/storage/*.py``)? Decision: use a single + module for now, possibly switching to a package if it gets too big. + + See `support for character set encodings`_ above. - Fix tests to run standalone. I.e., allow:: @@ -191,6 +251,9 @@ General Raises an exception with path processing on GNU/Linux (but only sometimes?). +- Perhaps the ``Component.supports`` method should deal with + individual features ("meta" etc.) instead of formats ("html" etc.)? + Specification ------------- @@ -648,7 +711,10 @@ HTML Writer - If a list's items contain single paragraphs only, omit the

tags? Recursively? (if item == list whose items are single paragraphs - only...) + only...) Optional, with "--compact-lists" and "--no-compact-lists"? + Should only simple lists be compacted, or should the first paragraph + of all list items lack a

(perhaps "--compact-all-lists" and + "--compact-simple-lists")? Front-Ends @@ -740,8 +806,6 @@ a common option-processing module, as described below. conflicts) to splitting common and component-specific options apart. -- Implement command-line options. Common options: --encoding=name. - Project Policies ================ -- cgit v1.2.1 From 90bf36cbb768a40211d0bb87e29e7442f0f240b7 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 28 Jun 2002 04:29:03 +0000 Subject: fixed link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@223 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4ba150157..d0fdd2871 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -204,8 +204,10 @@ General space (0x00-0x7F, 0xA0-0xFF), so there's no point in checking for both. If one succeeds, the other one inevitably will too. - `Introduction to i18n`_ by Tomohiro KUBOTA is a good reference - (http://www.debian.org/doc/manuals/intro-i18n/). + `Introduction to i18n`_ by Tomohiro KUBOTA is a good reference. + + .. _Introduction to i18n: + http://www.debian.org/doc/manuals/intro-i18n/ - Need a Unicode -> HTML entities codec for HTML writer? -- cgit v1.2.1 From 7478c5e11f04e31b322d4b9db4173297e1e8408e Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 29 Jun 2002 00:52:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@231 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index d0fdd2871..ab8b92cb9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -63,15 +63,23 @@ General - Document! - - Internal module documentation. + - Internal module documentation (docstrings). - - User docs. + - Implementation docs. + + - spec/doctree.txt: Doctree nodes (DTD element) semantics: + + - External (public) attributes (node.attributes). + - Internal attributes (node.*). + - Linking mechanism. + + - How a Writer works & how to write one - - Doctree nodes (DTD element) semantics: + - Howto: Transforms - - External (public) attributes (node.attributes). - - Internal attributes (node.*). - - Linking mechanism. + - Howto: Directives + + - User docs. - Refactor @@ -104,8 +112,8 @@ General - 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. +- @@ (Done.) Add _`support for character set encodings` on input & + output, Unicode internally. To determine the encoding, use these heuristics in order: @@ -211,11 +219,12 @@ General - 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? +- (Done, in io.py.) 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 file I/O is + default. - Name ideas: importer/exporter. Perhaps reader/writer should be applied to lower-level tasks? "PySource Reader" or "PySource @@ -286,6 +295,8 @@ Also see the `... Or Not To Do?`__ list. __ rst/alternatives.html#or-not-to-do +- Clean up the code; refactor as required. + - Add motivation sections for constructs in spec. - Allow very long titles (on two or more lines)? -- cgit v1.2.1 From fbaab75dffd78697fd9fcd8cb747bed50d2773a1 Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 1 Jul 2002 13:59:11 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@238 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index ab8b92cb9..964c35b17 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -608,11 +608,12 @@ Directives (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. Current favorites: "line_block" for - element name, "lines" for directive name. + 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, -- cgit v1.2.1 From be8b2373908f3c5f02b983b0f65016a0911ad921 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 4 Jul 2002 01:36:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@248 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 964c35b17..6149a1bdb 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -22,6 +22,12 @@ you'd like to tackle, please do! Bugs ---- +- The move to I/O classes (io.py) has broken the "view source" links. + (Pointed out by Simon Budig.) + + Perhaps add attributes to I/O classes, like ``IO.source_path``? + Include logic to skip link creation if ``IO.source_path`` is empty. + - (Fixed, I think.) When there are duplicate implicit target names (e.g., section headers), a named hyperlink will link to the last of them. It shouldn't link to any at all, and should report an error. -- cgit v1.2.1 From 87775b59e4ba4b6cb20baa1f563a8751e8dbd7c0 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 6 Jul 2002 03:06:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@258 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 324 ++++++++---------------------------------------------- 1 file changed, 45 insertions(+), 279 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6149a1bdb..b77fcf2ba 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1,9 +1,12 @@ ================= Docutils_ Notes ================= +:Author: David Goodger (with input from many) +:Contact: goodger@users.sourceforge.net :Date: $Date$ :Revision: $Revision$ + .. _Docutils: http://docutils.sourceforge.net/ .. contents:: @@ -22,46 +25,7 @@ you'd like to tackle, please do! Bugs ---- -- The move to I/O classes (io.py) has broken the "view source" links. - (Pointed out by Simon Budig.) - - Perhaps add attributes to I/O classes, like ``IO.source_path``? - Include logic to skip link creation if ``IO.source_path`` is empty. - -- (Fixed, I think.) When there are duplicate implicit target names - (e.g., section headers), a named hyperlink will link to the last of - them. It shouldn't link to any at all, and should report an error. - - - nodes.document.nameids maps names to IDs. When there is a - duplicate, the last one stays. Idea: have a parallel - nodes.document.nametype mapping, name -> boolean (explicit name?). - :: - - ==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes - ----------- -------- ----------------- ----------- - id type new type sys.msg. dupname id type - ==== ===== ======== ======== ======= ==== ===== ===== - -- -- 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 - ==== ===== ======== ======== ======= ==== ===== ===== - - (The above is an example of `table syntax alternative 3`__; not - implemented yet, but I'm thinking about it.) - - 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 an identical - URI. The new target is invalidated regardless. - - __ rst/problems.html#tables +None reported. General @@ -118,148 +82,8 @@ General - Implement a specialized PEP/HTML writer? Or implement a generic `templating system`_, with PEP/HTML as one application? -- @@ (Done.) Add _`support for character set encodings` on input & - output, Unicode internally. - - To determine the encoding, use these heuristics in order: - - - Try the encoding specified by a command-line option, if any. - - - Try the encoding specified by an "encoding" directive, and/or an - "encoding" field in field lists & PEP headers, if any. See the - misc.encoding_ directive below. - - - Try the locale's encoding. - - - Try UTF-8. - - - Try platform-specific encodings: CP-1252 on Windows, Mac-Roman on - MacOS, perhaps Latin-9 (iso-8859-15) otherwise. - - Some questions: - - - Does the application have to call - ``locale.setlocale(locale.LC_ALL, '')``, and if so, where? Is it OK - to call setlocale from within the decoding function, or should it be - left up to the client application? - - - Should I use the result of ``locale.getlocale()``? On - Win2K/Python2.2.1, I get this:: - - >>> import locale - >>> locale.getlocale() - (None, None) - >>> locale.getdefaultlocale() - ('en_US', 'cp1252') - - Looks good so far. - - >>> locale.setlocale(locale.LC_ALL, '') - 'English_United States.1252' - >>> locale.getlocale() - ['English_United States', '1252'] - - "1252"? What happened to the "cp"? - - >>> s='abcd' - >>> s.decode('1252') - Traceback (most recent call last): - File "", line 1, in ? - LookupError: unknown encoding - - How can I use ``locale.getlocale()`` when it doesn't return a - known encoding? Or put another way, how can I get a known - encoding out of ``locale.getlocale()``? - - - Does ``locale.getdefaultlocale()[1]`` reliably produce the - platform-specific encoding? - - From Skip Montanaro's `Using Unicode in Python`_ ("Console Input" - section):: - - def encode_heuristically(s, enc=None): - "try interpreting s using several possible encodings" - try: - x = unicode(s, "ascii") - # if it's ascii, just return the plain string - return s - # you might want to return a Unicode object instead - # return x - except UnicodeError: - encodings = ["cp1252", "utf-8", "iso-8859-15", "iso-8859-1"] - # try any caller-provided encoding first - if enc: encodings.insert(0, enc) - for enc in encodings: - try: - x = unicode(s , enc) - except UnicodeError: - pass - else: - return x - # punt - return s - - .. _Using Unicode in Python: - http://manatee.mojam.com/~skip/unicode/unicode/ - - Windows CP-1252 and MacOS Mac-Roman are full 8-bit encodings, so - there's no point trying anything after them; they'll match any byte - string. UTF-8 is almost a full 8-bit encoding; it only uses up to - 0xFD but 0xFE & 0xFF are likely unused by most texts in other - encodings anyhow (a notable exception is UTF-16, in which 0xFEFF is - used as a "byte order mark"; but we'll ignore UTF-16 as it's - incompatible with ASCII). UTF-8 does have the advantage of a - verifyable encoding scheme, which is unlikely to be achieved by - accident in an 8-bit text. (I assume the UTF-8 codec verifies the - encoding.) So it makes sense to check for UTF-8 before - platform-dependent encodings (like CP-1252). - - ISO-8859-15 is an update of ISO-8859-1, and they share the same code - space (0x00-0x7F, 0xA0-0xFF), so there's no point in checking for - both. If one succeeds, the other one inevitably will too. - - `Introduction to i18n`_ by Tomohiro KUBOTA is a good reference. - - .. _Introduction to i18n: - http://www.debian.org/doc/manuals/intro-i18n/ - - Need a Unicode -> HTML entities codec for HTML writer? -- (Done, in io.py.) 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 file I/O is - default. - -- Name ideas: importer/exporter. Perhaps reader/writer should be - applied to lower-level tasks? "PySource Reader" or "PySource - Importer"? "HTML Writer" or "HTML Exporter"? I like the names - "Reader" & "Writer" for the high-level classes. So if we stick with - the status quo, what to call the components that do low-level I/O? - - - IOReader, IOWriter - - DataReader, DataWriter - - Inputter, Outputter - - Scanner, Recorder? - - Lector?, Scribe - - Loader, Storer/Stower/Recorder - - InputStorage, OutputStorage - - Input, Output - - Source, Destination - - Perhaps subclasses of a single class, a abstraction for - file/string/etc. reading & writing. - - - Storage (thus InputStorage/OutputStorage) - - IO (SourceIO/DestIO; InputIO/OutputIO) - - Implement as a single module (``docutils/storage.py``)? Or as a - subpackage (``docutils/storage/*.py``)? Decision: use a single - module for now, possibly switching to a package if it gets too big. - - See `support for character set encodings`_ above. - - Fix tests to run standalone. I.e., allow:: cd test/test_rst @@ -712,23 +536,9 @@ Index HTML Writer ----------- -- 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. (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? - -- Add an option to generate a "View source text" link. (Done.) - -- Add an option to generate a "Generated by Docutils [from - reStructuredText source?]" message, with links. (Done.) - - If a list's items contain single paragraphs only, omit the

tags? Recursively? (if item == list whose items are single paragraphs only...) Optional, with "--compact-lists" and "--no-compact-lists"? @@ -736,95 +546,51 @@ 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. + 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 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 - module, and add option processing. - - - Named docutils.frontend.OptionParser. Supporting parameters have - been added to docutils.core.Publisher/publish(): ``argv`` & - ``usage``. (Done.) - - - Use Optik to do modular command-line option processing. (Done.) - - - An Optik 'option Values' object is attached to the document. - - - 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:: - - pub = Publisher(...) - pub.process_command_line(argv=[]) - pub.options.an_option = "my default value" - pub.publish() - - - The core supports all common options (--verbose, --date, etc.). - (Done.) - - - Each component adds its own specific options (HTML: --stylesheet, - etc.). (Done.) - - - Disables common options that don't apply? - - - Added/removed dynamically (during option processing)? Is this - possible with Optik? Is it desirable? (See dynamic_ below.) - - - Perhaps each component could have an ``init_options`` method, - which can do surgery on the option list? - - - 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. Store a data structure in each component containing its - specific options, merge with the common option data, and - instantiate an OptionParser. (Done.) - - - 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. - - c) _`Unqualified`: Reader and Writer are specified as subcommands - (e.g. ``publish pep html [options]``, ``publish pysource pdf - [options]``). A single front-end would be sufficient, but - probably only useful for testing purposes. - - d) _`Dynamic`: Reader and/or Writer are specified by options, with - defaults if unspecified (e.g. ``publish --writer pdf - [options]``). Is this possible? The option parser would have - to be told about new options it needs to handle, on the fly. - Component-specific options would have to be specified *after* - the component-specifying option. - - Allow common options before subcommands, as in CVS? Or group all - options together? In the case of the `fully qualified`_ - front-ends, all the options will have to be grouped together - anyway, so there's no advantage (we can't use it to avoid - conflicts) to splitting common and component-specific options - apart. +- Common and component-specific options must not conflict. Reserve + short options for the core, and restrict components to long + 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?) + + 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. + + c) _`Unqualified`: Reader and Writer are specified as subcommands + (e.g. ``publish pep html [options]``, ``publish pysource pdf + [options]``). A single front-end would be sufficient, but + probably only useful for testing purposes. + + d) _`Dynamic`: Reader and/or Writer are specified by options, with + defaults if unspecified (e.g. ``publish --writer pdf + [options]``). Is this possible? The option parser would have + to be told about new options it needs to handle, on the fly. + Component-specific options would have to be specified *after* + the component-specifying option. + + Allow common options before subcommands, as in CVS? Or group all + options together? In the case of the `fully qualified`_ + front-ends, all the options will have to be grouped together + anyway, so there's no advantage (we can't use it to avoid + conflicts) to splitting common and component-specific options + apart. Project Policies -- cgit v1.2.1 From 0b3ab52210c5a244aa2e56dd82e2df832aaece71 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 11 Jul 2002 01:54:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@265 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index b77fcf2ba..933294fe4 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -95,6 +95,12 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? +- Add "NullIO" degenerate ``docutils.io.IO`` subclass. + +- 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 ------------- @@ -549,6 +555,12 @@ HTML Writer Tried it; not easy. If you're interested, email me for a copy of the patch. +- Add more support for elements, especially for navigation + bars. + +- "name" attributes only on these tags: a, applet, form, frame, + iframe, img, map. + Front-Ends ---------- -- cgit v1.2.1 From 005c5319f9cbf6f4776e117e5bb6b690f3cf3374 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 13 Jul 2002 03:06:48 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@276 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 933294fe4..a42f8d74f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -25,7 +25,20 @@ you'd like to tackle, please do! Bugs ---- -None reported. +- 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:: + + .. 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? General @@ -95,8 +108,6 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- Add "NullIO" degenerate ``docutils.io.IO`` subclass. - - Add a command-line option & directive attribute to control TOC backlinks: no TOC backlinks, backlinks to TOC entries, or backlinks to TOC itself only. -- 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/dev/todo.txt') 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 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/todo.txt | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'docs/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/todo.txt | 7 ------- 1 file changed, 7 deletions(-) (limited to 'docs/dev/todo.txt') 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 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 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From fe85dac3bdde0869b81347eca18a300a881940e8 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 27 Jul 2002 03:54:33 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@381 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a0b445f26..e53f96215 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -116,6 +116,15 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? +- Get the "--source-link" option (or a variation) to produce relative + links, like in this case:: + + cd tools + html.py -s ../spec/rst/problems.txt ../spec/rst/problems.html + + The source link should refer to "problems.txt" (relative to + "problems.html"), not "../spec/rst/problems.txt" which it does now. + Specification ------------- @@ -567,16 +576,6 @@ HTML Writer - @@@ Construct a _`templating system`, as in ht2html/yaptu, using directives and substitutions for dynamic stuff. -- If a list's items contain single paragraphs only, omit the

tags? - Recursively? (if item == list whose items are single paragraphs - only...) Optional, with "--compact-lists" and "--no-compact-lists"? - Should only simple lists be compacted, or should the first paragraph - of all list items lack a

(perhaps "--compact-all-lists" and - "--compact-simple-lists")? - - 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. @@ -629,6 +628,10 @@ Front-End Tools - Parameterize help text & defaults somehow? Perhaps a callback? Or initialize ``cmdline_options`` in ``__init__``? +- Write a tool (perhaps ``html-all.py`` or ``htmldocs.py``) which + generates .html from all the .txt files in the project. It could + even be run by setup.py as a final step! + Project Policies ================ -- cgit v1.2.1 From c32cc0f4c2155740d72c24cd5ff5d01d6e7c15bb Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 27 Jul 2002 15:51:02 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@394 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e53f96215..07d9c95cf 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -73,10 +73,6 @@ General - Howto: Directives - User docs. - - - How to use the front-end tools (docs/tools.txt). - - - Configuration file syntax & recognized entries. - Refactor @@ -143,12 +139,20 @@ Specification - 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 writer? - - Once doctree.txt is fleshed out, how about breaking (most of) it up and putting it into nodes.py as docstrings? +PySource Reader +--------------- + +- Analyze Tony Ibbs' PySource code. + +- Analyze Doug Hellman's HappyDoc project. + +- Take the best ideas and integrate them into Docutils 0.3. + + reStructuredText Parser ----------------------- @@ -586,10 +590,6 @@ HTML Writer Front-End Tools --------------- -- Common and component-specific options must not conflict. Reserve - short options for the core, and restrict components to long - 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?) @@ -628,9 +628,10 @@ Front-End Tools - Parameterize help text & defaults somehow? Perhaps a callback? Or initialize ``cmdline_options`` in ``__init__``? -- Write a tool (perhaps ``html-all.py`` or ``htmldocs.py``) which +- Write a tool (perhaps ``htmldocs.py`` or ``buildhtml.py``) which generates .html from all the .txt files in the project. It could - even be run by setup.py as a final step! + even be run by setup.py as a final step! Once PySource is there, + it can build .html from .py as well. Project Policies -- cgit v1.2.1 From 0fde6c336dc365cf31b5c0caf2087642a8af7c9d Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 27 Jul 2002 16:06:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@395 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 07d9c95cf..4dc22943c 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -148,7 +148,7 @@ PySource Reader - Analyze Tony Ibbs' PySource code. -- Analyze Doug Hellman's HappyDoc project. +- Analyze Doug Hellmann's HappyDoc project. - Take the best ideas and integrate them into Docutils 0.3. -- cgit v1.2.1 From ae2521dfb7014eca7ac0d421c3a8f8658e1f0553 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 28 Jul 2002 17:46:16 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@401 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 --------- 1 file changed, 9 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4dc22943c..0ba2e863f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -112,15 +112,6 @@ General - Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -- Get the "--source-link" option (or a variation) to produce relative - links, like in this case:: - - cd tools - html.py -s ../spec/rst/problems.txt ../spec/rst/problems.html - - The source link should refer to "problems.txt" (relative to - "problems.html"), not "../spec/rst/problems.txt" which it does now. - Specification ------------- -- cgit v1.2.1 From 60e5c1371c60c00dc4c76d684f263021a703c3a7 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 31 Jul 2002 01:49:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@425 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 0ba2e863f..009da9801 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -619,11 +619,6 @@ Front-End Tools - Parameterize help text & defaults somehow? Perhaps a callback? Or initialize ``cmdline_options`` in ``__init__``? -- Write a tool (perhaps ``htmldocs.py`` or ``buildhtml.py``) which - generates .html from all the .txt files in the project. It could - even be run by setup.py as a final step! Once PySource is there, - it can build .html from .py as well. - Project Policies ================ -- cgit v1.2.1 From 1822e231995b5aacc2511922f1fe4b7c46ff2de5 Mon Sep 17 00:00:00 2001 From: goodger Date: Thu, 1 Aug 2002 00:15:21 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@433 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 009da9801..62412811a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -79,7 +79,7 @@ General - Rename methods & variables according to the `coding conventions`_ below. - - The name->id conversion and hyperlink resolution code needs to be + - 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. @@ -95,11 +95,11 @@ General 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 +- 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 -> HTML entities codec for HTML writer? +- Need a Unicode to HTML entities codec for HTML writer? - Fix tests to run standalone. I.e., allow:: @@ -168,13 +168,13 @@ __ rst/alternatives.html#or-not-to-do - Add _`character processing`? For example: - - ``--`` -> em-dash (or ``--`` -> en-dash, and ``---`` -> em-dash). + - ``--`` 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. - - ``"\ "`` ->  . - - Escaped newlines ->
. + - ``"\ "`` to  . + - Escaped newlines to
. - Escaped period or quote as a disappearing catalyst to allow character-level inline markup? - Others? @@ -297,8 +297,9 @@ __ rst/alternatives.html#or-not-to-do "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:: + 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:: @@ -306,10 +307,18 @@ __ rst/alternatives.html#or-not-to-do > > 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. +- Decide whether or not to implement Simon Budig's "inline external + targets" syntax idea, and if so, how (pragma directive or full-blown + addition to the spec & parser). + +- Add support for pragma (syntax-altering) directives. + Directives `````````` @@ -593,9 +602,11 @@ Front-End Tools 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. + ``pysource2 pdf [options]``). The Writer is known before option + processing happens, allowing the OptionParser to be built + dynamically. Alternatively, the Writer could be hard-coded and + the Reader specified as a sub-command (e.g. ``htmlfrom pep + [options]``). c) _`Unqualified`: Reader and Writer are specified as subcommands (e.g. ``publish pep html [options]``, ``publish pysource pdf @@ -617,7 +628,9 @@ Front-End Tools apart. - Parameterize help text & defaults somehow? Perhaps a callback? Or - initialize ``cmdline_options`` in ``__init__``? + initialize ``cmdline_options`` in ``__init__`` or ``init_options``? + +- Disable common options that don't apply? Project Policies -- cgit v1.2.1 From 415ea7d3b8d5217275984c80b475d4cf2da5b00d Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 2 Aug 2002 03:34:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@441 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 62412811a..24be32a61 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -314,8 +314,11 @@ __ rst/alternatives.html#or-not-to-do non-alphanumeric non-whitespace character. - Decide whether or not to implement Simon Budig's "inline external - targets" syntax idea, and if so, how (pragma directive or full-blown - addition to the spec & parser). + targets" syntax idea, and if so, how: + + - regular directive affecting its indented text block + - pragma directive affecting the entire document + - or a full-blown addition to the spec & parser - Add support for pragma (syntax-altering) directives. @@ -883,6 +886,20 @@ structure is recommended:: # code and tools/ files into the right # places in Docutils. + +Release Checklist +================= + +* Edit the version number in the following files: + + + docutils: + + - setup.py + - HISTORY.txt + - docutils/__init__.py + + + web: index.txt + .. Local Variables: -- cgit v1.2.1 From 8a3f3452d5f1810da1d6fe284baf1e98edc6e974 Mon Sep 17 00:00:00 2001 From: goodger Date: Sat, 3 Aug 2002 19:14:40 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@450 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 24be32a61..e4d0cc69f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -586,9 +586,6 @@ HTML Writer - Add more support for elements, especially for navigation bars. -- "name" attributes only on these tags: a, applet, form, frame, - iframe, img, map. - Front-End Tools --------------- -- cgit v1.2.1 From c0b162dca2a7e9a61d57ad46aa444b025a1e650b Mon Sep 17 00:00:00 2001 From: goodger Date: Mon, 5 Aug 2002 16:55:05 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@458 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e4d0cc69f..8814a4524 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -50,6 +50,10 @@ 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? + General ------- @@ -341,8 +345,6 @@ Directives - _`parts.citations`: See `Footnote & Citation Gathering`_. - - _`parts.topic` (maybe "body.topic") - - _`parts.sectnum` (section numbering; add support to .contents; could be cmdline option also) @@ -381,6 +383,8 @@ Directives problem similar to the first problem listed for misc.encoding_, although to a lesser degree. + - _`body.topic` + - _`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?) @@ -490,7 +494,65 @@ Directives - _`body.example`: Examples; suggested by Simon Hefti. Semantics as per Docbook's "example"; admonition-style, numbered, reference, - with a caption/title. (Maybe "admonitions.example"?) + with a caption/title. + + - _`body.index`: Index targets. + + Were I writing a book with an index, I guess I'd need two + different kinds of index tags: 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. + + 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:: + + .. index:: markup; syntax + + Semicolons instead of commas because commas could *be* part of the + index entry, like:: + + .. index:: van Rossum, Guido + + 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. 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. - _`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 5db282bc4ae30b9d4a53010c7e1a231ba1bbcbc9 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 6 Aug 2002 03:58:55 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@461 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 8814a4524..737e4533e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -54,6 +54,27 @@ Bugs 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. + + The only problem is, what about this? :: + + 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. + + 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.) + General ------- @@ -116,6 +137,12 @@ 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. + +- @@@ Add a transform to remove body-level targets from the doctree, + as the first stage of optimization. + Specification ------------- @@ -383,7 +410,7 @@ Directives problem similar to the first problem listed for misc.encoding_, although to a lesser degree. - - _`body.topic` + - @@@ _`body.topic` - _`body.qa` (directive a.k.a. "faq", "questions"): Questions & Answers. Implement as a generic two-column marked list? As a @@ -642,12 +669,15 @@ 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 elements, especially for navigation bars. +- @@@ Add ```` around chunks of text in inline + literals, and a "whitespace: pre" style to the stylesheet. + Front-End Tools --------------- -- cgit v1.2.1 From 1981123ec5a63f9d98ee3b8d8433e7d1cab3b021 Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 7 Aug 2002 01:25:26 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@474 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 737e4533e..7649fb083 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -140,9 +140,6 @@ General - @@@ Add references to the user docs: bugs to the SF bug tracker, questions to the mailing lists. -- @@@ Add a transform to remove body-level targets from the doctree, - as the first stage of optimization. - Specification ------------- @@ -410,8 +407,6 @@ Directives problem similar to the first problem listed for misc.encoding_, although to a lesser degree. - - @@@ _`body.topic` - - _`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?) @@ -675,9 +670,6 @@ HTML Writer - Add more support for elements, especially for navigation bars. -- @@@ Add ```` around chunks of text in inline - literals, and a "whitespace: pre" style to the stylesheet. - Front-End Tools --------------- -- 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 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 54 insertions(+), 18 deletions(-) (limited to 'docs/dev/todo.txt') 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` -- cgit v1.2.1 From 917d3af9d29ddb8b0bf284ccc1cb30e1b17052b1 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 `__. - 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 07dc5b490583921a0cc62654ed4a0e37c1bea9d9 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 16a36a0e2ef919331cabb32a76f987741eed1909 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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/dev/todo.txt') 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 84d492dd0ac01d6f187f7871670305f6ed5024e1 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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:: - - - - - - 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 `, 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 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/dev/todo.txt') 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 ac8f51c8f6be541125dbd57742b7a43ff0acaeb8 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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:: - `` 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:: `` 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 13ed20d392cc6c5e727344dad0c3aca8cea125f1 Mon Sep 17 00:00:00 2001 From: goodger 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 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From da1ed9c59bcc92e21b45ed894c8850d669b508d0 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 473739633ba059db86d233b2b383bc0108d65083 Mon Sep 17 00:00:00 2001 From: goodger 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 --------------------------------------------- 1 file changed, 45 deletions(-) (limited to 'docs/dev/todo.txt') 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 ================ -- cgit v1.2.1 From 80f8cc03017c6845f8a1bb41871caf13b3d04022 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') 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. -- cgit v1.2.1 From abfba76cb86e08408273238e2af0ace0e5d04827 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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 49373e9eff9b650bd989452f2067cf2b78a5cebe Mon Sep 17 00:00:00 2001 From: goodger 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 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) (limited to 'docs/dev/todo.txt') 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 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 ================ -- cgit v1.2.1 From 2ba8fffc2b3bf0e74aedfd33533f10a54a5b77be Mon Sep 17 00:00:00 2001 From: goodger 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 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/dev/todo.txt') 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 ------------- -- cgit v1.2.1 From 30c9c811f9bc05a1a2e88252668eaf14a73a9107 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 elements, especially for navigation bars. +- ```` tags should be XML empty tags: ````. + 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 c2291595af5c117f10061fd9bf68fa0ff69d74fa Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 1e92920c6d84d99f6c6009f1e024260eec434914 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 e1d2f1face2a58f022aa0bb0e9b3b6fb11adf900 Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From 2570dd555418b4a1402dc828a5a6f5a158ea29fe Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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/dev/todo.txt') 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 elements, especially for navigation +* Add more support for elements, especially for navigation bars. -- ```` tags should be XML empty tags: ````. +* ```` tags should be XML empty tags: ````. 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 a9be40d6b5f5902c3b68e4416553fef4583cd7a6 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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:: `` 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 elements, especially for navigation bars. -* ```` tags should be XML empty tags: ````. - Front-End Tools --------------- -- cgit v1.2.1 From e11dfe778b470ccb244767b6f9f2c959db6bec82 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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:: -- cgit v1.2.1 From 58036bb54a184a823272be8ddf5f52c619d4f83c Mon Sep 17 00:00:00 2001 From: goodger 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 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') 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. -- cgit v1.2.1 From 7413a2c5688f098e12539710604fa046ed41b0c2 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 71cd002d07424cfa16059a3069f16bc4efac13a1 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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/dev/todo.txt') 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 element, containing the + book 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 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 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) (limited to 'docs/dev/todo.txt') 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 ------------- -- 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 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') 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" -- 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/dev/todo.txt') 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/dev/todo.txt') 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 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 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) (limited to 'docs/dev/todo.txt') 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 ------------- -- cgit v1.2.1 From afeedfb343c2904e9357997d2a50f8f3cabb2568 Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++++++++++++++++++++--------------------------- 1 file changed, 24 insertions(+), 27 deletions(-) (limited to 'docs/dev/todo.txt') 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 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? -- cgit v1.2.1 From e1118b87d660565cdafe0f321adf2bd2fcbe03e9 Mon Sep 17 00:00:00 2001 From: goodger 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 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From a714d9a65946eaec2c775e27e24159ce65ce10a1 Mon Sep 17 00:00:00 2001 From: goodger 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 ++----------------------------------------------------- 1 file changed, 3 insertions(+), 95 deletions(-) (limited to 'docs/dev/todo.txt') 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 ----------------------- -- cgit v1.2.1 From 35a1beda765cd44715a9ea7c4064d71b1abbcf1e Mon Sep 17 00:00:00 2001 From: goodger 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 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') 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. -- cgit v1.2.1 From 15e81d9c0111d33107133b79089a21561e398ed9 Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From b2f5d8df179415896167ddbf22d25cdd12769758 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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/dev/todo.txt') 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 f290510ad2f164c0ef773ca098eae21274bcbd9f Mon Sep 17 00:00:00 2001 From: goodger 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 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs/dev/todo.txt') 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 elements, especially for navigation bars. +* Make the admonitions more distinctive and varied. + Front-End Tools --------------- -- cgit v1.2.1 From 47e460c659b1e295d43604762eff2e9147d7df6c Mon Sep 17 00:00:00 2001 From: goodger 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 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/dev/todo.txt') 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 ------------- -- cgit v1.2.1 From 0b5556688eb293cdd373a5cf0cd3ee5af5842b8a Mon Sep 17 00:00:00 2001 From: goodger 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/todo.txt | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) (limited to 'docs/dev/todo.txt') 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 9db0294f3fb56bc3b4055eaf2cd79f0d25b527fa Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) (limited to 'docs/dev/todo.txt') 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 `````````` -- cgit v1.2.1 From 77f2ee4872ec99a61ca1756c2dad1be556877a3a Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 bd499ef3acf8d89237b20bcd6bea9e268eeb0cf3 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 `__ 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:: :global: - - Ordinary paragraphs ... - - This is an anonymous `reference `__ of one word ("reference"). Here is a - `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 4ea8903f17cf86452afef915296820e8c7d8225f Mon Sep 17 00:00:00 2001 From: goodger 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 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/dev/todo.txt') 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 ------------- -- cgit v1.2.1 From fe4f32cd84affa9cb4cef45cb96d50e899fa17fb Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 673c882e62ff706d8706218bfe74c203c46c87f5 Mon Sep 17 00:00:00 2001 From: goodger 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/todo.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') 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 a4237939cd9815ee1f487ffab293398b843a6e25 Mon Sep 17 00:00:00 2001 From: goodger 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 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/dev/todo.txt') 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 element. Part of the ht2html implementation? + * Add more support for 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.

. + Front-End Tools --------------- -- cgit v1.2.1 From 3b2fad8136d9ba7c4db32426eb96f62640b14323 Mon Sep 17 00:00:00 2001 From: goodger 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 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/dev/todo.txt') 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. -- cgit v1.2.1 From 623794723f5a6b489d395cc4c41e9eea22818575 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 ae5fd4a5e4f398a38b52b712b4a19ad8416139e3 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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
. - - 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.

. +* 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 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/dev/todo.txt') 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 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/todo.txt | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') 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 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/dev/todo.txt') 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 13681f75fbe4e198808988aa4dc962524e89fbcf Mon Sep 17 00:00:00 2001 From: goodger 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/todo.txt | 125 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 100 insertions(+), 25 deletions(-) (limited to 'docs/dev/todo.txt') 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 , +, , , 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 ``reST``. 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 ================ -- cgit v1.2.1 From 16979155f8d713326c1a9d5887372c7366196d7c Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') 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: -- cgit v1.2.1 From 76a8bdd027af6103076ae78b50ab5e9f64320153 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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/dev/todo.txt') 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 1c87d959eb6be73667ca61bbb48d69b075a846df Mon Sep 17 00:00:00 2001 From: goodger 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/todo.txt | 30 ------------------------------ 1 file changed, 30 deletions(-) (limited to 'docs/dev/todo.txt') 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
. - - 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 -- cgit v1.2.1 From 98eab0e0fa0239ad300d565a7a2677143252689f Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 6a44b80fbc36df0065293b936d526e31f7267dea Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 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 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/dev/todo.txt') 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 element. Part of the ht2html implementation? + of the 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 elements, especially for navigation bars. -- cgit v1.2.1 From 26600cb16f6e77aa8584ffe0a8938a6fb5c7d3f3 Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 85926fa8addd84c3d6411d73039a5bf1c6bc196d Mon Sep 17 00:00:00 2001 From: goodger 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 +++ 1 file changed, 3 insertions(+) (limited to 'docs/dev/todo.txt') 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 -- cgit v1.2.1 From 44975befa49fd1a2283b53a2e429faf084b5a8bf Mon Sep 17 00:00:00 2001 From: goodger 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/dev/todo.txt') 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 e95205d5c5b9aef0c7742a47e4c97213e844dffd Mon Sep 17 00:00:00 2001 From: goodger 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 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 298 insertions(+), 6 deletions(-) (limited to 'docs/dev/todo.txt') 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 + . + +* 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: + + + print 'This is Python code.' + for i in range(10): + print i + + + into something like this ("" is end-tag shorthand): + + + print 'This is Python code.' + for i in + range(10): + print i + + + But I'm leaning toward adding a single new general-purpose + element, "phrase", equivalent to HTML's . Here's the + example rewritten using the generic "phrase": + + + print 'This is Python code.' + for i in range(10): + print i + + + 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? + -like element? Put "interpreted" back for such purposes? I + currently like "phrase". But: + + ...my penny on : I think is inherently evil. More + than enough I learned to hate because some HTML pages are + full of it and it is a pain to translate them to a useful + format. + + I think is an indication that you don't have a concept + for what you want to express. 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 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 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 -- 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/todo.txt | 72 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 48 insertions(+), 24 deletions(-) (limited to 'docs/dev/todo.txt') 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? :: -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/todo.txt | 66 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 20 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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/todo.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/dev/todo.txt') 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/ -- 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 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/todo.txt') 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 ------------- -- 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/dev/todo.txt') 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 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 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) (limited to 'docs/dev/todo.txt') 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. .. -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) (limited to 'docs/dev/todo.txt') 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 ------------- -- 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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 ------------------------------------------------------- 1 file changed, 84 deletions(-) (limited to 'docs/dev/todo.txt') 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? -- 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 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) (limited to 'docs/dev/todo.txt') 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>_ -- 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/dev/todo.txt') 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 -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs/dev/todo.txt') 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, -- 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/dev/todo.txt') 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 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') 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``. -- 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs/dev/todo.txt') 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 ------- -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/todo.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/dev/todo.txt') 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/dev/todo.txt') 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 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/todo.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/dev/todo.txt') 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? -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 e9ae298f5a66bc749ae98c49fe4583a42a6bf5e8 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 14 Jun 2004 01:06:58 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2267 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5933e9d82..5e42d449f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1048,6 +1048,8 @@ when used in a document. For a specific application, see the discussion of `character entity substitution definition files`_ above. + - _`misc.raw`: "encoding" option? + - _`misc.class`: @@@ Allow multiple classes (whitespace-separated) to be declared. -- cgit v1.2.1 From c4390021ead2b93640894f762c36d9b48e05285e Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 14 Jun 2004 16:28:44 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2276 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5e42d449f..00fe606c2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1048,6 +1048,9 @@ when used in a document. For a specific application, see the discussion of `character entity substitution definition files`_ above. + Instead of C-include "<syntax>", perhaps a new "include-sys" + directive? + - _`misc.raw`: "encoding" option? - _`misc.class`: @@@ Allow multiple classes (whitespace-separated) -- cgit v1.2.1 From 8a119fb37a1379f1a45573c9cfa9975f8febf354 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 14 Jun 2004 20:05:28 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2280 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 00fe606c2..1b264c70f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -866,7 +866,7 @@ __ rst/alternatives.html#or-not-to-do .. _name: ^url -* Allow transitions between sections? A transition immediately +* 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 -- cgit v1.2.1 From 4b369e8429eda7417467f59a9138421872b3549d Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 19 Jun 2004 15:32:19 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2313 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 1b264c70f..fd597c92d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1109,12 +1109,14 @@ when used in a document. .. include:: {includepath}/charents.txt - - Docutils already has the ability to say "use this content for + - .. _conditional directives: + + Docutils already has the ability to say "use this content for Writer X" (via the "raw" directive), but it doesn't have the ability to say "use this content for any Writer other than X". It wouldn't be difficult to add this ability though. - My first idea would be to add a set of _`conditional directives`. + 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 862ba78b55fa4f947753b65a2b53eb9844b891a0 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 20 Jun 2004 08:22:13 +0000 Subject: csv-table compatibility git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2318 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fd597c92d..6b4aeba94 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -363,6 +363,8 @@ 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. + Documentation ============= -- cgit v1.2.1 From 6d9a2d6b6cd4017aad5061036b520ef2b193b4ad Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 20 Jun 2004 11:41:04 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2319 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 6b4aeba94..40a66e74e 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -369,24 +369,22 @@ General Documentation ============= -* User docs. What's needed? +User Docs +--------- + +What else is needed? Implementation Docs ------------------- -* Internal module documentation (docstrings). +* Improve the internal module documentation (docstrings in the code). + Specific deficiencies to be listed below. * docs/ref/doctree.txt: DTD element structural relationships, semantics, and attributes. In progress; element descriptions to be completed. -* How-to docs: In docs/howto/. - - - How a Writer works & how to write one - - - Transforms - * Document the ``pending`` elements, how they're generated and what they do. @@ -395,9 +393,25 @@ Implementation Docs * Document the HTML classes used by html4css1.py. +* Write an overview of the Docutils architecture, as an introduction + for developers. What connects to what, why, and how. Either update + PEP 258 (see PEPs_ below) or as a separate doc. + + +How-Tos +------- + +* Creating Docutils Writers + +* Creating Docutils Readers + +* Creating Docutils Transforms + +* Creating Docutils Parsers + -Specification -------------- +PEPs +---- * Complete PEP 258 Docutils Design Specification. -- cgit v1.2.1 From b8ad9d899570b959a43863456915a94e412058fd Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 20 Jun 2004 12:07:12 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2320 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 40a66e74e..29c59a55a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -379,7 +379,13 @@ Implementation Docs ------------------- * Improve the internal module documentation (docstrings in the code). - Specific deficiencies to be listed below. + Specific deficiencies listed below. + + - docutils.parsers.rst.states.State.build_table: data structure required + (including StringList). + + - docutils.parsers.rst.states: more complete documentation of parser + internals. * docs/ref/doctree.txt: DTD element structural relationships, semantics, and attributes. In progress; element descriptions to be -- cgit v1.2.1 From 5b0a08da505813b51e174ad9034dee98b480816a Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 20 Jun 2004 12:28:08 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2321 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 29c59a55a..e88d0c350 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -378,8 +378,8 @@ What else is needed? Implementation Docs ------------------- -* 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). -- cgit v1.2.1 From 29c8c42a01aaabf8a3f5ccbdb6ac05cb774a5ba1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 21 Jun 2004 12:02:07 +0000 Subject: moved line number bug from docs/dev/todo.txt to BUGS.txt git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2339 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e88d0c350..60d0fa116 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -748,9 +748,6 @@ __ rst/alternatives.html#or-not-to-do 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. -- cgit v1.2.1 From 009c2d3943f0d7cba80af8f95b6ad84c5feb1c16 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 21 Jun 2004 14:17:15 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2342 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 60d0fa116..c3ce516ce 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -19,7 +19,11 @@ the priority. Items in question form (containing "?") are ideas which require more thought and debate; they are potential to-do's. Many of these items are awaiting champions. If you see something -you'd like to tackle, please do! +you'd like to tackle, please do! If there's something you'd like to +see done but are unable to implement it yourself, `please consider +contributing`__ in other ways. + +__ http://docutils.sf.net/#please-contribute Priorities -- cgit v1.2.1 From bc40dde3c19ff4cc2a37eb8a8f6ab994092e158f Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 21 Jun 2004 14:37:10 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2343 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index c3ce516ce..98791e0e2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -946,6 +946,24 @@ __ rst/alternatives.html#or-not-to-do after the fact, so order can't be relied upon there. So they have to be two independent settings. +* Enable _`tables inside XML comments`, where "--" ends comments. I + see three implementation possibilities: + + 1. Make the table syntax characters into "table" directive options. + This is the most flexible but most difficult, and we probably + don't need that much flexibility. + + 2. Substitute "~" for "-" with a specialized directive option + (e.g. ":tildes:"). + + 3. Make the standard table syntax recognize "~" as well as "-", even + without a directive option. Individual tables would have to be + internally consistent. + + Directive options are preferable to configuration settings, because + tables are document-specific. A pragma directive would be another + approach, to set the syntax once for a whole document. + Directives ---------- -- cgit v1.2.1 From 5e1547422edb1074dfe6c2bacfc1d0c24d4bc6e5 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Jun 2004 14:05:57 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2373 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 98791e0e2..45fccc46b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -37,8 +37,10 @@ Priorities setup.py install them. * 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! + added. See the document `"Plan for Enthought API Documentation + Tool"`__ for details. If you'd like to help, let me know! + + __ enthought-plan.html General @@ -77,9 +79,6 @@ General * Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -* 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 @@ -244,7 +243,7 @@ General As I said earlier in chapter :chapter:`objects`, the reference count gets increased every time a binding is made. -* Add functional testing to Docutils: Readers, Writers, front ends. +* Add testing to Docutils front ends? * Changes to sandbox/davidg/infrastructure/docutils-update? @@ -367,7 +366,10 @@ 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. +* 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 Documentation -- cgit v1.2.1 From 6ff0ce12b3ac99dd48b68ba638e5a6648916788c Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Jun 2004 18:21:21 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2375 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 45fccc46b..4920c08c1 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -243,7 +243,7 @@ General As I said earlier in chapter :chapter:`objects`, the reference count gets increased every time a binding is made. -* Add testing to Docutils front ends? +* Add testing for Docutils' front end tools? * Changes to sandbox/davidg/infrastructure/docutils-update? -- cgit v1.2.1 From 86e1b40edc0e10dbf6c33aa2e2a0eb826058f15f Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Jun 2004 21:28:02 +0000 Subject: docs/dev/todo.txt git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2379 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 4920c08c1..81e8a1ba8 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -381,8 +381,8 @@ User Docs What else is needed? -Implementation Docs -------------------- +Developer Docs +-------------- * @@@ Improve the internal module documentation (docstrings in the code). Specific deficiencies listed below. @@ -409,6 +409,8 @@ Implementation Docs for developers. What connects to what, why, and how. Either update PEP 258 (see PEPs_ below) or as a separate doc. +* Give information about unit tests. Maybe as a howto? + How-Tos ------- @@ -451,7 +453,7 @@ General: * Investigate how POD handles literate programming. -* Take the best ideas and integrate them into Docutils 0.3. +* Take the best ideas and integrate them into Docutils. Miscellaneous ideas: -- cgit v1.2.1 From 8b7034e7ec7b523bb59e6e1e25c2e8220280e1f1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Jun 2004 21:48:52 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2382 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 81e8a1ba8..5b38ad780 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -384,11 +384,13 @@ What else is needed? Developer Docs -------------- +* The settings/options system. + * @@@ Improve the internal module documentation (docstrings in the code). Specific deficiencies listed below. - - docutils.parsers.rst.states.State.build_table: data structure required - (including StringList). + - docutils.parsers.rst.states.State.build_table: data structure + required (including StringList). - docutils.parsers.rst.states: more complete documentation of parser internals. @@ -409,8 +411,6 @@ Developer Docs for developers. What connects to what, why, and how. Either update PEP 258 (see PEPs_ below) or as a separate doc. -* Give information about unit tests. Maybe as a howto? - How-Tos ------- @@ -423,6 +423,8 @@ How-Tos * Creating Docutils Parsers +* Using Docutils as a Library + PEPs ---- -- cgit v1.2.1 From 248c7ef18a61ebee4520ecdd451b792f6ac42eb9 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 25 Jun 2004 22:52:32 +0000 Subject: whoops! restored git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2386 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 5b38ad780..3814c665d 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -411,6 +411,8 @@ Developer Docs for developers. What connects to what, why, and how. Either update PEP 258 (see PEPs_ below) or as a separate doc. +* Give information about unit tests. Maybe as a howto? + How-Tos ------- -- cgit v1.2.1 From 2db7f6a8b77ebc75425efcebb97ac9c7a841c3a1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 28 Jun 2004 19:18:48 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2409 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3814c665d..2c9ddb294 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -384,7 +384,7 @@ What else is needed? Developer Docs -------------- -* The settings/options system. +* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_. * @@@ Improve the internal module documentation (docstrings in the code). Specific deficiencies listed below. -- cgit v1.2.1 From 83ee6f8cc16e4a7107fa0bf3cd87bdf981b949eb Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Mon, 28 Jun 2004 19:42:03 +0000 Subject: moved doctitle-should-be-target bug to 'reStructuredText Parser' section of todo.txt git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2411 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2c9ddb294..7c6767d00 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -558,6 +558,8 @@ __ 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 -- cgit v1.2.1 From 7e9faf43c8bf76f62a668279532136d3707bba77 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 2 Jul 2004 16:24:17 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2419 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 7c6767d00..e0aace32b 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -371,6 +371,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]``? + Documentation ============= @@ -413,6 +418,8 @@ Developer Docs * Give information about unit tests. Maybe as a howto? +* Document the docutils.nodes APIs. + How-Tos ------- -- cgit v1.2.1 From c646de05dbaa7f4acf1cfa7aa95d22bd3f6ec366 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Jul 2004 13:54:09 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2429 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e0aace32b..a98777d98 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -376,6 +376,14 @@ General string or an integer). Replace with ``node[int]`` and ``node.attributes[string]``? +* Add file-specific settings support to config files, like:: + + [file index.txt] + compact-lists: no + + Is this even possible? Should the criterion be the name of the + input file or the output file? + Documentation ============= -- cgit v1.2.1 From 95422f640fd1bb0f45b09062068d5bb5dbb57582 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Fri, 16 Jul 2004 23:13:51 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2436 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a98777d98..f0cebd2d2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -29,6 +29,10 @@ __ http://docutils.sf.net/#please-contribute Priorities ========== +Always high priority: `FIX BUGS!`__ + +__ ../../BUGS.html + * Include substitution files for character entities, produced by the tools/unicode2rstsubs.py. As static data, these files could go inside the docutils package somewhere. @@ -42,6 +46,8 @@ Priorities __ enthought-plan.html +* `Nested inline markup`_. + General ======= @@ -384,6 +390,14 @@ General Is this even possible? Should the criterion be the name of the input file or the output file? +* The "validator" support added to OptionParser is very similar to + "traits_" in SciPy_. Perhaps something could be done with them? + (Had I known about traits when I was implementing docutils.frontend, + I may have used them instead of rolling my own.) + + .. _traits: http://old.scipy.org/site_content/traits + .. _SciPy: http://www.scipy.org/ + Documentation ============= @@ -428,6 +442,8 @@ Developer Docs * Document the docutils.nodes APIs. +* Complete the docs/api/publisher.txt docs. + How-Tos ------- -- cgit v1.2.1 From f6621345b5dc35ffbc4e6ec6a27e141d33e0db76 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Jul 2004 16:22:32 +0000 Subject: reordered git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2439 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f0cebd2d2..f78abe63f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -29,9 +29,9 @@ __ http://docutils.sf.net/#please-contribute Priorities ========== -Always high priority: `FIX BUGS!`__ +* Always high priority: `FIX BUGS!`__ -__ ../../BUGS.html + __ ../../BUGS.html * Include substitution files for character entities, produced by the tools/unicode2rstsubs.py. As static data, these files could go @@ -61,6 +61,21 @@ General checked for correctness and refactored. I'm afraid it's a bit of a spaghetti mess now. +* Language modules: in accented languages it may be useful to have + both accented and unaccented entries in the ``bibliographic_fields`` + mapping for versatility. + +* Add a "--strict-language" option & setting: no English fallback for + language-dependent features. + +* Add internationalization to _`footer boilerplate text` (resulting + from "--generator", "--source-link", and "--date" etc.), allowing + translations. + +* Need a Unicode to HTML entities codec for HTML writer? No, the + "xmlcharrefreplace" output error handler is sufficient. + Make it the default for HTML & XML writers? + * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. * Ask Python-dev for opinions (GvR for a pronouncement) on special @@ -78,10 +93,6 @@ General 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 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.)? @@ -284,13 +295,6 @@ 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. - -* 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. The "--language" option would set both input & output @@ -316,10 +320,6 @@ General * 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 - 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, -- cgit v1.2.1 From 8b0cb425e2a4255f3bb979a50a21a214ba488a12 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 18 Jul 2004 16:46:33 +0000 Subject: xmlcharrefreplace git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2440 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f78abe63f..47f8e4eff 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -74,7 +74,8 @@ General * 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? + Make it the default for HTML & XML writers? Not as long as we need + to support Python versions prior to 2.3. * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. -- cgit v1.2.1 From 253d5324a1754ddda972807b0e2ff6303c3dbef4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sat, 24 Jul 2004 18:35:09 +0000 Subject: xmlcharrefreplace backport git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2448 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 47f8e4eff..f78abe63f 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -74,8 +74,7 @@ General * 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? Not as long as we need - to support Python versions prior to 2.3. + Make it the default for HTML & XML writers? * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. -- cgit v1.2.1 From 2121b42339c51b359ca5b269c200297ba2f4f280 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Jul 2004 12:16:51 +0000 Subject: moved double-width character bug to todo.txt git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2462 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index f78abe63f..a9b209149 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -585,6 +585,15 @@ Also see the `... Or Not To Do?`__ list. __ rst/alternatives.html#or-not-to-do +* The parser doesn't know anything about double-width characters such + as Chinese hanza & Japanese kanji/kana. Also, it's dependent on + whitespace and punctuation as markup delimiters, which may not be + applicable in these languages. + + Python 2.4 introduces the iswide() and width() string methods, so + this problem will be resolved later, when Python 2.4 is being used + more widely. + * Clean up the code; refactor as required. * Add motivation sections for constructs in spec. -- cgit v1.2.1 From 13e0ae00b90a39b4d7e859feef02b61451545e07 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Jul 2004 17:17:42 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2471 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index a9b209149..e928fa21a 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -37,9 +37,6 @@ Priorities tools/unicode2rstsubs.py. As static data, these files could go inside the docutils package somewhere. -* Rename front-end tools (perhaps to "rst2*" pattern) and have - setup.py install them. - * 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 70d29d96d61bb2ec77a682aa6dd04ade4a9bc239 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Tue, 27 Jul 2004 17:42:40 +0000 Subject: removed item about /usr/(local/)etc; is wrong git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2472 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 7 ------- 1 file changed, 7 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index e928fa21a..2bc0639bf 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -93,13 +93,6 @@ General * Perhaps the ``Component.supports`` method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? -* 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 - * Add _`object numbering and object references` (tables & figures). These would be the equivalent of DocBook's "formal" elements. -- cgit v1.2.1 From a9a5edc09ae3955029c7a96f6d50e804b1740395 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 4 Aug 2004 14:14:18 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2525 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 2bc0639bf..714598967 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -388,6 +388,15 @@ General .. _traits: http://old.scipy.org/site_content/traits .. _SciPy: http://www.scipy.org/ +* tools/buildhtml.py: Extend the --prune option ("prune" config + setting) to accept file names (generic path) in addition to + 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. + Documentation ============= @@ -1715,18 +1724,6 @@ Unimplemented Transforms HTML Writer =========== -* Construct a _`templating system`, as in ht2html/yaptu, using - directives and substitutions for dynamic stuff? Or a specialized - writer to generate .ht & links.h files for ht2html? - - This is an overly generic, ambitious, and unnecessary idea. The two - systems, ht2html & yaptu, represent different approaches to - templating. Ht2html stiches bits of HTML together to make unified - web pages. Yaptu is for generic programmable text replacement. - Templating should simply be left to other systems. Users can choose - a templating system to apply to their reStructuredText documents as - best serves their interests. - * Add more support for <link> elements, especially for navigation bars. -- cgit v1.2.1 From 4cb852d5f9884e7ebe82095b9731f6bd26623710 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 22 Aug 2004 16:05:11 +0000 Subject: iswide has been moved to unicodedata in Python 2.4 git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2536 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 714598967..9bc8ab1c2 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -589,9 +589,9 @@ __ rst/alternatives.html#or-not-to-do whitespace and punctuation as markup delimiters, which may not be applicable in these languages. - Python 2.4 introduces the iswide() and width() string methods, so - this problem will be resolved later, when Python 2.4 is being used - more widely. + 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. * Clean up the code; refactor as required. -- cgit v1.2.1 From b96b6f32f54c14a01705b0c13c36f8e25d7a93f6 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 29 Aug 2004 20:04:53 +0000 Subject: converted tabs to whitespace git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2548 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 9bc8ab1c2..fefab0dd9 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1393,9 +1393,9 @@ when used in a document. - _`body.literal`: Literal block, possibly "formal" (see `object numbering and object references`_ above). Possible options: - - "highlight" a range of lines + - "highlight" a range of lines - - "number" or "line-numbers" + - "number" or "line-numbers" - "styled" could indicate that the directive should check for style comments at the end of lines to indicate styling or @@ -1405,7 +1405,7 @@ when used in a document. could interpret style based on cues, like the ">>> " prompt and "input()"/"raw_input()" calls. - See docutils-users 2003-03-03. + See docutils-users 2003-03-03. - _`body.sidebar`: Add to the already implemented directive. Allow internal section structure, with adornment styles independent of -- cgit v1.2.1 From f3aa787d95ca9355050f76b4a849610bbeeace5c Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Wed, 8 Sep 2004 19:49:33 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2562 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index fefab0dd9..3a3e33331 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -134,6 +134,18 @@ General This may be a more general solution, equally applicable to tables. However, explicit naming using an option seems simpler to users. + - Perhaps the figure name could be incorporated into the figure + definition, as an optional inline target part of the directive + argument:: + + .. figure:: _`figure name` image.png + + Maybe with a delimiter:: + + .. figure:: _`figure name`: image.png + + Or some other, simpler syntax. + We'll also need syntax for object references. See `OpenOffice.org XML`_ "reference fields": @@ -164,6 +176,18 @@ General See `Interpreted Text`_ below. + - We could leave the boilerplate text up to the document:: + + See Figure :fig:`figure name` on page :pg:`figure name`. + + - Reference boilerplate could be specified in the document + (defaulting to nothing):: + + .. fignum:: + :prefix-ref: "Figure " + :prefix-caption: "Fig. " + :suffix-caption: : + .. _OpenOffice.org XML: http://xml.openoffice.org/ * Think about _`large documents` made up of multiple subdocument @@ -1414,6 +1438,62 @@ 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 + 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 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 bf28d9f44cf9a673129c8e17b81f225cf5607caf Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> Date: Sun, 19 Sep 2004 18:27:29 +0000 Subject: added --embed-stylesheet to todo list of LaTeX writer git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2634 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/dev/todo.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/dev/todo.txt') diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt index 3a3e33331..7c773c425 100644 --- a/docs/dev/todo.txt +++ b/docs/dev/todo.txt @@ -1832,6 +1832,12 @@ HTML Writer --> +LaTeX writer +============ + +* Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option. + + Front-End Tools =============== -- cgit v1.2.1 From 90276ab6b54a4e0eb5a4e2b273098df046d2cec1 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/dev/todo.txt') 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 2cdc5c5df80ff79387774cb8e89c982bc2cd2328 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 95 ++----------------------------------------------------- 1 file changed, 2 insertions(+), 93 deletions(-) (limited to 'docs/dev/todo.txt') 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 <statement syntax:>`, - we must remember ... - - The opposite sense could also be possible:: - - When dealing with `index entries <:multi-level>`, there are - many permutations to consider. - - Also "see / see also" index entries. - - Given:: - - Here's a paragraph. - - .. index:: paragraph - - (The "index" directive above actually targets the *preceding* - object.) The directive should produce something like this XML:: - - <paragraph> - <index_entry text="paragraph"/> - Here's a paragraph. - </paragraph> - - This kind of content model would also allow true inline - index-entries:: - - Here's a `paragraph`:index:. - - If the "index" role were the default for the application, it could be - dropped:: - - Here's a `paragraph`. - - Both of these would result in this XML:: - - <paragraph> - Here's a <index_entry>paragraph</index_entry>. - </paragraph> + 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 465c87e73035e8e8cefd444cfc7ab4fbcfbdec56 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 bb10e40d88e30feef6fc125bf172b7c9125c8124 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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:: - - <!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, - (transition, (%body.elements; | topic | sidebar)+ )*, - (transition?, (%section.elements;))* ) - | (transition?, (%section.elements;))+ ) "> - * Add an option to allow arbitrary URI schemes (not just those in urischemes.py)? This would make text like "signal:noise" into a URI. -- 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/dev/todo.txt') 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? -- 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 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') 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? -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 dbab7e3441e11bf2bed00c53314191aefa808eed Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <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: -- 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/dev/todo.txt') 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 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 ++++----------------------------------- 1 file changed, 4 insertions(+), 35 deletions(-) (limited to 'docs/dev/todo.txt') 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 -- 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/todo.txt | 439 +++++++++++++----------------------------------------- 1 file changed, 100 insertions(+), 339 deletions(-) (limited to 'docs/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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 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/dev/todo.txt') 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 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/dev/todo.txt') 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/dev/todo.txt') 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/dev/todo.txt') 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 88e05f8b6d298dc43fddbac594c413847edfa0d4 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <http://thread.gmane.org/gmane.text.docutils.user/2524>. + * Add indirect links via citation references & footnote references. Example:: -- cgit v1.2.1 From d30297348e43d04a8006c12b35f407141b499dae Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 09990717cff73a01c118f208643551e47871f032 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 2d9be866bdfd38044a368345f77d93ef9907df9c Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') 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 4daab9f9ccb5c522de264c7352bbd40ee82c34ee Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/dev/todo.txt') 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 6f185bf33fee23aab3ba57a78eeeaeb69867e400 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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. <font color="red"> <raw format="latex"> {\color{red} - text + <inline classes="red"> + text <raw format="html"> </font> <raw format="latex"> } + 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 d66e00e85902ec5667ba03392be74c625c4efeb3 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 976c10fa68fc7259c79ba878f947be0db7f0a66e Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 + <http://thread.gmane.org/gmane.text.docutils.user/2499>. + * The current list-recognition logic has too many false positives, as in :: -- cgit v1.2.1 From 5fe7c5067c6c5a2512c4d8747292041247ed4035 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 b775a81b52fedbb19c60f6b0aff673427eaa0c9e Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 - <http://thread.gmane.org/gmane.text.docutils.user/2499>. + <http://thread.gmane.org/gmane.text.docutils.user/2499> and + <http://thread.gmane.org/gmane.text.docutils.user/2443>. * The current list-recognition logic has too many false positives, as in :: -- cgit v1.2.1 From 498f4a1bb34f9b1544e7a1fe502e4f62deffdbc1 Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 + <http://thread.gmane.org/gmane.text.docutils.devel/3392>. + * .. _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 <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 + <http://article.gmane.org/gmane.text.docutils.user/2635>. + * The citation syntax could use some enhancements. See <http://thread.gmane.org/gmane.text.docutils.user/2499> and <http://thread.gmane.org/gmane.text.docutils.user/2443>. -- cgit v1.2.1 From ced6843a40a4b84b50b10c1106edfe80e088fbaa Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 e5ba1950c904e32f886b52106e876f5c7de33a7c Mon Sep 17 00:00:00 2001 From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 + <http://thread.gmane.org/gmane.text.docutils.cvs/4336>. + * Add more support for <link> 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <http://thread.gmane.org/gmane.text.docutils.devel/3392>. - + * .. _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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 44 ++++++++------------------------------------ 1 file changed, 8 insertions(+), 36 deletions(-) (limited to 'docs/dev/todo.txt') 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:: - - <!ELEMENT question_list (question_list_item+)> - <!ATTLIST question_list - numbering (none | local | global) - #IMPLIED - start NUMBER #IMPLIED> - <!ELEMENT question_list_item (question, answer*)> - <!ELEMENT question %text.model;> - <!ELEMENT answer (%body.elements;)+> - - Originally I thought of implementing a Q&A list with special - syntax:: - - Q: What am I? - - A: You are a question-and-answer - list. - - Q: What are you? - - A: I am the omniscient "we". - - Where each "Q" and "A" could also be numbered (e.g., "Q1"). - However, a simple enumerated or bulleted list will do just fine - for syntax. A directive could treat the list specially; e.g. the - first paragraph could be treated as a question, the remainder as - the answer (multiple answers could be represented by nested - lists). Without special syntax, this directive becomes low - priority. - - _`body.example`: Examples; suggested by Simon Hefti. Semantics as per Docbook's "example"; admonition-style, numbered, reference, with a caption/title. @@ -1704,6 +1668,14 @@ HTML Writer * Add support for _`multiple stylesheets`. See <http://thread.gmane.org/gmane.text.docutils.cvs/4336>. +* 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 <link> elements, especially for navigation bars. -- cgit v1.2.1 From 507cddee06eea200d202f38761c960815a814517 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 - <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 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 c2737d5c145b4715cf6ed0b4fd9362e07d50b86b Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/todo.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/dev/todo.txt') 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? -- cgit v1.2.1 From e329a521a11f62212d4504d25cb1a3c5c76dfc18 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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 ------- 1 file changed, 7 deletions(-) (limited to 'docs/dev/todo.txt') 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 <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 0b718c86ce872823b2c22f1024f8df83bff797a7 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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 8a4a3988a2cd67973071f5d774c268ed88bf3cf5 Mon Sep 17 00:00:00 2001 From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> 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/dev/todo.txt') 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:: <macros> - - Today's date is |date|. - - Where "macros" contains ``.. |date| date::``, among others. - - - _`text.time`: Timestamp. For substitutions. Shortcut for - ``.. date:: %H:%M``. Date fields can also be used. - - _`pysource.usage`: Extract a usage message from the program, either by running it at the command line with a ``--help`` option or through an exposed API. [Suggestion for Optik.] -- cgit v1.2.1