Re: rst2odt.py/odtwriter added to main branch
Dave Kuhlman <dkuhlman <at> pacbell.net>
2009-01-07 19:21:32 GMT
> From: David Goodger <goodger <at> python.org>
> To: Dave Kuhlman <dkuhlman <at> pacbell.net>
> Cc: Docutils-develop <at> lists.sourceforge.net
> Sent: Saturday, December 27, 2008 2:31:00 PM
> Subject: Re: [Docutils-develop] rst2odt.py/odtwriter added to main branch
[snip]
I've made a few fixes in response to David's suggestions. A few
notes about these changes are below.
> There are some issues though. While I think it was premature to add, I
> understand the reasons. You did propose the addition 10 days ago, and
> I apologize for not replying earlier.
>
> Most importantly, there's no copyright/license statement in
> docutils/writers/odf_odt/__init__.py. Please add a public domain
> statement as found in other files. If you don't intend to put the
> writer in the public domain, please remove it immediately and let's
> discuss first.
Added::
# Copyright: This module has been placed in the public domain.
>
> I see two test failures:
>
> FAIL: test_odt_basic (test_writers.test_odt.DocutilsOdtTestCase)
> FAIL: test_odt_tables1 (test_writers.test_odt.DocutilsOdtTestCase)
>
I do not see these errors. When I run alltests.py, I see::
....................................................................................
----------------------------------------------------------------------
Ran 1095 tests in 14.630s
OK
Elapsed time: 15.348 seconds
The result of running rst2odt.py is a binary (Zipped) file, from
which I extract and an XML file. The test is a comparison to see
if this is identitical to a previously generated file. Could this
be a platform dependency? I'm on a 64-bit Ubuntu GNU/Linux system.
I just now did a fresh checkout of the docutils SVN tree. When I
go to docutils/test and run alltests.py, it says "OK".
I also have a laptop on which I can boot MS Windows/Vista. I'll
see if I can install and run the tests there.
> Documentation issues (docs/user/odt.txt):
>
> * Since it's now part of core Docutils, is there any need for section
> 2 ("How to Install It")? I suggest deleting it.
Done. But, I left a section describing special requirements.
>
> * I'd rename "Command line flags" to "Command line options", since not
> all are flags (i.e. some take arguments).
Done.
>
> * Why do you have both --stylesheet and --stylesheet-path options? I
> would expect rst2odt to require a local file, and wouldn't expect it
> to do any URL resolution. Please don't perpetuate the HTML/LaTeX
> stylesheet confusion currently being debated. I suggest just
> --stylesheet, but with the semantics of the current --stylesheet-path.
> Except, isn't the stylesheet inserted into the .odt file? Why "The
> path is adjusted relative to the output ODF file"?
I'll bet that I did that originally because all the other guys
(rst2html.py, rst2latex.py) did it and I wanted to be cool like
them. But, you are right. Only one is needed. I've removed
--stylesheet-path and modified the help/usage message and the doc.
>
> * Instead of "--no-add-syntax-highlighting", how about
> "--no-syntax-highlighting"? Ditto for "--no-create-sections"
> (--no-sections) & "--no-create-links" (--no-links).
Done.
>
> * Under "Styles", both "styles.xml" and "styles.odt" are mentioned.
> Which is actually used (and how)? Please clarify.
Actually, you can use either. The default is styles.odt installed
under writers/odf_odt/. styles.xml is packed inside of styles.odt
(which is a Zip archive). A likely scenario is to make a copy of
styles.odt, then edit it with oowriter, then use the --stylesheet
option to use your modified copy. A less likely scenario is to
extract styles.xml from styles.odt, then modify it with a text
editor, then use the --stylesheet option to use your modified copy.
I've made a few changes to the doc to attempt to make that more
clear.
>
> * Table of contents: can't the ODT writer insert an ODT table of
> contents (possibly via an option, as with LaTeX)?
rst2odt.py can generate a table of contents, but it's not a *real*
table of contents; it's just nested bullet/enum lists and has no
page numbers. That's why in the doc, there is this:
Table of contents
-----------------
``odtwriter`` can generate an outline style table of contents.
However, if you want an ``oowriter`` style table of contents along
with the formatting control that ``oowriter`` gives you, then you
may want to omit the ``.. contents::`` directive and, after
generating your document, open it in ``oowriter`` and insert a
table of contents. That feature is under menu item::
Insert --> Indexes and Tables --> Indexes and Tables
I could generate an oowriter table of contents with no page
numbers, but you would still have to open the document in oowriter
and ask it to update the table of contents, so as to insert the
page numbers. Either way requires opening the generated
document in oowriter and manually doing something to the table of
contents.
I'm open to suggestions.
rst2latex.py has a --use-latex-toc option. Perhaps I could add a
--generate-oowriter-toc option, which would cause generation of an
oowriter table of contents instead of the bullet/enumerated list
toc. But, a user would still need to open the document in
oowriter, right click on the toc, then pick "update".
OK. I implemented the --generate-oowriter-toc option, although it
still needs work. It inserts an empty, but real table of contents.
So, now, if you use that option, you would need to open the
generated document in oowriter, find that generated TOC, and update
it. I'm not sure that having to find and update a toc is any
easier than inserting one, however.
>
> * Under "Syntax highlighting", the note doesn't apply any more, and
> should be removed. But see below; the whole section probably should be
> pulled.
>
> Code issues:
>
> * The code/sourcecode/code-block directive should not be defined by a
> writer. Directives are parser constructs. If we can define a
> code-block directive that works with all writers, fine, but no
> writer-defined directive please. This has been discussed many times
> but never implemented. Please remove it from the writer until it's
> globally implemented.
Removed.
>
> * "odtwriter_plugins"? How are they used? This is something that must
> be done Docutils-wide or not at all.
Removed.
>
> * load_plugins is called at top-level, meaning that the writer cannot
> be imported for static analysis without side-effects. It (and any
> other call) should be guarded by an 'if __name__ == "main":' clause,
> at the very least. But I think all plugin support should be pulled, at
> least for now.
Removed.
>
> * OdtPygmentsFormatter etc.: I have a problem with all those classes
> being defined inside conditional blocks. Please put everything within
> the "try/except ImportError" block into a separate module; import that
> within a try/except.
Done.
>
> * In tools/rst2odt.py, there's a BinaryFileOutput class and a
> publish_cmdline_to_binary function. If these are necessary (I haven't
> examined them closely yet), they should be moved to the right places
> (docutils.io and docutils.core modules, respectively).
Moved them to docutils.io and docutils.core modules, respectively.
>
> --
> David Goodger
Additional change -- Added rst2odt_prepstyles.py to setup.py.
- Dave K.
--
Dave Kuhlman
http://www.rexx.com/~dkuhlman
------------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It is the best place to buy or sell services for
just about anything Open Source.
http://p.sf.net/sfu/Xq1LFB
RSS Feed