I don't know, Birgit. When you examine the work of the generalize
and specialize transforms in the root xsl folder of the DITA Open
Toolkit, you will see that all they do is move the specialization
name from the element (<termdeftopic>) to the outputclass
attribute <topic outputclass="termdeftopic"> and back. It is a
design part of the architecture to be able to generalize any
specialization to its base form so that you may respecialize it in a
different way as needed. Michael's design simply starts with that
relaxed form as a template, and a new variant of the
"specialize.xsl" transform will recognize these structural and
semantic hints as implied schema that you can then do many thing
with: save as a DTD, drive the generation of a web form using the
outputclass values as the field labels and names, or automate the
conversion of documents from the relaxed topic type into the
specific specialization type, almost like the specialize.xsl
transform but with two inputs: the source file and the template file
that defines its intended result. The template is not a document
instance in most cases; it is a valid DITA document that follows all
the normal XML rules but encodes intent, which makes it behave like
a schema in that these cues can be applied to all this different
downstream opportunities.
A case in point is that the oXygen editor allows you to load any XML
document and generate the apparent schema that represents that
particular document instance. That schema might not be very useful
in setting up the editor to create other documents of the same type
because the content rules will map only to the original document,
but this derived schema is a great starting point for design. All
Michael is doing is adding hints to make that process smarter so
that the schema generator can make its content models richer and
more general within the needs of the design. This document is not
the model for all documents, it is the pattern for all subsequent
documents, which themselves have none of the syntactic attribute
data because that is all now in the new derived schema that captured
that intent from the template.
I hope this makes sense. It is a powerful capability of DITA to be
able to straddle the roles of both pattern and instance.
On 9/2/2015 3:39 AM, birgit wrote:
Dear Michael,
Yes, you can do it this way but honestly I
don’t like to put syntax information in @outputclass. That’s
just the great thing of DITA that you can specialize new
elements for special syntax/content. Yes, the use of
@outputclass makes is flexible but also more suitable for
errors.
Kind regards, Birgit
Van:
[mailto:] Namens
Michael Priestley
Verzonden: dinsdag 25 augustus 2015 20:52
Aan:
Onderwerp: [dita-lightweight-dita] Specialization by
example - tlotermtopic - basic structure
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
http://dita.xml.org/blog/michael-priestley
--
Don R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don R. Day Skype:
don.r.day
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
This email has been checked for viruses by Avast antivirus software.
www.avast.com
