[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