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: Re: [dita-lightweight-dita] Specialization by example - tlotermtopic - basic structure

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: dita-lightweight-dita@lists.oasis-open.org [mailto:dita-lightweight-dita@lists.oasis-open.org] Namens Michael Priestley
Verzonden: dinsdag 25 augustus 2015 20:52
Aan: dita-lightweight-dita@lists.oasis-open.org
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>
                <section outputclass="tlowhy">
                        <title contentrole="generate">Why is it important?</title>
                <section outputclass="tloessay">
                        <title contentrole="generate">Why does a technical writer need to know this?</title>
                <section outputclass="tlosummary" collection-type="sequence">
                        <title contentrole="generate">Summary:</title>

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

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

Avast logo

This email has been checked for viruses by Avast antivirus software.

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