[Doc-SIG] what about OpenDocument?

[Chad Whitacre]

Laura,

Thanks for the feedback. You are correct that ODT is functionally a 
binary format from the point of view of the Unix toolset, and you'll 
notice that I mention "harder to diff/version?" as a con in my original 
post.

The decision I am seeing out of this is between a manual markup language 
and an automated one. Examples of the former would be LaTeX, ReST, 
HTML+PythonDoc: in these formats the doc authors directly manipulate the 
documentation source. ODT would be an example of the latter, which 
require a specialized authoring environment.

The problem with the former is that some folks don't like manually 
coding markup, and so we then look for a balance between light markup 
and adequacy to the task. The OpenOffice idea was a stab at solving the 
problem in a different way: by not manually coding markup at all. 
Besides the translucency of the format, my beef is that the markup it 
gives us is inadequate, both in terms of encoding information and 
accessing it.



chad



Laura Creighton wrote:
> Yes, this is precisely what many of us dislike.  When we are working
> on a project, and somebody changes the docs, we want a nice readable
> svn checkin with the diffs, something that we can glance at any say
> 'yes that's correct' or 'oops, that's wrong'.  When instead you get
> 'binary file, no diffs available' your documentation starts living in
> a world of its own, a world that you have to visit periodically and do
> work to keep up with.
> 
> Laura
> 
> In a message of Sat, 31 Dec 2005 13:19:34 +1100, Christopher Armstrong writes:
> 
>>On 12/31/05, Laura Creighton <lac at strakt.com> wrote:
>>
>>>So it is a binary file format?  If so, that will be a problem.  Anythin
>>
>>g
>>
>>>that produces output you cannot run through unix tools such as grep, an
>>
>>d
>>
>>>anything that you cannot edit in your favourite text editor will be a
>>>problem.
>>
>>Well, all it is is a zip file that contains some XML files and some
>>subdirectories. content.xml is fairly easy to extract from the zip,
>>munge, and put back.
>>
>>--
>> Twisted   |  Christopher Armstrong: International Man of Twistery
>>  Radix    |    -- http://radix.twistedmatrix.com
>>           |  Release Manager, Twisted Project
>> \\\V///   |    -- http://twistedmatrix.com
>>  |o O|    |
>>w----v----w-+
> 
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>