dita-lightweight-dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Specialization by example - tlotermtopic - adding domains and a conref example
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: dita-lightweight-dita@lists.oasis-open.org
- Date: Fri, 18 Sep 2015 15:49:44 -0400
What I've added/changed
Ok, changing this up a bit - changing
collection-type attribute to specmodel attribute since I think that's clearer,
and changing contentrole to specrole with an extra model-only value.
And then adding some data element specializations
to the prolog for managing domain enhancements (specializations of ph,
props, data). Constraints and extensions still TBD.
Attribute usage in this specialization
model
- specmodel attribute: whether
a content model is sequence or choice or inherited (if unset, inherited
from ancestor type)
- specrole attribute: whether the content
of an element is intended to be generated by the transform, editable by
the author, an editor prompt, documentation, or used for content modeling
purposes only (or any mix of the above) - if unset, element content is
editable by author (part of template)
- outputclass: provides the element-specific
class value for the specialized element (to be concatenated with the topic-level
class value for the full result).
Specialized data elements in this
specialization model
- specmeta contains any number of ph,
data, or specatt elements (note: specialized from <data>, not <metadata>,
so we can include <ph> in the content model)
- specatt contains text only - or we
could extend it to allow an xref that could reference a map for controlled
values for the attribute
And here's the actual example that
would generate the <tlotermtopic> specialization
I'm including an extra <prereqs>
section borrowed from task just to show off conref working to assemble
a specialization with reuse of elements across types. I'm also showing
a specialized author element in prolog. The domain extensions go in a new
section of the prolog called specmeta, specialized from data.
<topic id="termdef_term"
outputclass="tlotermtopic"
<title outputclass="tloterm">Structured
Content</title>
<prolog
outputclass="tlotermprolog">
<data
outputclass="tlotermauthor" specrole="prompt">author
name here</data>
<specmeta>
<ph outputclass="tlophrase" specrole="doc">A
new global phrase element</p>
<data outputclass="tlodata" specmodel="choice"
specrole="modelonly">Simple text only for this global data
specialization, but with a different specmodel you could do anything</data>
<specatt outputclass="tloatt"
specrole="doc">A conditional processing attribute called tloatt</specatt>
<body outputclass="tlotermbody"
specmodel="sequence">
<section outputclass="tlowhat">
<title specrole="generate">What is it?</title>
<p>...</p></section>
<section outputclass="tlowhy">
<title specrole="generate">Why is it important?</title>
<p>...</p></section>
<section outputclass="tloessay">
<title specrole="generate">Why does a technical
writer need to know this?</title>
<p>...</p></section>
<section outputclass="tlosummary"
collection-type="sequence">
<title specrole="generate">Summary:</title>
<p>...</p></section>
<section
conref="task-spec.dita/task-def/postreqs"/>
</body>
</topic>
And the specialized topic type template
it would create:
<tlotermtopic id="termdef_term">
<tloterm>Structured
Content</tloterm>
<tlotermprolog>
<tlotermauthor>Don Day</tlotermauthor>
</tlotermprolog>
<tlotermbody>
<tlowhat><p>...</p></tlowhat>
<tlowhy><p>...</p></tlowhy>
<tloessay><p>...</p></tloessay>
<tlosummary><p>...</p></tlosummary>
<postreqs><p>...</p></postreqs>
</tlotermbody>
</tlotermtopic>
I'm not showing all the generated class
and domain attribute values because they'd be defaulted by the doctype
- but they'd include things like the appropriate domain declarations, and
a cross-type dependency on task as part of the specialization, because
it pulls in the postreqs element.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From:
Michael Priestley/Toronto/IBM@IBMCA
To:
"dita-lightweight-dita@lists.oasis-open.org"
<dita-lightweight-dita@lists.oasis-open.org>
Date:
08/25/2015 02:52 PM
Subject:
[dita-lightweight-dita]
Specialization by example - tlotermtopic - basic structure
Sent by:
<dita-lightweight-dita@lists.oasis-open.org>
Taking Don's example, and ignoring the
metadata portions for now - just the basic section structures.
I wanted to capture:
- whether a content model is a sequence or a choice
with a new attribute - collection-type - "borrowed"
from map)
if there is no collection-type, then it inherits
the content model from its ancestor (including what elements are allowed
- no need to define them all every time)
- which elements are required vs optional
(defaults to required in a sequence, default
to optional in a choice)
using the importance attribute with restricted
values
- when a title/label or other content is intended to be generated vs author-edited
vs template-only (eg prompt text) or documentation
with a new attribute contentrole with restricted
values (editable, prompt, generate, doc)
Still to capture:
- metadata attribute specialization
- global/domain specializations of ph element, data element, props attribute
- constraints definition, including use of predefined constraints, or new
constraints such as a global element removal, addition, or substitition
- show how conref could be used to assemble topic types and reuse domains
from existing elements in other specification topics
<topic id="termdef_term" outputclass="termdeftopic"
<title outputclass="tloterm">Structured
Content</title>
<body outputclass="tlotermbody"
collection-type="sequence">
<section outputclass="tlowhat">
<title contentrole="generate">What is it?</title>
<p>...</p></section>
<section outputclass="tlowhy">
<title contentrole="generate">Why is it important?</title>
<p>...</p></section>
<section outputclass="tloessay">
<title contentrole="generate">Why does a technical
writer need to know this?</title>
<p>...</p></section>
<section outputclass="tlosummary"
collection-type="sequence">
<title contentrole="generate">Summary:</title>
<p>...</p></section>
</body>
</topic>
In this example, all the sections have titles to be generated. All of them
have content models that are inherited from <section>, so allow more
than <p>, except for <tlosummary> that requires a single <p>
element (I could also have expressed this by saying it was collection-type="choice"
and making the <p> importance="required" explicitly).
Some things we could validate for:
- if importance is set with a parent that doesn't
have collection-type set
- if outputclass is set with a parent that
doesn't have outputclass set (unless it's also listed wherever/however
we define domain specializations)
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]