On 7/7/2011 07:26, Mathias Bauer wrote:
Moin,
I know how the help files where written at Sun/Oracle: the writers took
Writer for the text and used a set of basic macros to put some markup
into the files. Then they used an xslt to convert the document into the
xhp format.
I can't speak for the help writers, but most probably that isn't
necessary as we shouldn't ask those who created help content in the past
but those who will do it in the future.
IMHO using a well-established, maintained tool instead of a home brewn
set of macros that probably has lost its maintainer would be a huge
improvement.
While I don't oppose a change to DITA, I do offer another string to the
bow. One advantage of the Writer / macros method is that it greatly
lowers the bar to participation. Example: I volunteer to maintain the
macros (and at least help with the source) either for the interim, or
indefinitely. I don't know xslt technology, but I should be able to
learn as much as is needed, quickly.
There's another aspect that we should see: extension developers might
also want to add help content to their extensions. As until now there is
no tool available for the public, extension developers had a problem.
DITA would be an improvement for them.
The obvious alternative is to make the existing method public: create a
template with the Basic macros in a library, and make that and the xslt
down-loadable.
ODT export from DITA wouldn't help as it would miss the markup that the
help content provider needs. So either we had to convert from DITA to
xhp directly or we had to rewrite the help content provider to support
the DITA format.
Re-doing the help content provider is IMHO an excellent idea. Again,
there are two ways to go: a DITA provider, or an ODF (actually, .odt)
provider.
Mathias, you would know much better than I how feasible it would be to
use some kind of Writer window to display help. Without making light of
the technical problems, I am intrigued by lowering the participation bar
that far. Translators could work directly with .odt files. Users could
customize their own help, using Writer, and (we would hope) send us
their suggestions and improvements.
HTH. --/tj/
Regards,
Mathias
On 07.07.2011 00:49, Greg Stein wrote:
Ah. User guides vs $otherstuff.
For developer documentation, I'd be partial to doxygen. For help
doc... no opinion.
Cheers,
-g
On Wed, Jul 6, 2011 at 18:08, Rob Weir<apa...@robweir.com> wrote:
That was user guides. I'm talking about help documentation, though
the DITA approach could certainly handle user guides with ease as
well.
And remember, there is more than one doc team to consider here. And
once of them would like to use DITA.
-Rob
On Wed, Jul 6, 2011 at 5:46 PM, Greg Stein<gst...@gmail.com> wrote:
I seem to recall an email from the doc people that they wanted to
stick to their current toolset and infrastructure, rather than bring
that to the ASF. My take-away from that message is that the OOo
documentation is written by other/downstream people, rather than as a
deliverable from the ASF.
Cheers,
-g
On Wed, Jul 6, 2011 at 17:10, Rob Weir<apa...@robweir.com> wrote:
Would it be worth considering using DITA for the documentation/help?
I love ODF as much as anyone, but DITA was designed specifically for
technical documentation, and has built-in facilities for making
modular "topics" that then can be reassembled, with a "map" to
assemble larger works. This gives you the ability, for example, to
have paragraph that only shows up in the Linux version of the doc, but
not in the Windows version.
You also get an easy ability, via the DITA Open Toolkit (which is
Apache 2.0 licensed), to transform the DITA source into a large
variety of output forms, including:
HTML
PDF
ODT (Open Document Format)
Eclipse Help
HTML Help
Java Help
Eclipse Content
Word RTF
Docbook
Troff
The authors focus on the structure and content, and the layout and
styling is deferred until publication time. So you have a great deal
of flexibility for targeting the same content to various uses.
The other nice thing is that DITA is text (well, XML specifically), so
we use SVN to manage the content, can do diff's, merges, use the
editor of our choice, etc.
I'd like to argue for the advantages of DITA as a source format here.
I can probably find some volunteers to help enabled this. The
Symphony team uses DITA for doc/help, and we've already done the work
of converting much of the OOo help to DITA.
-Rob
