incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Frank Peters <>
Subject Re: Source format for user guides
Date Mon, 27 Jun 2011 18:20:48 GMT

> Can you clarify, please?  Is the intent to make ODFAuthors be part of
>> the Apache OpenOffice project, e.g. run on Apache servers with
>> PMC-elected committers having write access, other contributing authors
>> submitting patches before being eventually voted in as committers, all
>> working in the Apache project lists, transparently, with all work
>> under the Apache license, with the PMC setting overall direction and
>> approving releases?
>> Is that the idea?  If so, this would be great.
>> -Rob
> Rob,
> No. None of the above is the intent. ODFAuthors is, and intends to
> remain, independent. Some variation on our existing workflow and
> procedures could certainly be accommodated. For example, OOo-related
> discussion could be carried out on a mailing list at Apache instead of
> on the existing list at OOo (or the ODFAuthors list), and "release
> candidates" of user guide chapters could be approved by the PMC.

So basically, like with the OOo Docs Project, ODFAuthors remains
independent and Apache OOo can take advantage of the material by
publishing it on the website and/or the wiki, much like what happens
today at (classical) OOo.

and in another post of Jean:

> BTW, OOoAuthors (the precursor to ODFAuthors) was set up largely because
> of the difficulty of user documentation producers in coping with the
> sort of versioning and tracking systems used by code developers.

Source code management systems in general are only poorly suited to
work with documentation, unless you *stricly* separate
content from representation. You could then make the latter part of
the documentation build process, where the content is compiled into
ODF/PDF/HTML/Whatever using certain styles and templates.

Ideally, for documentation pieces that will be part of the Apache
OOo project I would like to find a way in which we follow the above
workflow and *not* use ODF for docs sources for the reasons given
by Rob.

That does not mean, however, that we cannot use OOo as an authoring
tool, provided we use a file format that can be read and written
by OOo and is compatible with SVN storage. The OOo help, for example,
uses a simple XML format, yet there is an authoring extension that
allows you to edit those files directly from within OOo.

We could go for Docbook (or a simplified Doc book), for example,
or XHTML. Or even flat-ODF (uncompressed XML stream), although this
stream is fairly "polluted" with insignificant meta information
and would therefore be harder to "normalize" for SVN storage.

An advantage of this approach would be that we can showcase
OOo's excellent potential as "generic" authoring tool through
filters to almost any XML-based format.


View raw message