Re: [chairs] What can Standards Development / TC Administration do to help?

[Mary McRae <mary.mcrae@oasis-open.org>]

On Apr 22, 2010, at 5:56 PM, James Bryce Clark wrote:

> Thanks.  Hope springs eternal about automation :D  So we need a
> critical mass to justify development effort.  Back to Kelvin and the
> chairs then ...
> 
> 1. Do we think that there are a *lot* of TCs who happily author in an
> XML editor, and could get together on a schema?
I don't, but I'd loved to be proven wrong ;)
> 
> (Let's exclude the case that each TC wants to use its own format, as
> too obvious.  Which TCs are using OTHER TCs' work?  Jon mentioned that
> UBL uses DocBook.)
DITA is the only TC I'm aware of using DITA as an authoring format; there are several (DocBook, UBL, Codelist, XRI, and I think a couple of others) using DocBook. There's also a handful using our XHTML markup (WebCGM, WSRP, maybe another one).
> 
> 2.  Do we think that there are a *lot* of TCs who want only to author
> in a  WYSIWYG office-document-style environment only, like Kelvin?
Yes

> Any reason we could not use a single XML-compatible office document
> format for that?  Maybe even a standard?
Yes. The markup is atrocious and building XSLTs robust enough to handle all of the possible variances would require a much greater level of effort than a content/structure-based vocabulary.

Take the following code snippet from an ODF file (represents a specification title, stage, date, and URIs):
<!--     ODF Snippet Start -->
- <text:p text:style-name="Title"> 
SAML V2.0 Identity Assurance Profiles, 
<text:s /> 
Version 1.0 
</text:p> 
<text:p text:style-name="Subtitle">Committee Draft 01</text:p> 
<text:p text:style-name="Subtitle">22 September 2009</text:p> 
<text:p text:style-name="Title_20_page_20_info">Specification URIs:</text:p> 
<text:p text:style-name="Title_20_page_20_info">This Version:</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";>http://docs.oasis-open.org/security/saml/Post2.0/</text:a> 
- <text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";> 
<text:file-name text:display="name">sstc-saml-assurance-profile-cd-01</text:file-name> 
</text:a> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";>.html</text:a> 
</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.odt";>http://docs.oasis-open.org/security/saml/Post2.0/</text:a> 
- <text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.odt";> 
<text:file-name text:display="name">sstc-saml-assurance-profile-cd-01</text:file-name> 
</text:a> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.odt";>.odt</text:a> 
(Authoritative) 
</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.pdf";>http://docs.oasis-open.org/security/saml/Post2.0/</text:a> 
- <text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.pdf";> 
<text:file-name text:display="name">sstc-saml-assurance-profile-cd-01</text:file-name> 
</text:a> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.pdf";>.pdf</text:a> 
</text:p> 
<text:p text:style-name="Title_20_page_20_info">Previous Version:</text:p> 
<text:p text:style-name="Title_20_page_20_info_20_description">N/A</text:p> 
- <text:p text:style-name="Title_20_page_20_info"> 
Latest 
<text:s /> 
Version: 
</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.html";>http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.html</text:a> 
</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.odt";>http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.odt</text:a> 
(Authoritative) 
</text:p> 
- <text:p text:style-name="Title_20_page_20_info_20_description"> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.pdf";>http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile.pdf</text:a> 
</text:p>
<!-- ODF Snippet end -->



vs this snippet from a DocBook file:
<!-- DocBook snippet start -->
<!--inclusions-->
<!ENTITY conformance-doc SYSTEM "conformance-doc.xml">
<!ENTITY conformance-app SYSTEM "conformance-app.xml">
<!--the document properties-->
<!ENTITY name "context-value-association">
<!ENTITY previous-version "prd01">
<!ENTITY version "cd02prd02">
<!ENTITY standard "Committee Draft 02/Public Review Draft 02"><!--"Committee Specification"-->
<!ENTITY pubdate "07 February 2010">
<!ENTITY previous-loc   "http://docs.oasis-open.org/codelist/&previous-version;-ContextValueAssociation-1.0";>
<!ENTITY this-loc   "http://docs.oasis-open.org/codelist/&version;-ContextValueAssociation-1.0";>
<!ENTITY latest-loc "http://docs.oasis-open.org/codelist/ContextValueAssociation";>
]>
<article status="&standard;">

<articleinfo>
<releaseinfo role="cvs">
<?nospell-start?>$Id: context-value-association-cd02prd02.xml,v 1.4 2010/02/15 00:12:31 gkholman Exp $<?nospell-end?>
</releaseinfo>

<productname>&name;</productname>
<productnumber>&version;</productnumber>

<!--
<releaseinfo role="product"><ulink url="&name;-&version;.xml">XML</ulink></releaseinfo>
<releaseinfo role="product"><ulink url="&name;-&version;.html">HTML</ulink></releaseinfo>
<releaseinfo role="product"><ulink url="&name;-&version;.pdf">PDF (A4)</ulink></releaseinfo>
<releaseinfo role="product"><ulink url="&name;-&version;-us.pdf">PDF (US)</ulink></releaseinfo>
<releaseinfo role="oasis-id">{OASIS Document Number}</releaseinfo>
-->

<releaseinfo role="OASIS-specification-this-authoritative">&this-loc;/doc/context-value-association.html</releaseinfo>
<releaseinfo role="OASIS-specification-this">&this-loc;/doc/context-value-association.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-this">&this-loc;/doc/context-value-association.xml</releaseinfo>

<releaseinfo role="OASIS-specification-previous-authoritative">&previous-loc;/doc/context-value-association.html</releaseinfo>
<releaseinfo role="OASIS-specification-previous">&previous-loc;/doc/context-value-association.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-previous">&previous-loc;/doc/context-value-association.xml</releaseinfo>

<releaseinfo role="OASIS-specification-latest-authoritative">&latest-loc;/doc/context-value-association.html</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/doc/context-value-association.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/doc/context-value-association.xml</releaseinfo>
<!-- DocBook snippet end-->


If you were to test the first (ODT), not only are you left with nothing to actually identify what each of the metadata components are, the following markup applies to a single line on the specification cover:
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";>http://docs.oasis-open.org/security/saml/Post2.0/</text:a> 
- <text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";> 
<text:file-name text:display="name">sstc-saml-assurance-profile-cd-01</text:file-name> 
</text:a> 
<text:a xlink:type="simple" xlink:href="http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-assurance-profile-cd-01.html";>.html</text:a> 
</text:p> 

The document may actually *look* and *behave* properly, but there's no telling that from the markup. Whereas the DocBook data uses entities to ensure proper values and XSLT to generate the actual hypertext links. 

So, unless everyone is using the same markup vocabulary in the same way, creating automated processing will be extremely difficult at best. And secondly, whether you're converting format-based XML or RTF or anything that's actually encoding the presentation formt rather than the content, it's nearly impossible (or takes a really large budget and a huge team of people).

Mary






> 
> Regards Jamie
> 
> ~ James Bryce Clark
> ~ General Counsel, OASIS
> ~ http://www.oasis-open.org/who/staff.php#clark
> 
> On Thu, Apr 22, 2010 at 2:44 PM, Mary McRae <mary.mcrae@oasis-open.org> wrote:
>> Great point Jamie!
>> 
>> Ken Holman has done an amazing job with the DocBook environment - it's been through several iterations now - and it's almost foolproof. I'm hoping that the DITA environment JoAnn and Don have mentioned will create the same end result - eliminating many of the things that cause problems. It's not just the checking that's quicker, but using the DocBook environment makes it much harder to mess up.
>> 
>> I think the key thing here is that unless a significant percentage of TCs would be taking advantage of it by authoring in a content and structure-based, rather than formatting-based, structured markup language, the development costs can't be justified.
>> 
>> Mary
>>