35
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
38
Minimum Requirements for Python Standard Library Candidacy
76
39
==========================================================
75
* We don't have consistent (or no) encoding handling for command line
77
<http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957>.
79
* Improve handling on Windows:
81
- Get graphical installer.
82
- Make rst2html.py an .exe file using py2exe.
86
The user interface is very difficult to use for most Windows users;
87
you can't really expect them to use the command line. We need some
88
kind of GUI that can launch rst2html.py, and save the HTML output to
89
a file, and launch a browser. What's important is that we get
90
settings to work with the GUI. So we need some way to dynamically
91
generate a list of settings for the GUI. The current settings_spec
92
for OptionParser doesn't seem to be usable for this for the
95
- It's biased toward the command line -- there are *two* options for
98
- You cannot have both a one-line description and a longer
99
description for tooltips/help-texts.
101
- It doesn't provide hints for the input type. You cannot easily
102
infer the type of a setting from its validator, because any
103
component can add new validators. In fact, it may be necessary to
104
have both a hint about the input type (e.g. string) and a
105
validator (valid ID), or it may be necessary to have a different
106
set of choices for the CLI (1, INFO, 2, ...) and for the GUI
107
(INFO, WARNING, ...).
109
- It's coupled to the OptionParser. We want to be able to change
110
the underlying system without breaking everything.
112
- It's a bunch of primitive structures. We want an extensible (thus
113
object-oriented) interface.
115
So we probably need to create a class for storing all the settings,
116
and auto-generate the OptionParser data from that.
118
I talked to Stephan Deibel about getting Docutils integrated into
119
Wing IDE. He said it's possible, and he'd be willing to help.
120
There's a scripting interface to Wing, which we'd use. We can
121
dynamically generate a list of preferences and not worry too much
122
about the rendering (from what I understood); Wing's whole GUI is
123
dynamic anyway. The interface could be made usable for other GUIs.
124
For example, we could try to get option support for DocFactory. //
112
127
* Allow different report levels for STDERR and system_messages inside
115
130
* Change the docutils-update script (in sandbox/infrastructure), to
116
131
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
133
* Move some general-interest sandboxes out of individuals'
123
134
directories, into subprojects?
351
362
As I said earlier in chapter :chapter:`objects`, the
352
363
reference count gets increased every time a binding is made.
354
* Add support for _`multiple output files`.
365
* Add support for _`multiple output files` and _`generic data
368
It should be possible for a component to **emit or reference** data
369
to be either **included or referenced** in the output document.
370
Examples of such data are stylesheets or images.
372
For this, we need a "data" object which stores the data either
373
inline or by referring to a file. The Docutils framework is
374
responsible for either:
376
* storing the data in the appropriate location (e.g. in the
377
directory of the output file, or in a user-specified directory)
378
and providing the paths of the stored files to the writer, *or*
380
* providing the data itself to the writer so that it can be embedded
381
in the output document.
383
This approach decouples data handling from the data source (which
384
can either be embedded or referenced) and the destination (which can
385
either be embedded or referenced as well).
387
See <http://article.gmane.org/gmane.text.docutils.devel/3631>.
356
389
* Add testing for Docutils' front end tools?
703
744
__ rst/alternatives.html#or-not-to-do
746
* Recognize unicode whitespace and punctuation. See
747
<http://thread.gmane.org/gmane.text.docutils.user/2765>.
749
* Allow embedded references and not only embedded URIs: ```link text
750
<reference_>`_``; see the second half of
751
<http://article.gmane.org/gmane.text.docutils.devel/3738>.
753
* Another list problem::
759
This ends up as a definition list. This is more of a usability
762
* This case is probably meant to be a nested list, but it ends up as a
763
list inside a block-quote without an error message::
769
It should probably just be an error.
771
The problem with this is that you don't notice easily in HTML that
772
it's not a nested list but a block-quote -- there's not much of a
705
775
* Treat enumerated lists that are not arabic and consist of only one
706
776
item in a single line as ordinary paragraphs. See
707
777
<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>.
779
* The citation syntax could use some improvements. See
780
<http://thread.gmane.org/gmane.text.docutils.user/2499> (and the
782
<http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>,
783
and the follow-ups at
784
<http://thread.gmane.org/gmane.text.docutils.user/3087>,
785
<http://thread.gmane.org/gmane.text.docutils.user/3110>,
786
<http://thread.gmane.org/gmane.text.docutils.user/3114>),
787
<http://thread.gmane.org/gmane.text.docutils.user/2443>,
788
<http://thread.gmane.org/gmane.text.docutils.user/2715>,
789
<http://thread.gmane.org/gmane.text.docutils.user/3027>,
790
<http://thread.gmane.org/gmane.text.docutils.user/3120>,
791
<http://thread.gmane.org/gmane.text.docutils.user/3253>.
713
793
* The current list-recognition logic has too many false positives, as
812
881
__ http://thread.gmane.org/gmane.text.docutils.user/1915
813
882
__ http://thread.gmane.org/gmane.text.docutils.user/2438
884
Idea from Jim Fulton: an external lookup table of targets:
886
I would like to specify the extension (e.g. .txt) [in the
887
source, rather than ``filename.*``], but tell the converter to
888
change references to the files anticipating that the files will
893
.. _Another Document: another.txt
895
rst2html.py --convert-links "another.txt bar.txt" foo.txt
897
That is, name the files for which extensions should be converted.
899
Note that I want to refer to original files in the original text
900
(another.txt rather than another.txt) because I want the
901
unconverted text to stand on its own.
903
Note that in most cases, people will be able to use globs::
905
rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
907
It might be nice to be able to use multiple arguments, as in::
909
rst2html.py --convert-link-extensions-for *.txt -- foo.txt
913
> What is to be done for output formats
914
> that don't have hyperlinks?
916
Don't convert the links.
920
> Handle documents only, or objects
921
> (images, etc.) also?
923
No, documents only, but there really is no need for gueswork.
924
Just get the file names as command-line arguments. EIBTI
925
[explicit is better than implicit].
927
For images, we probably need separate solution (which is being
928
worked on), whereas for documents, the issue is basically
929
interlinking between reStructuredText documents. IMO, this cries
930
for support for multiple input and output files, i.e. support for
931
documents which comprise multiple files. Adding adaptable file
932
extensions seems like a kludge. // FW
815
934
* Implement the header row separator modification to table.el. (Wrote
816
935
to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
817
936
support for "=====" header rows. On 2001-08-17 he replied, saying
1773
* Make it easier to find out fragment names (#foo-bar) of ``_`inline
1774
targets```. Currently you have to either look at the source or
1777
For example, we could add support for self-referencing targets
1778
(i.e. inline targets would [unobtrusively] link to themselves, so
1779
that you can just click them and then copy the address). Or we
1780
could add support for titles that display the fragment name (as in
1781
<http://subversion.tigris.org/mailing-list-guidelines.html>; just
1782
hover the paragraphs).
1784
Either way it should be optional and deactivated by default.
1786
This would be useful for documents like Docutils' bug list or to-do
1789
* Make the _`list compacting` logic more generic: For example, allow
1790
for literal blocks or line blocks inside of compact list items.
1792
This is not implementable as long as list compacting is done by
1793
omitting ``<p>`` tags. List compacting would need to be done by
1794
adjusting CSS margins instead.
1637
1796
* Add support for _`multiple stylesheets`. See
1638
1797
<http://thread.gmane.org/gmane.text.docutils.cvs/4336>.
1673
1832
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?
1838
* Add a way to begin an untitled slide.
1840
* Add a way to begin a new slide, continuation, using the same title
1841
as the previous slide? (Unnecessary?) You need that if you have a
1842
lot of items in one section which don't fit on one slide.
1844
Maybe either this item or the previous one can be realized using
1847
* Have a timeout on incremental items, so the colour goes away after 1
1850
* Add an empty, black last slide (optionally). Currently the handling
1851
of the last slide is not very nice, it re-cycles through the
1852
incremental items on the last slide if you hit space-bar after the
1855
* Add a command-line option to disable advance-on-click.
1857
* Add a speaker's master document, which would contain a small version
1858
of the slide text with speaker's notes interspersed. The master
1859
document could use ``target="whatever"`` to direct links to a
1860
separate window on a second monitor (e.g., a projector).
1862
.. Note:: This item and the following items are partially
1863
accomplished by the S5 1.2 code (currently in alpha), which has
1864
not yet been integrated into Docutils.
1755
1866
* Speaker's notes -- how to intersperse? Could use reST comments
1756
1867
(".."), but make them visible in the speaker's master document. If
1779
1890
the beginning of the next/current parent section? First/Last
1780
1891
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...
1897
* Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option.
1905
1900
Front-End Tools
added
removed
docs/dev/todo.txt
