5
:Author: David Goodger (with input from many); open to all Docutils
7
:Contact: goodger@python.org
8
:Date: $Date: 2005-12-23 00:46:16 +0100 (Fri, 23 Dec 2005) $
9
:Revision: $Revision: 4229 $
10
:Copyright: This document has been placed in the public domain.
12
.. _Docutils: http://docutils.sourceforge.net/
17
Priority items are marked with "@" symbols. The more @s, the higher
18
the priority. Items in question form (containing "?") are ideas which
19
require more thought and debate; they are potential to-do's.
21
Many of these items are awaiting champions. If you see something
22
you'd like to tackle, please do! If there's something you'd like to
23
see done but are unable to implement it yourself, please consider
24
donating to Docutils: |donate|
26
.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
27
:target: http://sourceforge.net/donate/index.php?group_id=38414
31
:alt: Support the Docutils project!
33
Please see also the Bugs_ document for a list of bugs in Docutils.
35
.. _bugs: ../../BUGS.html
41
We should get Docutils 0.4 out soon, but we shouldn't just cut a
42
"frozen snapshot" release. Here's a list of features (achievable in
43
the short term) to include:
45
* [DONE in rev. 3901] Move support files to docutils/writers/support.
47
* [DONE in rev. 4163] Convert ``docutils/writers/support/*`` into
48
individual writer packages.
50
* [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck
51
(no longer needed because of the above change).
53
* [DONE in rev. 3962] Incorporate new branch policy into the docs.
54
("Development strategy" thread on Docutils-develop)
56
* [DONE in rev. 4152] Added East-Asian double-width character support.
58
* [DONE in rev. 4156] Merge the S5 branch.
64
* Tag it and create a maintenance branch (perhaps "maint-0-4").
68
- Docutils 0.4.x is the last version that will support Python 2.1
71
- Docutils 0.4.x is the last version that will support (make
72
compromises for) Netscape Navigator 4
75
Minimum Requirements for Python Standard Library Candidacy
76
==========================================================
78
Below are action items that must be added and issues that must be
79
addressed before Docutils can be considered suitable to be proposed
80
for inclusion in the Python standard library.
82
* Support for `document splitting`_. May require some major code
85
* Support for subdocuments (see `large documents`_).
87
* `Object numbering and object references`_.
89
* `Nested inline markup`_.
91
* `Python Source Reader`_.
93
* The HTML writer needs to be rewritten (or a second HTML writer
94
added) to allow for custom classes, and for arbitrary splitting
97
* Documentation_ of the architecture. Other docs too.
101
* A LaTeX writer making use of (La)TeX's power, so that the rendering
102
of the resulting documents is more easily customizable. (Similar to
103
what you wrote about a new HTML Writer.)
105
* Suitability for `Python module documentation
106
<http://docutils.sf.net/sandbox/README.html#documenting-python>`_.
112
* Allow different report levels for STDERR and system_messages inside
115
* Change the docutils-update script (in sandbox/infrastructure), to
116
support arbitrary branch snapshots.
118
* Add a generic "container" element, equivalent to "inline", to which
119
a "class" attribute can be attached. Will require a reST directive
122
* Move some general-interest sandboxes out of individuals'
123
directories, into subprojects?
125
* Add option for file (and URL) access restriction to make Docutils
126
usable in Wikis and similar applications.
128
2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
129
settings. These partially solve the problem, allowing or disabling
130
**all** file accesses, but not limited access.
132
* Configuration file handling needs discussion:
134
- There should be some error checking on the contents of config
135
files. How much checking should be done? How loudly should
136
Docutils complain if it encounters an error/problem?
138
- Docutils doesn't complain when it doesn't find a configuration
139
file supplied with the ``--config`` option. Should it? (If yes,
142
* Internationalization:
144
- I18n needs refactoring, the language dictionaries are difficult to
145
maintain. Maybe have a look at gettext or similar tools.
147
- Language modules: in accented languages it may be useful to have
148
both accented and unaccented entries in the
149
``bibliographic_fields`` mapping for versatility.
151
- Add a "--strict-language" option & setting: no English fallback
152
for language-dependent features.
154
- Add internationalization to _`footer boilerplate text` (resulting
155
from "--generator", "--source-link", and "--date" etc.), allowing
158
* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
160
* In ``docutils.readers.get_reader_class`` (& ``parsers`` &
161
``writers`` too), should we be importing "standalone" or
162
"docutils.readers.standalone"? (This would avoid importing
163
top-level modules if the module name is not in docutils/readers.
164
Potential nastiness.)
166
* Perhaps store a _`name-to-id mapping file`? This could be stored
167
permanently, read by subsequent processing runs, and updated with
168
new entries. ("Persistent ID mapping"?)
170
* Perhaps the ``Component.supports`` method should deal with
171
individual features ("meta" etc.) instead of formats ("html" etc.)?
173
* Add _`object numbering and object references` (tables & figures).
174
These would be the equivalent of DocBook's "formal" elements.
176
We may need _`persistent sequences`, such as chapter numbers. See
177
`OpenOffice.org XML`_ "fields". Should the sequences be automatic
178
or manual (user-specifyable)?
180
We need to name the objects:
182
- "name" option for the "figure" directive? ::
184
.. figure:: image.png
187
Same for the "table" directive::
189
.. table:: optional title here
199
This would also allow other options to be set, like border
200
styles. The same technique could be used for other objects.
202
A preliminary "table" directive has been implemented, supporting
203
table titles. Perhaps the name should derive from the title.
205
- The object could also be done this way::
209
.. figure:: image.png
211
This may be a more general solution, equally applicable to tables.
212
However, explicit naming using an option seems simpler to users.
214
- Perhaps the figure name could be incorporated into the figure
215
definition, as an optional inline target part of the directive
218
.. figure:: _`figure name` image.png
220
Maybe with a delimiter::
222
.. figure:: _`figure name`: image.png
224
Or some other, simpler syntax.
226
We'll also need syntax for object references. See `OpenOffice.org
227
XML`_ "reference fields":
229
- Parameterized substitutions? For example::
231
See |figure (figure name)| on |page (figure name)|.
233
.. |figure (name)| figure-ref:: (name)
234
.. |page (name)| page-ref:: (name)
236
The result would be::
238
See figure 3.11 on page 157.
240
But this would require substitution directives to be processed at
241
reference-time, not at definition-time as they are now. Or,
242
perhaps the directives could just leave ``pending`` elements
243
behind, and the transforms do the work? How to pass the data
244
through? Too complicated.
246
- An interpreted text approach is simpler and better::
248
See :figure:`figure name` on :page:`figure name`.
250
The "figure" and "page" roles could generate appropriate
251
boilerplate text. The position of the role (prefix or suffix)
252
could also be utilized.
254
See `Interpreted Text`_ below.
256
- We could leave the boilerplate text up to the document::
258
See Figure :fig:`figure name` on page :pg:`figure name`.
260
- Reference boilerplate could be specified in the document
261
(defaulting to nothing)::
264
:prefix-ref: "Figure "
265
:prefix-caption: "Fig. "
268
.. _OpenOffice.org XML: http://xml.openoffice.org/
270
* Think about _`large documents` made up of multiple subdocument
271
files. Issues: continuity (`persistent sequences`_ above),
272
cross-references (`name-to-id mapping file`_ above and `targets in
273
other documents`_ below), splitting (`document splitting`_ below).
275
When writing a book, the author probably wants to split it up into
276
files, perhaps one per chapter (but perhaps even more detailed).
277
However, we'd like to be able to have references from one chapter to
278
another, and have continuous numbering (pages and chapters, as
279
applicable). Of course, none of this is implemented yet. There has
280
been some thought put into some aspects; see `the "include"
281
directive`__ and the `Reference Merging`_ transform below.
283
When I was working with SGML in Japan, we had a system where there
284
was a top-level coordinating file, book.sgml, which contained the
285
top-level structure of a book: the <book> element, containing the
286
book <title> and empty component elements (<preface>, <chapter>,
287
<appendix>, etc.), each with filename attributes pointing to the
288
actual source for the component. Something like this::
291
<title>Title of the Book</title>
292
<preface inrefid="pr01"></preface>
293
<chapter inrefid="ch01"></chapter>
294
<chapter inrefid="ch02"></chapter>
295
<chapter inrefid="ch03"></chapter>
296
<appendix inrefid="ap01"></appendix>
299
(The "inrefid" attribute stood for "insertion reference ID".)
301
The processing system would process each component separately, but
302
it would recognize and use the book file to coordinate chapter and
303
page numbering, and keep a persistent ID to (title, page number)
304
mapping database for cross-references. Docutils could use a similar
305
system for large-scale, multipart documents.
307
__ ../ref/rst/directives.html#including-an-external-document-fragment
323
As I said earlier in chapter :chapter:`Objects.txt`, the
324
reference count gets increased every time a binding is made.
328
As I said earlier in chapter 2, the
329
reference count gets increased every time a binding is made.
331
The ToC in this form doesn't even need to be references to actual
332
reST documents; I'm simply doing it that way for a minimum of
333
future-proofing, in case I do want to add the ability to pick up
334
references within external chapters.
336
Perhaps, instead of ToC (which would overload the "contents"
337
directive concept already in use), we could use "manifest". A
338
"manifest" directive might associate local reference names with
342
intro: Introduction.txt
347
Then the sample becomes::
349
.. include:: manifest.txt
351
As I said earlier in chapter :chapter:`objects`, the
352
reference count gets increased every time a binding is made.
354
* Add support for _`multiple output files`.
356
* Add testing for Docutils' front end tools?
358
* Publisher: "Ordinary setup" shouldn't requre specific ordering; at
359
the very least, there ought to be error checking higher up in the
362
``Publisher.get_settings`` requires that all components be set up
363
before it's called. Perhaps the I/O *objects* shouldn't be set, but
364
I/O *classes*. Then options are set up (``.set_options``), and
365
``Publisher.set_io`` (or equivalent code) is called with source &
366
destination paths, creating the I/O objects.
368
Perhaps I/O objects shouldn't be instantiated until required. For
369
split output, the Writer may be called multiple times, once for each
370
doctree, and each doctree should have a separate Output object (with
371
a different path). Is the "Builder" pattern applicable here?
373
* Perhaps I/O objects should become full-fledged components (i.e.
374
subclasses of ``docutils.Component``, as are Readers, Parsers, and
375
Writers now), and thus have associated option/setting specs and
378
* Multiple file I/O suggestion from Michael Hudson: use a file-like
379
object or something you can iterate over to get file-like objects.
381
* Add an "--input-language" option & setting? Specify a different
382
language module for input (bibliographic fields, directives) than
383
for output. The "--language" option would set both input & output
386
* Auto-generate reference tables for language-dependent features?
387
Could be generated from the source modules. A special command-line
388
option could be added to Docutils front ends to do this. (Idea from
391
* Enable feedback of some kind from internal decisions, such as
392
reporting the successful input encoding. Modify runtime settings?
393
System message? Simple stderr output?
395
* Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
397
* Merge docs/user/latex.txt info into tools.txt and config.txt.
399
* Add an "--include file" command-line option (config setting too?),
400
equivalent to ".. include:: file" as the first line of the doc text?
401
Especially useful for character entity sets, text transform specs,
404
* Parameterize the Reporter object or class? See the `2004-02-18
405
"rest checking and source path"`_ thread.
407
.. _2004-02-18 "rest checking and source path":
408
http://thread.gmane.org/gmane.text.docutils.user/1112
410
* Add a "disable_transforms" setting? And a dummy Writer subclass
411
that does nothing when its .write() method is called? Would allow
412
for easy syntax checking. See the `2004-02-18 "rest checking and
413
source path"`_ thread.
415
* Add a generic meta-stylesheet mechanism? An external file could
416
associate style names ("class" attributes) with specific elements.
417
Could be generalized to arbitrary output attributes; useful for HTML
418
& XMLs. Aahz implemented something like this in
419
sandbox/aahz/Effective/EffMap.py.
421
* .. _classes for table cells:
423
William Dode suggested that table cells be assigned "class"
424
attributes by columns, so that stylesheets can affect text
425
alignment. Unfortunately, there doesn't seem to be a way (in HTML
426
at least) to leverage the "colspec" elements (HTML "col" tags) by
427
adding classes to them. The resulting HTML is very verbose::
429
<td class="col1">111</td>
430
<td class="col2">222</td>
433
At the very least, it should be an option. People who don't use it
434
shouldn't be penalized by increases in their HTML file sizes.
436
Table rows could also be assigned classes (like odd/even). That
437
would be easier to implement.
439
How should it be implemented?
441
* There could be writer options (column classes & row classes) with
444
* The table directive could grow some options. Something like
445
":cell-classes: col1 col2 col3" (either must match the number of
446
columns, or repeat to fill?) and ":row-classes: odd even" (repeat
447
to fill; body rows only, or header rows too?).
449
Probably per-table directive options are best. The "class" values
450
could be used by any writer, and applying such classes to all tables
451
in a document with writer options is too broad.
453
* Add file-specific settings support to config files, like::
458
Is this even possible? Should the criterion be the name of the
459
input file or the output file?
461
* The "validator" support added to OptionParser is very similar to
462
"traits_" in SciPy_. Perhaps something could be done with them?
463
(Had I known about traits when I was implementing docutils.frontend,
464
I may have used them instead of rolling my own.)
466
.. _traits: http://code.enthought.com/traits/
467
.. _SciPy: http://www.scipy.org/
469
* tools/buildhtml.py: Extend the --prune option ("prune" config
470
setting) to accept file names (generic path) in addition to
471
directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
472
*not* be converted to HTML).
474
* Add support for _`plugins`.
476
* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
477
/etc/docutils.conf are read as configuration files. Proposal: allow
478
~/.docutils to be a a configuration *directory*, along with
479
/etc/docutils/ and ./docutils.conf/. Within these directories,
480
check for config.txt files. We can also have subdirectories here,
481
for plugins, S5 themes, components (readers/writers/parsers) etc.
483
Docutils will continue to support configuration files for backwards
486
* Add support for document decorations other than headers & footers?
487
For example, top/bottom/side navigation bars for web pages. Generic
490
Seems like a bad idea as long as it isn't independent from the ouput
491
format (for example, navigation bars are only useful for web pages).
493
* docutils_update: Check for a ``Makefile`` in a directory, and run
494
``make`` if found? This would allow for variant processing on
495
specific source files, such as running rst2s5.py instead of
498
* Add a "disable table of contents" setting? The S5 writer could set
499
it as a default. Rationale:
501
The ``contents`` (table of contents) directive must not be used
502
[in S5/HTML documents]. It changes the CSS class of headings
503
and they won't show up correctly in the screen presentation.
505
-- `Easy Slide Shows With reStructuredText & S5
506
<../user/slide-shows.html>`_
515
* Add a FAQ entry about using Docutils (with reStructuredText) on a
516
server and that it's terribly slow. See the first paragraphs in
517
<http://article.gmane.org/gmane.text.docutils.user/1584>.
519
* Add document about what Docutils has previously been used for
520
(web/use-cases.txt?).
526
* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
528
* Improve the internal module documentation (docstrings in the code).
529
Specific deficiencies listed below.
531
- docutils.parsers.rst.states.State.build_table: data structure
532
required (including StringList).
534
- docutils.parsers.rst.states: more complete documentation of parser
537
* docs/ref/doctree.txt: DTD element structural relationships,
538
semantics, and attributes. In progress; element descriptions to be
541
* Document the ``pending`` elements, how they're generated and what
544
* Document the transforms (perhaps in docstrings?): how they're used,
545
what they do, dependencies & order considerations.
547
* Document the HTML classes used by html4css1.py.
549
* Write an overview of the Docutils architecture, as an introduction
550
for developers. What connects to what, why, and how. Either update
551
PEP 258 (see PEPs_ below) or as a separate doc.
553
* Give information about unit tests. Maybe as a howto?
555
* Document the docutils.nodes APIs.
557
* Complete the docs/api/publisher.txt docs.
563
* Creating Docutils Writers
565
* Creating Docutils Readers
567
* Creating Docutils Transforms
569
* Creating Docutils Parsers
571
* Using Docutils as a Library
577
* Complete PEP 258 Docutils Design Specification.
579
- Fill in the blanks in API details.
581
- Specify the nodes.py internal data structure implementation?
583
[Tibs:] Eventually we need to have direct documentation in
584
there on how it all hangs together - the DTD is not enough
585
(indeed, is it still meant to be correct? [Yes, it is.
588
* Rework PEP 257, separating style from spec from tools, wrt Docutils?
589
See Doc-SIG from 2001-06-19/20.
597
* Analyze Tony Ibbs' PySource code.
599
* Analyze Doug Hellmann's HappyDoc project.
601
* Investigate how POD handles literate programming.
603
* Take the best ideas and integrate them into Docutils.
607
* Ask Python-dev for opinions (GvR for a pronouncement) on special
608
variables (__author__, __version__, etc.): convenience vs. namespace
609
pollution. Ask opinions on whether or not Docutils should recognize
612
* If we can detect that a comment block begins with ``##``, a la
613
JavaDoc, it might be useful to indicate interspersed section headers
614
& explanatory text in a module. For example::
616
"""Module docstring."""
629
class MyException(Exception): pass
633
* Should standalone strings also become (module/class) docstrings?
634
Under what conditions? We want to prevent arbitrary strings from
635
becomming docstrings of prior attribute assignments etc. Assume
636
that there must be no blank lines between attributes and attribute
637
docstrings? (Use lineno of NEWLINE token.)
639
Triple-quotes are sometimes used for multi-line comments (such as
640
commenting out blocks of code). How to reconcile?
642
* HappyDoc's idea of using comment blocks when there's no docstring
643
may be useful to get around the conflict between `additional
644
docstrings`_ and ``from __future__ import`` for module docstrings.
645
A module could begin like this::
647
#!/usr/bin/env python
649
# :Copyright: whatever
651
"""This is the public module docstring (``__doc__``)."""
653
# More docs, in comments.
654
# All comments at the beginning of a module could be
655
# accumulated as docstrings.
656
# We can't have another docstring here, because of the
657
# ``__future__`` statement.
659
from __future__ import division
661
Using the JavaDoc convention of a doc-comment block beginning with
662
``##`` is useful though. It allows doc-comments and implementation
665
.. _additional docstrings:
666
../peps/pep-0258.html#additional-docstrings
668
* HappyDoc uses an initial comment block to set "parser configuration
669
values". Do the same thing for Docutils, to set runtime settings on
670
a per-module basis? I.e.::
672
# Docutils:setting=value
674
Could be used to turn on/off function parameter comment recognition
675
& other marginal features. Could be used as a general mechanism to
676
augment config files and command-line options (but which takes
679
* Multi-file output should be divisible at arbitrary level.
681
* Support all forms of ``import`` statements:
683
- ``import module``: listed as "module"
684
- ``import module as alias``: "alias (module)"
685
- ``from module import identifier``: "identifier (from module)"
686
- ``from module import identifier as alias``: "alias (identifier
688
- ``from module import *``: "all identifiers (``*``) from module"
690
* Have links to colorized Python source files from API docs? And
691
vice-versa: backlinks from the colorized source files to the API
694
* In summaries, use the first *sentence* of a docstring if the first
695
line is not followed by a blank line.
698
reStructuredText Parser
699
=======================
701
Also see the `... Or Not To Do?`__ list.
703
__ rst/alternatives.html#or-not-to-do
705
* Treat enumerated lists that are not arabic and consist of only one
706
item in a single line as ordinary paragraphs. See
707
<http://article.gmane.org/gmane.text.docutils.user/2635>.
709
* The citation syntax could use some enhancements. See
710
<http://thread.gmane.org/gmane.text.docutils.user/2499> and
711
<http://thread.gmane.org/gmane.text.docutils.user/2443>.
713
* The current list-recognition logic has too many false positives, as
720
Here ``V.`` is recognized as an enumerator, which leads to
721
confusion. We need to find a solution that resolves such problems
722
without complicating the spec to much.
724
See <http://thread.gmane.org/gmane.text.docutils.user/2524>.
726
* Add indirect links via citation references & footnote references.
729
`Goodger (2005)`_ is helpful.
731
.. _Goodger (2005): [goodger2005]_
732
.. [goodger2005] citation text
734
See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
736
* Allow multiple block quotes, only separated by attributions
737
(http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.::
747
* Change the specification so that more punctuation is allowed
748
before/after inline markup start/end string
749
(http://article.gmane.org/gmane.text.docutils.cvs/3824).
751
* Complain about bad URI characters
752
(http://article.gmane.org/gmane.text.docutils.user/2046) and
753
disallow internal whitespace
754
(http://article.gmane.org/gmane.text.docutils.user/2214).
756
* Create ``info``-level system messages for unnecessarily
757
backslash-escaped characters (as in ``"\something"``, rendered as
758
"something") to allow checking for errors which silently slipped
761
* Add (functional) tests for untested roles.
763
* Add test for ":figwidth: image" option of "figure" directive. (Test
764
code needs to check if PIL is available on the system.)
766
* Add support for CJK double-width whitespace (indentation) &
767
punctuation characters (markup; e.g. double-width "*", "-", "+")?
769
* Add motivation sections for constructs in spec.
771
* Support generic hyperlink references to _`targets in other
772
documents`? Not in an HTML-centric way, though (it's trivial to say
773
``http://www.example.com/doc#name``, and useless in non-HTML
774
contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
777
* .. _adaptable file extensions:
779
In target URLs, it would be useful to not explicitly specify the
780
file extension. If we're generating HTML, then ".html" is
781
appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
782
indicate "choose the most appropriate filename extension"? For
785
.. _Another Document: another.*
787
What is to be done for output formats that don't *have* hyperlinks?
788
For example, LaTeX targeted at print. Hyperlinks may be "called
789
out", as footnotes with explicit URLs.
791
But then there's also LaTeX targeted at PDFs, which *can* have
792
links. Perhaps a runtime setting for "*" could explicitly provide
793
the extension, defaulting to the output file's extension.
795
Should the system check for existing files? No, not practical.
797
Handle documents only, or objects (images, etc.) also?
799
If this handles images also, how to differentiate between document
800
and image links? Element context (within "image")? Which image
801
extension to use for which document format? Again, a runtime
802
setting would suffice.
804
This may not be just a parser issue; it may need framework support.
806
Mailing list threads: `Images in both HTML and LaTeX`__ (especially
807
`this summary of Felix's objections`__), `more-universal links?`__,
808
`Output-format-sensitive link targets?`__
810
__ http://thread.gmane.org/gmane.text.docutils.user/1239
811
__ http://article.gmane.org/gmane.text.docutils.user/1278
812
__ http://thread.gmane.org/gmane.text.docutils.user/1915
813
__ http://thread.gmane.org/gmane.text.docutils.user/2438
815
* Implement the header row separator modification to table.el. (Wrote
816
to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
817
support for "=====" header rows. On 2001-08-17 he replied, saying
818
he'd put it on his to-do list, but "don't hold your breath".)
820
* Fix the parser's indentation handling to conform with the stricter
821
definition in the spec. (Explicit markup blocks should be strict or
824
.. XXX What does this mean? Can you elaborate, David?
826
* Make the parser modular. Allow syntax constructs to be added or
827
disabled at run-time. Subclassing is probably not enough because it
828
makes it difficult to apply multiple extensions.
830
* Generalize the "doctest block" construct (which is overly
831
Python-centric) to other interactive sessions? "Doctest block"
832
could be renamed to "I/O block" or "interactive block", and each of
833
these could also be recognized as such by the parser:
838
A block beginning with a "$ " prompt is interpreted as a shell
839
session interactive block. As with Doctest blocks, the
840
interactive block ends with the first blank line, and wouldn't
843
- Root shell sessions::
846
A block beginning with a "# " prompt is interpreted as a root
847
shell session (the user is or has to be logged in as root)
848
interactive block. Again, the block ends with a blank line.
850
Other standard (and unambiguous) interactive session prompts could
851
easily be added (such as "> " for WinDOS).
853
Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
854
"docutils feedback").
856
* The "doctest" element should go away. The construct could simply be
857
a front-end to generic literal blocks. We could immediately (in
858
0.4, or 0.5) remove the doctest node from the doctree, but leave the
859
syntax in reST. The reST parser could represent doctest blocks as
860
literal blocks with a class attribute. The syntax could be left in
861
reST for a set period of time.
863
* Add support for pragma (syntax-altering) directives.
865
Some pragma directives could be local-scope unless explicitly
866
specified as global/pragma using ":global:" options.
868
* Support whitespace in angle-bracketed standalone URLs according to
869
Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
872
.. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt
874
* Use the vertical spacing of the source text to determine the
875
corresponding vertical spacing of the output?
877
* [From Mark Nodine] For cells in simple tables that comprise a
878
single line, the justification can be inferred according to the
881
1. If the text begins at the leftmost column of the cell,
882
then left justification, ELSE
883
2. If the text begins at the rightmost column of the cell,
884
then right justification, ELSE
885
3. Center justification.
887
The onus is on the author to make the text unambiguous by adding
888
blank columns as necessary. There should be a parser setting to
889
turn off justification-recognition (normally on would be fine).
891
Decimal justification?
893
All this shouldn't be done automatically. Only when it's requested
894
by the user, e.g. with something like this::
901
Otherwise it will break existing documents.
903
* Generate a warning or info message for paragraphs which should have
904
been lists, like this one::
909
* Generalize the "target-notes" directive into a command-line option
910
somehow? See docutils-develop 2003-02-13.
912
* Allow a "::"-only paragraph (first line, actually) to introduce a
913
_`literal block without a blank line`? (Idea from Paul Moore.) ::
916
This is a literal block
918
Is indentation enough to make the separation between a paragraph
919
which contains just a ``::`` and the literal text unambiguous?
920
(There's one problem with this concession: If one wants a definition
921
list item which defines the term "::", we'd have to escape it.) It
922
would only be reasonable to apply it to "::"-only paragraphs though.
923
I think the blank line is visually necessary if there's text before
926
The text in this paragraph needs separation
927
from the literal block following::
928
This doesn't look right.
930
* Add new syntax for _`nested inline markup`? Or extend the parser to
931
parse nested inline markup somehow? See the `collected notes
932
<rst/alternatives.html#nested-inline-markup>`__.
934
* Drop the backticks from embedded URIs with omitted reference text?
935
Should the angle brackets be kept in the output or not? ::
939
Probably not worth the trouble.
941
* Add _`math markup`. We should try for a general solution, that's
942
applicable to any output format. Using a standard, such as MathML_,
943
would be best. TeX (or itex_) would be acceptable as a *front-end*
944
to MathML. See `the culmination of a relevant discussion
945
<http://article.gmane.org/gmane.text.docutils.user/118>`__.
947
Both a directive and an interpreted text role will be necessary (for
948
each markup). Directive example::
951
\alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda)
953
The same thing inline::
955
The equation in question is :itex:`\alpha_t(i) = P(O_1, O_2,
956
\dots O_t, q_t = S_i \lambda)`.
958
.. _MathML: http://www.w3.org/TR/MathML2/
959
.. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
961
* How about a syntax for alternative hyperlink behavior, such as "open
962
in a new window" (as in HTML's ``<a target="_blank">``)? Double
963
angle brackets might work for inline targets::
965
The `reference docs <<url>>`__ may be handy.
967
But what about explicit targets?
969
The MoinMoin wiki uses a caret ("^") at the beginning of the URL
970
("^" is not a legal URI character). That could work for both inline
971
and explicit targets::
973
The `reference docs <^url>`__ may be handy.
977
This may be too specific to HTML. It hasn't been requested very
980
* Add an option to add URI schemes at runtime.
982
* _`Segmented lists`::
984
: segment : segment : segment
985
: segment : segment : very long
987
: segment : segment : segment
989
The initial colon (":") can be thought of as a type of bullet
991
We could even have segment titles::
993
:: title : title : title
994
: segment : segment : segment
995
: segment : segment : segment
997
This would correspond well to DocBook's SegmentedList. Output could
998
be tabular or "name: value" pairs, as described in DocBook's docs.
1000
* Allow backslash-escaped colons in field names::
1002
:Case Study\: Event Handling: This chapter will be dropped.
1004
* _`footnote spaces`:
1006
When supplying the command line options
1007
--footnote-references=brackets and --use-latex-footnotes with the
1008
LaTeX writer (which might very well happen when using configuration
1009
files), the spaces in front of footnote references aren't trimmed.
1011
* Enable grid _`tables inside XML comments`, where "--" ends comments.
1012
I see three implementation possibilities:
1014
1. Make the table syntax characters into "table" directive options.
1015
This is the most flexible but most difficult, and we probably
1016
don't need that much flexibility.
1018
2. Substitute "~" for "-" with a specialized directive option
1021
3. Make the standard table syntax recognize "~" as well as "-", even
1022
without a directive option. Individual tables would have to be
1023
internally consistent.
1025
Directive options are preferable to configuration settings, because
1026
tables are document-specific. A pragma directive would be another
1027
approach, to set the syntax once for a whole document.
1029
In the meantime, the list-table_ directive is a good replacement for
1030
grid tables inside XML comments.
1032
.. _list-table: ../ref/rst/directives.html#list-table
1034
* Generalize docinfo contents (bibliographic fields): remove specific
1035
fields, and have only a single generic "field"?
1041
Directives below are often referred to as "module.directive", the
1042
directive function. The "module." is not part of the directive name
1043
when used in a document.
1045
* Make the _`directive interface` object-oriented
1046
(http://article.gmane.org/gmane.text.docutils.user/1871).
1048
* Allow for field lists in list tables. See
1049
<http://thread.gmane.org/gmane.text.docutils.devel/3392>.
1053
Unify table implementations and unify options of table directives
1054
(http://article.gmane.org/gmane.text.docutils.user/1857).
1056
* Allow directives to be added at run-time?
1058
* Use the language module for directive option names?
1060
* Add "substitution_only" and "substitution_ok" function attributes,
1061
and automate context checking?
1063
* Change directive functions to directive classes? Superclass'
1064
``__init__()`` could handle all the bookkeeping.
1066
* Implement options or features on existing directives:
1068
- Add a "name" option to directives, to set an author-supplied
1071
- All directives that produce titled elements should grow implicit
1072
reference names based on the titles.
1074
- Allow the _`:trim:` option for all directives when they occur in a
1075
substitution definition, not only the unicode_ directive.
1077
.. _unicode: ../ref/rst/directives.html#unicode-character-codes
1079
- _`images.figure`: "title" and "number", to indicate a formal
1082
- _`parts.sectnum`: "local"?, "refnum"
1084
A "local" option could enable numbering for sections from a
1085
certain point down, and sections in the rest of the document are
1086
not numbered. For example, a reference section of a manual might
1087
be numbered, but not the rest. OTOH, an all-or-nothing approach
1088
would probably be enough.
1090
The "sectnum" directive should be usable multiple times in a
1091
single document. For example, in a long document with "chapter"
1092
and "appendix" sections, there could be a second "sectnum" before
1093
the first appendix, changing the sequence used (from 1,2,3... to
1094
A,B,C...). This is where the "local" concept comes in. This part
1095
of the implementation can be left for later.
1097
A "refnum" option (better name?) would insert reference names
1098
(targets) consisting of the reference number. Then a URL could be
1099
of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
1100
internal references by number? Allow name-based *and*
1101
number-based ids at the same time, or only one or the other (which
1102
would the table of contents use)? Usage issue: altering the
1103
section structure of a document could render hyperlinks invalid.
1105
- _`parts.contents`: Add a "suppress" or "prune" option? It would
1106
suppress contents display for sections in a branch from that point
1107
down. Or a new directive, like "prune-contents"?
1109
Add an option to include topics in the TOC? Another for sidebars?
1110
The "topic" directive could have a "contents" option, or the
1111
"contents" directive" could have an "include-topics" option. See
1112
docutils-develop 2003-01-29.
1114
- _`parts.header` & _`parts.footer`: Support multiple, named headers
1115
& footers? For example, separate headers & footers for odd, even,
1116
and the first page of a document.
1118
This may be too specific to output formats which have a notion of
1123
- Add a ``:parent:`` option for setting the parent's class
1124
(http://article.gmane.org/gmane.text.docutils.devel/3165).
1128
- Option to select a range of lines?
1130
- Option to label lines?
1132
- How about an environment variable, say RSTINCLUDEPATH or
1133
RSTPATH, for standard includes (as in ``.. include:: <name>``)?
1134
This could be combined with a setting/option to allow
1135
user-defined include directories.
1137
- Add support for inclusion by URL? ::
1140
:url: http://www.example.org/inclusion.txt
1142
- _`misc.raw`: add a "destination" option to the "raw" directive? ::
1149
It needs thought & discussion though, to come up with a consistent
1150
set of destination labels and consistent behavior.
1152
And placing HTML code inside the <head> element of an HTML
1153
document is rather the job of a templating system.
1155
- _`body.sidebar`: Allow internal section structure? Adornment
1156
styles would be independent of the main document.
1158
That is really complicated, however, and the document model
1159
greatly benefits from its simplicity.
1161
* Implement directives. Each of the list items below begins with an
1162
identifier of the form, "module_name.directive_function_name". The
1163
directive name itself could be the same as the
1164
directive_function_name, or it could differ.
1168
It has the disadvantage that it's only easily implementable for
1169
HTML, so it's specific to one output format.
1171
(For non-HTML writers, the imagemap would have to be replaced with
1174
- _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
1176
- _`parts.citations`: See `Footnote & Citation Gathering`_.
1178
- _`misc.language`: Specify (= change) the language of a document at
1181
- _`misc.settings`: Set any(?) Docutils runtime setting from within
1182
a document? Needs much thought and discussion.
1184
- _`misc.gather`: Gather (move, or copy) all instances of a specific
1185
element. A generalization of the "endnotes" & "citations" ideas.
1187
- Add a custom "directive" directive, equivalent to "role"? For
1192
.. class:: incremental
1196
"``.. incr::``" above is equivalent to "``.. class:: incremental``".
1200
.. directive:: printed-links
1206
:class: print-inline
1208
This acts like macros. The directive contents will have to be
1209
evaluated when referenced, not when defined.
1211
* Needs a better name? "Macro", "substitution"?
1212
* What to do with directive arguments & options when the
1213
macro/directive is referenced?
1215
- .. _conditional directives:
1217
Docutils already has the ability to say "use this content for
1218
Writer X" (via the "raw" directive), but it doesn't have the
1219
ability to say "use this content for any Writer other than X". It
1220
wouldn't be difficult to add this ability though.
1222
My first idea would be to add a set of conditional directives.
1223
Let's call them "writer-is" and "writer-is-not" for discussion
1224
purposes (don't worry about implemention details). We might
1227
.. writer-is:: text-only
1243
.. figure:: protocol_stack.eps
1245
.. writer-is-not:: text-only pdf
1247
.. figure:: protocol_stack.png
1249
This could be an interface to the Filter transform
1250
(docutils.transforms.components.Filter).
1252
The ideas in `adaptable file extensions`_ above may also be
1255
SVG's "switch" statement may provide inspiration.
1257
Here's an example of a directive that could produce multiple
1258
outputs (*both* raw troff pass-through *and* a GIF, for example)
1259
and allow the Writer to select. ::
1266
%sum from i=o to inf c sup i~=~lim from {m -> inf}
1267
sum from i=0 to m sup i%
1272
- _`body.example`: Examples; suggested by Simon Hefti. Semantics as
1273
per Docbook's "example"; admonition-style, numbered, reference,
1274
with a caption/title.
1276
- _`body.index`: Index targets.
1278
See `Index Entries & Indexes
1279
<./rst/alternatives.html#index-entries-indexes>`__.
1281
- _`body.literal`: Literal block, possibly "formal" (see `object
1282
numbering and object references`_ above). Possible options:
1284
- "highlight" a range of lines
1286
- include only a specified range of lines
1288
- "number" or "line-numbers"
1290
- "styled" could indicate that the directive should check for
1291
style comments at the end of lines to indicate styling or
1294
Specific derivatives (i.e., a "python-interactive" directive)
1295
could interpret style based on cues, like the ">>> " prompt and
1296
"input()"/"raw_input()" calls.
1298
See docutils-users 2003-03-03.
1300
- _`body.listing`: Code listing with title (to be numbered
1301
eventually), equivalent of "figure" and "table" directives.
1303
- _`colorize.python`: Colorize Python code. Fine for HTML output,
1304
but what about other formats? Revert to a literal block? Do we
1305
need some kind of "alternate" mechanism? Perhaps use a "pending"
1306
transform, which could switch its output based on the "format" in
1307
use. Use a factory function "transformFF()" which returns either
1308
"HTMLTransform()" instance or "GenericTransform" instance?
1310
If we take a Python-to-HTML pretty-printer and make it output a
1311
Docutils internal doctree (as per nodes.py) instead of HTML, then
1312
each output format's stylesheet (or equivalent) mechanism could
1313
take care of the rest. The pretty-printer code could turn this
1316
<literal_block xml:space="preserve">
1317
print 'This is Python code.'
1322
into something like this ("</>" is end-tag shorthand)::
1324
<literal_block xml:space="preserve" class="python">
1325
<keyword>print</> <string>'This is Python code.'</>
1326
<keyword>for</> <identifier>i</> <keyword
1327
>in</> <expression>range(10)</>:
1328
<keyword>print</> <expression>i</>
1331
But I'm leaning toward adding a single new general-purpose
1332
element, "phrase", equivalent to HTML's <span>. Here's the
1333
example rewritten using the generic "phrase"::
1335
<literal_block xml:space="preserve" class="python">
1336
<phrase class="keyword">print</> <phrase
1337
class="string">'This is Python code.'</>
1338
<phrase class="keyword">for</> <phrase
1339
class="identifier">i</> <phrase class="keyword">in</> <phrase
1340
class="expression">range(10)</>:
1341
<phrase class="keyword">print</> <phrase
1342
class="expression">i</>
1345
It's more verbose but more easily extensible and more appropriate
1346
for the case at hand. It allows us to edit style sheets to add
1347
support for new formats, not the Docutils code itself.
1349
Perhaps a single directive with a format parameter would be
1352
.. colorize:: python
1354
print 'This is Python code.'
1358
But directives can have synonyms for convenience. "format::
1359
python" was suggested, but "format" seems too generic.
1361
- _`pysource.usage`: Extract a usage message from the program,
1362
either by running it at the command line with a ``--help`` option
1363
or through an exposed API. [Suggestion for Optik.]
1369
Interpreted text is entirely a reStructuredText markup construct, a
1370
way to get around built-in limitations of the medium. Some roles are
1371
intended to introduce new doctree elements, such as "title-reference".
1372
Others are merely convenience features, like "RFC".
1374
All supported interpreted text roles must already be known to the
1375
Parser when they are encountered in a document. Whether pre-defined
1376
in core/client code, or in the document, doesn't matter; the roles
1377
just need to have already been declared. Adding a new role may
1378
involve adding a new element to the DTD and may require extensive
1379
support, therefore such additions should be well thought-out. There
1380
should be a limited number of roles.
1382
The only place where no limit is placed on variation is at the start,
1383
at the Reader/Parser interface. Transforms are inserted by the Reader
1384
into the Transformer's queue, where non-standard elements are
1385
converted. Once past the Transformer, no variation from the standard
1386
Docutils doctree is possible.
1388
An example is the Python Source Reader, which will use interpreted
1389
text extensively. The default role will be "Python identifier", which
1390
will be further interpreted by namespace context into <class>,
1391
<method>, <module>, <attribute>, etc. elements (see pysource.dtd),
1392
which will be transformed into standard hyperlink references, which
1393
will be processed by the various Writers. No Writer will need to have
1394
any knowledge of the Python-Reader origin of these elements.
1396
* Add explicit interpreted text roles for the rest of the implicit
1397
inline markup constructs: named-reference, anonymous-reference,
1398
footnote-reference, citation-reference, substitution-reference,
1399
target, uri-reference (& synonyms).
1401
* Add directives for each role as well? This would allow indirect
1404
This text contains |nested inline markup|.
1406
.. |nested inline markup| emphasis::
1408
nested ``inline`` markup
1412
- "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
1413
around role contents.
1415
For example, the following reStructuredText source ... ::
1417
.. role:: red(raw-formatting)
1419
:html: <font color="red">
1420
:latex: {\color{red}
1427
... will yield the following document fragment::
1431
<inline classes="red">
1434
<raw format="latex">
1436
<inline classes="red">
1440
<raw format="latex">
1443
Possibly without the intermediate "inline" node.
1445
- "acronym" and "abbreviation": Associate the full text with a short
1446
form. Jason Diamond's description:
1448
I want to translate ```reST`:acronym:`` into ``<acronym
1449
title='reStructuredText'>reST</acronym>``. The value of the
1450
title attribute has to be defined out-of-band since you can't
1451
parameterize interpreted text. Right now I have them in a
1452
separate file but I'm experimenting with creating a directive
1453
that will use some form of reST syntax to let you define them.
1455
Should Docutils complain about undefined acronyms or
1458
What to do if there are multiple definitions? How to
1459
differentiate between CSS (Content Scrambling System) and CSS
1460
(Cascading Style Sheets) in a single document? David Priest
1463
The short answer is: you don't. Anyone who did such a thing
1464
would be writing very poor documentation indeed. (Though I
1465
note that `somewhere else in the docs`__, there's mention of
1466
allowing replacement text to be associated with the
1467
abbreviation. That takes care of the duplicate
1468
acronyms/abbreviations problem, though a writer would be
1469
foolish to ever need it.)
1471
__ `inline parameter syntax`_
1473
How to define the full text? Possibilities:
1475
1. With a directive and a definition list? ::
1482
Docstring Processing System
1484
Would this list remain in the document as a glossary, or would
1485
it simply build an internal lookup table? A "glossary"
1486
directive could be used to make the intention clear.
1487
Acronyms/abbreviations and glossaries could work together.
1489
Then again, a glossary could be formed by gathering individual
1490
definitions from around the document.
1492
2. Some kind of `inline parameter syntax`_? ::
1494
`reST <reStructuredText>`:acronym: is `WYSIWYG <what you
1495
see is what you get>`:acronym: plaintext markup.
1497
.. _inline parameter syntax:
1498
rst/alternatives.html#parameterized-interpreted-text
1500
3. A combination of 1 & 2?
1502
The multiple definitions issue could be handled by establishing
1503
rules of priority. For example, directive-based lookup tables
1504
have highest priority, followed by the first inline definition.
1505
Multiple definitions in directive-based lookup tables would
1506
trigger warnings, similar to the rules of `implicit hyperlink
1509
__ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
1511
4. Using substitutions? ::
1513
.. |reST| acronym:: reST
1514
:text: reStructuredText
1516
What do we do for other formats than HTML which do not support
1517
tool tips? Put the full text in parentheses?
1519
- "figure", "table", "listing", "chapter", "page", etc: See `object
1520
numbering and object references`_ above.
1522
- "glossary-term": This would establish a link to a glossary. It
1523
would require an associated "glossary-entry" directive, whose
1524
contents could be a definition list::
1533
This would allow entries to be defined anywhere in the document,
1534
and collected (via a "glossary" directive perhaps) at one point.
1537
Unimplemented Transforms
1538
========================
1540
* _`Footnote & Citation Gathering`
1542
Collect and move footnotes & citations to the end of a document.
1543
(Separate transforms.)
1545
* _`Reference Merging`
1547
When merging two or more subdocuments (such as docstrings),
1548
conflicting references may need to be resolved. There may be:
1550
* duplicate reference and/or substitution names that need to be made
1552
* duplicate footnote numbers that need to be renumbered.
1554
Should this be done before or after reference-resolving transforms
1555
are applied? What about references from within one subdocument to
1558
* _`Document Splitting`
1560
If the processed document is written to multiple files (possibly in
1561
a directory tree), it will need to be split up. Internal references
1562
will have to be adjusted.
1564
(HTML only? Initially, yes. Eventually, anything should be
1569
- Insert a "destination" attribute into the root element of each
1570
split-out document, containing the path/filename. The Output
1571
object or Writer will recognize this attribute and split out the
1572
files accordingly. Must allow for common headers & footers,
1573
prev/next, breadcrumbs, etc.
1575
- Transform a single-root document into a document containing
1576
multiple subdocuments, recursively. The content model of the
1577
"document" element would have to change to::
1580
( (title, subtitle?)?,
1582
(docinfo, transition?)?,
1586
(I.e., add the last line -- 0 or more document elements.)
1588
Let's look at the case of hierarchical (directories and files)
1589
HTML output. Each document element containing further document
1590
elements would correspond to a directory (with an index.html file
1591
for the content preceding the subdocuments). Each document
1592
element containing no subdocuments (i.e., structure model elements
1593
only) corresponds to a concrete file with no directory.
1595
The natural transform would be to map sections to subdocuments,
1596
but possibly only a given number of levels deep.
1600
If a document is split up, each segment will need navigation links:
1601
parent, children (small TOC), previous (preorder), next (preorder).
1602
Part of `Document Splitting`_?
1604
* _`List of System Messages`
1606
The ``system_message`` elements are inserted into the document tree,
1607
adjacent to the problems themselves where possible. Some (those
1608
generated post-parse) are kept until later, in
1609
``document.messages``, and added as a special final section,
1610
"Docutils System Messages".
1612
Docutils could be made to generate hyperlinks to all known
1613
system_messages and add them to the document, perhaps to the end of
1614
the "Docutils System Messages" section.
1616
Fred L. Drake, Jr. wrote:
1618
I'd like to propose that both parse- and transformation-time
1619
messages are included in the "Docutils System Messages" section.
1620
If there are no objections, I can make the change.
1622
The advantage of the current way of doing things is that parse-time
1623
system messages don't require a transform; they're already in the
1624
document. This is valuable for testing (unit tests,
1625
tools/quicktest.py). So if we do decide to make a change, I think
1626
the insertion of parse-time system messages ought to remain as-is
1627
and the Messages transform ought to move all parse-time system
1628
messages (remove from their originally inserted positions, insert in
1629
System Messages section).
1631
* _`Index Generation`
1637
* Add support for _`multiple stylesheets`. See
1638
<http://thread.gmane.org/gmane.text.docutils.cvs/4336>.
1640
* Idea for field-list rendering: hanging indent::
1642
Field name (bold): First paragraph of field body begins
1643
with the field name inline.
1645
If the first item of a field body is not a paragraph,
1646
it would begin on the following line.
1648
* Add more support for <link> elements, especially for navigation
1651
The framework does not have a notion of document relationships, so
1652
probably raw.destination_ should be used.
1654
We'll have framework support for document relationships when support
1655
for `multiple output files`_ is added. The HTML writer could
1656
automatically generate <link> elements then.
1658
.. _raw.destination: misc.raw_
1660
* Base list compaction on the spacing of source list? Would require
1661
parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
1663
* Add a tool tip ("title" attribute?) to footnote back-links
1664
identifying them as such. Text in Docutils language module.
1670
* Remove the generic style information (duplicated from html4css1.css)
1671
from pep.css to avoid redundancy.
1673
We need support for `multiple stylesheets`_ first, though.
1679
* Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option.
1682
HTML SlideShow Writer
1683
=====================
1685
Add a Writer for presentations, derivative of the HTML Writer. Given
1686
an input document containing one section per slide, the output would
1687
consist of a master document for the speaker, and a slide file (or set
1688
of filess, one (or more) for each slide). Each slide would contain
1689
the slide text (large, stylesheet-controlled) and images, plus "next"
1690
and "previous" links in consistent places. The speaker's master
1691
document would contain a small version of the slide text with
1692
speaker's notes interspersed. The master document could use
1693
``target="whatever"`` to direct links to a separate window on a second
1694
monitor (e.g., a projector).
1698
* Base the output on |S5|_. I discovered |S5| a few weeks before it
1699
appeared on Slashdot, after writing most of this section. It turns
1700
out that |S5| does most of what I wanted.
1702
Chris Liechti has `integrated S5 with the HTML writer
1703
<http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__.
1705
.. |S5| replace:: S\ :sup:`5`
1706
.. _S5: http://www.meyerweb.com/eric/tools/s5/
1708
Below, "[S5]" indicates that |S5| already implements the feature or
1709
may implement all or part of the feature. "[S5 1.1]" indicates that
1710
|S5| version 1.1 implements the feature (a preview of the 1.1 beta is
1711
available in the `S5 testbed`_).
1713
.. _S5 testbed: http://meyerweb.com/eric/tools/s5/testbed/
1717
* [S5 1.1] Incremental slides, where each slide adds to the one before
1718
(ticking off items in a list, delaying display of later items). The
1719
speaker's master document would list each transition in the TOC and
1720
provide links in the content.
1722
* Use transitions to separate stages. Problem with transitions is
1723
that they can't be used everywhere -- not, for example, within a
1724
list (see the example below).
1726
* Use a special directive to separate stages. Possible names:
1727
pause, delay, break, cut, continue, suspend, hold, stay, stop.
1728
Should the directive be available in all contexts (and ineffectual
1729
in all but SlideShow context), or added at runtime by the
1730
SlideShow Writer? Probably such a "pause" directive should only
1731
be available for slide shows; slide shows are too much of a
1732
special case to justify adding a directive (and node?) to the
1735
The directive could accept text content, which would be rendered
1736
while paused but would disappear when the slide is continued (the
1737
text could also be a link to the next slide). In the speaker's
1738
master document, the text "paused:" could appear, prefixed to the
1741
* Use a special directive or class to declare incremental content.
1742
This works best with the S5 ideas. For example::
1753
Add an option to make all bullet lists implicitly incremental?
1755
* Speaker's notes -- how to intersperse? Could use reST comments
1756
(".."), but make them visible in the speaker's master document. If
1757
structure is necessary, we could use a "comment" directive (to avoid
1758
nonsensical DTD changes, the "comment" directive could produce an
1759
untitled topic element).
1761
The speaker's notes could (should?) be separate from S5's handout
1764
* The speaker's master document could use frames for easy navigation:
1765
TOC on the left, content on the right.
1767
- It would be nice if clicking in the TOC frame simultaneously
1768
linked to both the speaker's notes frame and to the slide window,
1769
synchronizing both. Needs JavaScript?
1771
- TOC would have to be tightly formatted -- minimal indentation.
1773
- TOC auto-generated, as in the PEP Reader. (What if there already
1774
is a "contents" directive in the document?)
1776
- There could be another frame on the left (top-left or bottom-left)
1777
containing a single "Next" link, always pointing to the next slide
1778
(synchronized, of course). Also "Previous" link? FF/Rew go to
1779
the beginning of the next/current parent section? First/Last
1780
also? Tape-player-style buttons like ``|<< << < > >> >>|``?
1782
* [S5] Need to support templating of some kind, for uniform slide
1783
layout. S5 handles this via CSS.
1785
Build in support for limited features? E.g., top/bottom or
1786
left/right banners, images on each page, background color and/or
1789
* [S5?] One layout for all slides, or allow some variation?
1791
While S5 seems to support only one style per HTML file, it's
1792
pretty easy to split a presentation in different files and
1793
insert a hyperlink to the last slide of the first part and load
1794
the second part by a click on it.
1798
* For nested sections, do we show the section's ancestry on each
1799
slide? Optional? No -- leave the implementation to someone who
1802
* [S5] Stylesheets for slides:
1804
- Tweaked for different resolutions, 1024x768 etc.
1805
- Some layout elements have fixed positions.
1806
- Text must be quite large.
1807
- Allow 10 lines of text per slide? 15?
1808
- Title styles vary by level, but not so much?
1810
* [not required with S5.] Need a transform to number slides for
1811
output filenames?, and for hyperlinks?
1813
* Directive to begin a new, untitled (blank) slide?
1815
* Directive to begin a new slide, continuation, using the same title
1816
as the previous slide? (Unnecessary?)
1818
* Have a timeout on incremental items, so the colour goes away after 1
1821
Here's an example that I was hoping to show at PyCon DC 2005::
1823
========================
1824
The Docutils SlideShow
1825
========================
1827
Welcome To The Docutils SlideShow!
1828
==================================
1836
http://python.net/~goodger
1838
.. (introduce yourself)
1840
Hi, I'm David Goodger from Montreal, Canada.
1842
I've been working on Docutils since 2000.
1849
http://docutils.sourceforge.net
1851
.. I also volunteer as a Python Enhancement Proposal (or PEP)
1854
.. SlideShow is a new feature of Docutils. This presentation was
1855
written using the Docutils SlideShow system. The slides you
1856
are seeing are HTML, rendered by a standard Mozilla Firefox
1860
The Docutils SlideShow System
1861
=============================
1863
.. The Docutils SlideShow System provides
1865
Easy and open presentations.
1871
* reStructuredText-based input files.
1873
.. reStructuredText is a what-you-see-is-what-you-get
1874
plaintext format. Easy to read & write, non-proprietary,
1875
editable in your favourite text editor.
1877
.. Parsers for other markup languages can be added to Docutils.
1878
In the future, I hope some are.
1882
* Stylesheet-driven HTML output.
1884
.. The format of all elements of the output slides are
1885
controlled by CSS (cascading stylesheets).
1889
* Works with any modern browser.
1891
.. that supports CSS, frames, and JavaScript.
1892
Tested with Mozilla Firefox.
1902
That's as far as I got, but you get the idea...
1908
* What about if we don't know which Reader and/or Writer we are
1909
going to use? If the Reader/Writer is specified on the
1910
command-line? (Will this ever happen?)
1912
Perhaps have different types of front ends:
1914
a) _`Fully qualified`: Reader and Writer are hard-coded into the
1915
front end (e.g. ``pep2html [options]``, ``pysource2pdf
1918
b) _`Partially qualified`: Reader is hard-coded, and the Writer is
1919
specified a sub-command (e.g. ``pep2 html [options]``,
1920
``pysource2 pdf [options]``). The Writer is known before option
1921
processing happens, allowing the OptionParser to be built
1922
dynamically. Alternatively, the Writer could be hard-coded and
1923
the Reader specified as a sub-command (e.g. ``htmlfrom pep
1926
c) _`Unqualified`: Reader and Writer are specified as subcommands
1927
(e.g. ``publish pep html [options]``, ``publish pysource pdf
1928
[options]``). A single front end would be sufficient, but
1929
probably only useful for testing purposes.
1931
d) _`Dynamic`: Reader and/or Writer are specified by options, with
1932
defaults if unspecified (e.g. ``publish --writer pdf
1933
[options]``). Is this possible? The option parser would have
1934
to be told about new options it needs to handle, on the fly.
1935
Component-specific options would have to be specified *after*
1936
the component-specifying option.
1938
Allow common options before subcommands, as in CVS? Or group all
1939
options together? In the case of the `fully qualified`_
1940
front ends, all the options will have to be grouped together
1941
anyway, so there's no advantage (we can't use it to avoid
1942
conflicts) to splitting common and component-specific options
1945
* Parameterize help text & defaults somehow? Perhaps a callback? Or
1946
initialize ``settings_spec`` in ``__init__`` or ``init_options``?
1948
* Disable common options that don't apply?
1950
* Add ``--section-numbering`` command line option. The "sectnum"
1951
directive should override the ``--no-section-numbering`` command
1954
* Create a single dynamic_ or unqualified_ front end that can be
1961
indent-tabs-mode: nil
1962
sentence-end-double-space: t
added
removed
docs/dev/todo.txt
