[Doc-SIG] what about OpenDocument?
Chad Whitacre
chad at zetaweb.com
Sat Dec 31 05:36:07 CET 2005
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
>
More information about the Doc-SIG
mailing list