incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <apa...@robweir.com>
Subject Re: DITA for Doc?
Date Thu, 07 Jul 2011 00:21:14 GMT
On Wed, Jul 6, 2011 at 7:33 PM, Dave Fisher <dave2wave@comcast.net> wrote:
>
> On Jul 6, 2011, at 3:55 PM, Rob Weir wrote:
>
>> On Wed, Jul 6, 2011 at 6:11 PM, Dave Fisher <dave2wave@comcast.net> wrote:
>>> Hi Rob,
>>>
>>> On Jul 6, 2011, at 2:10 PM, Rob Weir wrote:
>>>
>>>>  we've already done the work
>>>> of converting much of the OOo help to DITA.
>>>
>>> Is there a software grant coming?
>>>
>>
>> It is worth considering.  But I'm not going to face that corporate red
>> tape merely on speculation that this might be useful.  Let's first
>> discuss whether the DITA approach seems reasonable.  I think it is
>> important for content authors to be aware that this would be writing
>> documentation with tags, similar to HTML.  Good HTML.  But this
>> structure would give us loads of flexibility for how we structure the
>> content, combine it is different ways, and publish it.
>>
>> You can get a flavor of DITA here:
>>
>> http://www.xmlmind.com/tutorials/DITA/index.html
>
> An example is always helpful. I think that DITA is a reasonable form.
>
> The topicref hierarchy is a critical necessity. It is likely as good as
>
>> Tags are off-putting to some people who just want to work in a WYSIWYG
>> fashion, so I wanted to check.
>
> I like tags. Where is a complete reference?
>

DITA is an standard from OASIS (same standards consortium that created
ODF, though a different committee)

Full specification is here:
http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.pdf

> It is difficult to repurpose content if is over-fiddled with in a WYSIWYG fashion.
>
> Since we want to repurpose this content in many ways this can make sense.
>
>>  One possible way of working is to
>> accept raw content in any reasonable format, ODF, DOC, HTML, yellow
>> crayon on a napkin, etc., and then have a manual cut & paste process
>> to get that into DITA initially, and then maintain it that way going
>> forward.
>
> I think that we can strive to go back and forth between DITA and markdown. The Apache
CMS is easily extensible with XSL. I can see how to structure a transformation.
>

So the DITA Open Toolkit may be useful here:  http://dita-ot.sourceforge.net/

It will do DITA to HTML, which at the very least could be used for
some form of preview in the CMS, before committing changes.

There is also an HTML to DITA converter that might be useful,
described here: http://dita-ot.sourceforge.net/readme/DITA-h2d.html


> How does DITA handle style sheets? Is it easy to have different layout templates for
different outputs.
>

So the unit of document in DITA is a "topic".  The topics that
together are ordered into a document via a "map".  This is one level
of control, the reuse and slice and dicing aspect.  Then there is the
presentation attributes, the styles and classes.  That is in the DITA
Open Toolkit. A good place to start is here:

http://dita-ot.sourceforge.net/readme/DITA-usingtransforms.html

There is additional customization available, but that is the set of
out-of-the-box parametrized settings.


> Is there an ODF to DITA translation?
>

No.   There is pretty much DITA to * conversions, but DITA is at the
"highest information level" so conversion to any other format results
in loss of semantic information, while generally gaining presentation
attributes.  ODF is more semi-structured.  It should be possible to do
a constrained conversion of ODF to DITA, but you would need to ensure
that the author used a specific pre-defined template and religiously
used only the template styles.  Once an author selects text and
fiddles with the styles to make it 16 pt bold Times New Roman,
indented 2", then all bets are off.

There are also aspects of DITA that don't quite map to ODF (at least
without RDF metadata).  For example, DITA has an "audience" attribute
for elements, where you can specify the target audience at a fine
grained level.  Ditto for "platform", "product", "rev", etc.  So you
could have a step in your documentation that is marked as relevant
only for OOo 3.4.0 beta advanced Linux users.  And this information
could then be published only in a subset of publications.  You would
go crazy trying to emulate this with predefined styles in ODF.  It
would be a combinatorial explosion of styles.  With RDF metadata in
ODF you might have a customized palette of attributes that you could
apply to text, in addition to the predefined ODF attributes like bold,
italics, etc.  So you would select text and right click and select
"platform\windows" or "audience\expert", etc.  Would be very powerful,
and is fully supported by ODF 1.2.  But OpenOffice doesn't support it
yet.


> I am currently looking closely at the Apache CMS someone will need to look at the requirements.
Where's the best release and what's required?
>
> Regards,
> Dave
>
>
>>
>>> Regards,
>>> Dave
>>>
>
>

Mime
View raw message