Re: [chairs] Why the DITA Adoption TC cares about "templates"

[Jon Bosak <bosak@pinax.com>]

In UBL we have (of course :-)) been providing all of our documents
as specified in the OASIS process.  Based on our experience, I
have to say that some of the ways you can do this are a lot
easier, or give better results, than some of the others.  Ways we
have tried include:

  - Authoring in HTML alone.  This works great (we published UBL
    0.7 and UBL 1.0 this way), but then the OASIS Board decided
    that HTML wasn't good enough for hypertexts (!) and added the
    requirement to produce PDF as well.  It has never been
    satisfactorily explained why this was found to be necessary.

  - Authoring in Word or OpenOffice (using the templates provided
    by OASIS) and then creating both PDF and HTML from that.  Using
    OpenOffice has the advantage of not requiring the purchase of a
    PDF writer (typically Adobe Acrobat).  This works reasonably
    well and is the workflow we used for our UBL Guidelines for
    Customization.  I wouldn't hesitate to recommend it for
    smallish ad hoc TC work products.

  - Authoring in DocBook and then generating HTML and PDF from that
    source using the tools provided by OASIS (which are largely
    based on the work of the OASIS DocBook TC).  The DocBook is
    translated by XSLT scripts directly into HTML and also into
    XSL-FO, from which you can generate rather nice-looking PDF.
    This works very well and (once you've got everything running
    correctly) is far and away the best of the three methods when
    it comes to managing big, complex documents with a lot of
    internal references like UBL.  We've used this workflow
    successfully with UBL 2.0, the UBL 2.0 Naming and Design Rules,
    and UBL 2.1 PRD1.

    The big problem with this last approach -- aside from the
    requirement that your authors have to be comfortable working in
    XML -- is that we don't have good, free XSL-FO formatters set
    up for OASIS use.  In UBL 2.0 (2006) we threw up our hands and
    produced the PDF deliverable by importing the generated HTML
    into something (probably OpenOffice) and then regenerating the
    PDF from that in order to satisfy OASIS.  The results were not
    exactly unreadable, but they were so bad that we actually had
    to insert a notice in the PDF telling people to please ignore
    it and use the HTML.  In recent years we have been lucky enough
    to use contributed licenses from a leading maker of FO
    formatting software, but this is not a strategy that will work
    for everyone.  What's needed, I think, is a version of
    something like FOP or (my favorite) xmlroff that can be
    downloaded along with the rest of the DocBook "template" to
    create a complete OASIS publishing environment.

Jon

Jeff Mischkinsky wrote:
> 
> On Dec 23, 2010, at 11:52 AM, JoAnn Hackos wrote:
> 
>> Jeff,
>> The Adoption TC has been developing feature articles, not committee
>> notes. Our feature articles are only provided in PDF. Thus, HTML is a
>> new requirements because our feature articles must now be released as
>> committee notes.
> 
> What were they released as before?
> 
>  From the (old) TC Process:
> "Editable formats of all versions of TC documents must be delivered to 
> the TC’s document repository. TC Working Drafts may be in any format 
> (i.e. produced by any application). All TC-approved versions of 
> documents (i.e. Committee Drafts, Public Review Drafts, and Committee 
> Specifications) must be delivered to the TC’s document repository in the 
> (1) editable source, (2) HTML or XHTML, and (3) PDF formats; and the TC 
> must explicitly designate one of those delivered formats as the 
> authoritative document. Any links published by the TC shall be to the 
> HTML, XHTML and/or PDF formats stored using repositories and domain 
> names owned by OASIS and as approved by the TC Administrator."
> 
> cheers,
>  jeff
> 
> 
> 
>>
>> JoAnn Hackos
>> Co-Chair DITA Adoption TC
>>
>> JoAnn Hackos PhD
>> President
>> Comtech Services, Inc.
>> joann.hackos@comtech-serv.com
>> Skype joannhackos
>>
>>
>>
>>
>> -----Original Message-----
>> From: Jeff Mischkinsky [mailto:jeff.mischkinsky@oracle.com]
>> Sent: Thursday, December 23, 2010 12:11 PM
>> To: Kristen Eberlein
>> Cc: chairs@lists.oasis-open.org
>> Subject: Re: [chairs] Why the DITA Adoption TC cares about "templates"
>>
>> hi kristen,
>>   one clarification below
>> On Dec 17, 2010, at 2:37 PM, Kristen Eberlein wrote:
>>
>>> Based on off-list e-mails, I thought I should clarify some issues:
>>>
>>> *         The DITA Adoption TC authors its white papers in DITA.
>>> *         The new processes now require us to provide editable
>>> source, PDF, and XHTML for the white papers.
>>
>> I don't believe this is a new requirement. I searched back, and found
>> the requirement going all the way back to the August 2006 version of
>> the TC Process (where i stopped searching).
>> Whether it's been enforced is a different question. ;-)
>>
>> For the record:  all the previous versions of the TC Process can be
>> found on linked from http://www.oasis-open.org/committees/process.php
>>
>> cheers,
>>   jeff
>>
>>> *         We cannot code the necessary transformations for XHTML
>>> without knowing what the requirements (font, font size, font weight,
>>> headers, footers, tables, etc.) are.
>>> *         We want the requirements to be defined and stable:
>>> o   We want to have a clearly specified set of requirements so that
>>> we can ensure that our work products meet them.
>>> o   We do not want to have to redevelop the transformations except
>>> at specified and set intervals.
>>> Best regards,
>>> Kris
>>> Co-chair, OASIS DITA Technical Committee
>>> Charter member, OASIS DITA Adoption Committee
>>> Kristen James Eberlein l DITA Architect and Technical Specialist l
>>> SDL Structured Content Technologies Division l (t) + 1 (919)
>>> 682-2290 lkeberlein@sdl.com
>>> <image001.jpg>
>>> Please consider the environment before printing this e-mail
>>>
>>
>> -- 
>> Jeff Mischkinsky
>> jeff.mischkinsky@oracle.com
>> Sr. Director, Oracle Fusion Middleware
>> +1(650)506-1975
>>     and Web Services Standards                       500
>> Oracle Parkway, M/S 2OP9
>> Oracle                                Redwood
>> Shores, CA 94065
>>
>>
>>
>>
>>
>>
>>
>>
>>
> 
> -- 
> Jeff Mischkinsky                              jeff.mischkinsky@oracle.com
> Sr. Director, Oracle Fusion Middleware                 +1(650)506-1975
>     and Web Services Standards                       500 Oracle Parkway, 
> M/S 2OP9
> Oracle                                Redwood Shores, CA 94065
> 
> 
> 
> 
> 
> 
> 
> 
> 
>