[Doc-SIG] docutils feedback
Simon Hefti
hefti@netcetera.ch
Tue, 11 Jun 2002 14:45:47 +0200 (MET DST)
Hi David,
We discussed a couple of rst syntax fragments a couple of month ago.
Now I actually started using docutils, and I like it. Here are a few
questions and comments (I'm using docutils-0.1).
- one problem resulted in this error message:
Traceback (most recent call last):
File "/home/hefti/local_in_archive/src/docutils-0.1/tools/html.py", line 26, in ?
reporter=reporter)
File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 85, in publish
pub.publish(source, destination)
File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 67, in publish
self.writer.write(document, destination)
File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init__.py", line 56, in write
self.record()
File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/html4css1.py", line 36, in record
self.recordfile(self.output, self.destination)
File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init__.py", line 86, in recordfile
output = output.encode('raw-unicode-escape') # @@@ temporary
UnicodeError: ASCII decoding error: ordinal not in range(128)
... where I wished to see the line number of the rst document more
than the stack trace. In some error cases, the line number is shown,
though.
- just realized that the --version option is mssing:
python html.py --version
should, in my opinion, write some version info to stdout.
- cannot handle umlauts !
I can see that you do not want to deal with exotic characters. I
would expect docutils to be able to process a few standard character
sets, though, including iso-8859-1.
I'm a Tcl guy, where the programming language itself supports all
kinds of encodings. I assume python can do this as well.
- I'm not sure I like the table markup.
I think that it is very usefull and complete, but perhaps sometimes
a simpler variant could be helpful, e.g. like
---+-----
id | desc
---+-----
1 | foo
2 | a rather long line which is not matched by the others
---+-----
One problem I had was with a "...." in the table, which was
interpreted as a title rather. I was confused because I was not
thinking of writing titles within tables.
Another problem of the table syntax is that monospaced chars are
often not approriate to write complex tables (this is one reason why
spread sheets are successfull), and long text in cells tends to blow
the ASCII art up so much that it is not readable, or editable
easily.
- how to mark-up examples ?
.. example:: would be nice
- literal blocks:
require no identation, please ! (but end-of-block)
This was one of the main reasons for POD: start a document,
copy-paste code or whatever, and process it into man pages, html
and so forth.
I would consider somthing like:
previous para::my_end_tag
select foo from bar where id=1;
.. my_end_tag
at least as a variant.
- relative URLs ?
I would like to add relative URLs, e.g.:
see also /some/where/more.html
Is there a mark-up for that ? Could docutils provide one ?
Thanks a lot,
Simon.
------------------------------------------------------------------------
Simon Hefti simon.hefti@netcetera.ch
Netcetera AG, 8040 Zuerich phone +41 1 247 79 47 fax +41 1 247 70 75