diff options
Diffstat (limited to 'docutils/docs/dev/todo.txt')
| -rw-r--r-- | docutils/docs/dev/todo.txt | 388 |
1 files changed, 0 insertions, 388 deletions
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt deleted file mode 100644 index 5c87d280d..000000000 --- a/docutils/docs/dev/todo.txt +++ /dev/null @@ -1,388 +0,0 @@ -================ - 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. - - - 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 - 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. - -- Implement a PEP reader. - -- Add support for character set encodings on input & output, Unicode - internally. Need a Unicode -> HTML entities codec for HTML writer? - - -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 -> <BR>. - - 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 (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:: - - 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. - -- Make the parser modular. Be able to turn on/off constructs, add - them at run time. Or is subclassing enough? - - -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. ``<element boolean>`` is good, ``<element - boolean="boolean">`` 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 (<HTML>?). - - - 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 <LINK>, 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. - -- 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 -================== - -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: |