OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [dita] Lightweight DITA proposal - 13076



This looks great!


Two things occur to me. First, whenever the DITA-light concept comes up, I try to get Andrzej to weigh in (Andrzej, are you listening?). As you probably know, Andrzej has already done a lot of work along these lines with his DITA EDEN proposal. And second, I wonder why this kind of thing is characterized as being for non-technical types. This reminds me of the thread "What do people (really) mean when they say DITA is too complex." Seems like a less-complex version of DITA might appeal to a fair number of mainstream technical DITA users. Who knows?






From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Michael Priestley
Sent: Tuesday, March 20, 2012 6:34 AM
To: dita
Subject: [dita] Lightweight DITA proposal - 13076


Thanks to Kris Eberlein, Don Day, Chris Nitchie, and Robert Anderson for help whipping this initial proposal into shape.

The goal is to create a lightweight DITA framework that can ease adoption for casual, contributing, or non-technical authors. We want to make both editing and specialization easier for vendors to support by limiting options and choice points.

There is a related proposal 13051 for defining starter sets of constrained content models, where we can add more explicit specializations or examples of these constraints in use. For example, 13051 could include a starter set for the DITA concept/task/reference specializations.

Here are my thoughts for the core content models and specialization architecture. I've tried to simplify both the content models and attribute models to eliminate redundancy, and wherever possible support just one way of doing things. I've tried to simplify the specialization architecture to the point where a complete and valid specialization could be easily generated from a simple set of forms. Here they are:

Simplified topic content model

<topic> contains title, shortdesc, body

<shortdesc> contains text or ph

<body> contains section

<section> contains p, ul, ol, simpletable, image
<p> contains text, ph, xref

<ph> contains ph, text

<xref> contains text

<ul>/<ol> contain li

<li> contains p

<simpletable> contains 1 sthead (optional), strow

<sthead>/<strow> contain <stentry>

<stentry> contains p, ul, ol

<image> contains <alt>
<alt> contains text

Total: 16 elements

Simplified topic attribute model

All attributes are optional for specializers except @id on topic, @href on xref and image, and the defaulted @domains and @class attributes. Each attribute or set of attributes below can be included/excluded through predefined constraints.

Conditional content: @props on section, p, ul, ol, simpletable, strow, li, image

Content reuse: @id/@conref on section, p, ul, ol, simpletable, strow, li, image

Variable links: @keyref on xref

Variable content: @keyref on ph, image

Class extension: @outputclass on everything

A note on href: to simplify the linking model, the format and scope attributes are omitted, and their values derived from context. Format will be taken from the file extension (eg .dita, .html), and scope will be local unless the link starts with http://, when it becomes external.

Total, if all enabled: 6 editable attributes plus 2 defaulted ones

Simplified map content model

<map> contains title, topicref

<title> contains text or ph

<ph> contains ph or text

<topicref> contains topicmeta (or modify base topicref model to contain <title> as option before topicmeta)

<topicmeta> contains navtitle

<navtitle> contains text or ph

Total: 6 elements (5 if we add title to topicref base, so we can eliminate the topicmeta containment layer)

Simplified map attribute model

All attributes are optional for specializers, except the defaulted @domains and @class attributes. Each attribute or set of attributes below can be included/excluded through predefined constraints.

Referencing content: @href on topicref
Variable and metadata control: @keys on topicref

Conditional content: @props on map, topicref

Content reuse: @id/@conref on topicref

Variable text: @keyref on ph

Variable links: @keyref on topicref

Class extension: @outputclass on everything

Total, if all enabled: 6 editable attributes plus 2 defaulted ones

Some prepackaged map/attribute combos

TOC map: Referencing content (@href)

TOC/Variable link map: Referencing content, Variable/metadata control (@href, @keys)

Variable text/metadata control map: Variable/metadata control (@keys)

A final thought on the DTDs/XSDs:  I think it could make sense to actually implement these as subset DTDs, rather than using redefinition of the content model entities in the existing DTDs (topic.mod etc.), so that the DTDs/XSDs themselves are easier to understand. This would give us at the TC a few more files to maintain, but considerably less complexity to manage.


Now on to the specialization architecture:

Simplified specialization model

topic: can be specialized to give a semantic container name to the content. Only structural specialization allowed.

section: can create new section specializations as domains that can then be integrated into new topic types using constraints to impose order

ph: can create new ph specializations as domains  

@props: can create new conditional processing attributes as domains

Total specializable elements/attributes: 4

So a new topic type would be constructed by:

1) Defining a new container name (topic element specialization)

2) Pulling in a particular set of section specializations in a particular order (like <goals>, <agenda>, <minutes>, <actionitems>)

3) Choosing the attribute and inline semantics to enable (@props and ph specializations)

A new section type domain would be constructed by:

1) Defining a new container name (section element specialization)

2) Defining its content model - I'd suggest either a single content element from p, ul, ol, simpletable, or allow everything


Finally, some thoughts on a specialization/authoring prototyping architecture. With the simplified rules above, it should be really simple to get someone up and running with authoring and publishing. We could even choose to define topic templates for defining new topic types and new domains, which people could fill in and then feed to a transform to get the actual DTDs/XSDs plus editor-specific and publishing-specific overrides.


<topictypedefinition id="mtgnotes">

       <title>Meeting Notes</title>

       <shortdesc>A topic type for taking notes on meetings</shortdesc>


               <sections><!--contains simpletable-->

Section reference

Generated heading

Authoring prompt

<xref keyref="goals"/>


Describe the goals of the meeting

<xref keyref="agenda"/>


List the agenda items

<xref keyref="minutes"/>


Record discussion




<sectiontypedefinition id="agenda">


       <shortdesc>A reusable section definition for listing agenda items</shortdesc>








From the definition above, a tool could generate DTDs/XSDs, authoring templates, and output overrides. A simple form of authoring template could be just HTML5 output with the authoring prompts included, and title and section content set to contentEditable="true".

Another advantage of having a higher-level definition of the specialization might be that we could generate both a subset-DTD version (easy to understand) and a full-DTD-compatible one (easy to integrate with full DITA), in case there is someone who needs to pull specialized elements from both architectures into a single DTD.

Let me know what you think.

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]