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

 


Help: OASIS Mailing Lists Help | MarkMail Help

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


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]