Lightweight DITA SC

  • 1.  Quick overview of current topic definition with questions for discussion

    Posted 06-01-2015 01:34
    Figuring it might be easier to discuss something higher level than the actual DTD files... Here's the current (rough) structure of the strawman: Topic specialization/customization ---------- Can be specialized by defining a new topic element and a body element that incorporates section modules in a specific sequence/organization. Section specializations are designed to be easily sharable across topic specializations. Each section specialization can include further-specialized block elements if needed. Can be extended by incorporating domains at the phrase or attribute level. Attributes and content model behaviors can be modified by redefining attributes and declaring appropriate constraints: Out of the box constraints available are: filters - controls whether @props attribute and any of its specializations are available reuse - controls whether @id and @conref are available on blocks variable-content - controls whether @keyref is available on <ph> , <image>, <data> localization - controls whether @dir, @xml:lang, and @translate are available on most elements nested-blocks - controls whether lists can be nested Q: in this model, you can easily share specialized section designs across topic specializations, but you cannot easily share specialized block-level designs (eg a specialized table) across section specializations. Is that acceptable? The alternative is to either open up full domain specialization for blocks as well as phrases,  or create a new method of extension that is parallel to domain extension but leverages the basic content model entities instead of creating redefinable entities for every mention of every element. Q: do we want to open up/doc redefining other content model entities arbitrarily, eg to add your own elements back in from base DITA? Q: do we want to break DITA here, by allowing the introduction of specialized elements through entity redefinition as well? What would be the processing model implications? Q: do we want to also consider breaking DITA in the way we declare constraints, to make it simpler and more flexible? For example adding in new elements, just declare them in the constraints attribute as (+xxx); removing existing elements, same thing but -xxx. Topic content model ---------- The following common content models are controlled with entities: common-inline: inline text, ph and its specializations, image, and data all-inline: same as common-inline plus xref, data, and data's specializations common-blocks: p, ul, ol, dl, pre, object, and object's specializations all-blocks: same as common-blocks plus simpletable nested-blocks: same as all-blocks (but only used in the content model of other blocks, so it can be redefined to turn off block nesting) Structural elements - all elements have default class attribute topic - requires @id, plus defaulted values for ditaarch and domains title - contains common-inline, has  entity-controlled localization attributes shortdesc - contains common-inline, has  entity-controlled localization attributes prolog - contains any number of data elements body - contains all-blocks, followed by any number of sections; has  entity-controlled localization attributes section - contains optional title, followed by all-blocks; has  entity-controlled localization, filters, reuse attributes Block-level elements (except table, object) - all elements have default class attribute, plus entity-controlled localization, filters, reuse attributes p - contains all-inline ul/ol - contains any number of li li - contains nested-blocks dl - contains any number of dlentry dlentry - contains dt, dd dt - contains all-inline dd - contains nested-blocks pre - contains all-inline; has defaulted xml:space attribute Table elements  - all elements have default class attribute, plus optional localization, filters, reuse attributes simpletable - contains optional sthead, any number of strow; sthead/strow - contains any number of stentry stentry - contains common-blocks Object and image elements - all elements have default class attribute object - contains optional desc, followed by any number of param; has data, type, height, width, name, usemap attributes plus entity-controlled localization, filters, reuse attributes desc - contains common-inline, has  entity-controlled localization attributes param - contains nothing, has required name and optional value attributes image - contains optional alt element; has href, height, width attributes plus  entity-controlled localization and variable-content attributes alt - contains common-inline, has  entity-controlled localization and variable-content attributes Inline elements ph - contains all-inline; has entity-controlled localization and variable-content attributes data - contains number data elements; has optional name/value attributes, plus entity-controlled variable-content attributes xref - contains common-inline; has href, format, scope attributes, plus entity-controlled localization and variable-links attributes Q: object has been defined as an entity to allow video and audio to be introduced as specializations; do we want to just ditch object, and go with video/audio from the start? Q: this list doesn't include <note> - I know that's been controversial, and I'm open to including it - do we want to map it to an html5 <aside> element? Maybe even rename it to that, to broaden its potential usage? Q: this is using simpletable, elsewhere I've tried a simplified form of CALS. Does anyone have a preference? Either way we're not allowing any complex table features - no column spanning, etc. Maybe we start with simpletable, but allow for the possibility of people reintroducing full table during customization? I almost wish we could just go with HTML tables here for the sake of easy mapping to HTML5, but that would really break all our existing DITA tooling. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley


  • 2.  Re: [dita-lightweight-dita] Quick overview of current topic definition with questions for discussion

    Posted 06-01-2015 13:36
    Hi all - Here's my comments on Michael's overview, from a learning, training, and educational content pov. 1) The topic specialization by section approach works. The most important section type for educational content is Objectives (lcObjectives in the 1.2 L&T specialization). It's potentially limiting to restrict topics to a specific sequence of sections, and not have the ability to provide available sections, but let them be used in any order. But we can probably live with that. On the approaches for specializing, I'm in favor of anything that makes this easier and lighter-weight, and look forward to the discussions. 2) On restrictions around specialized block designs, this would limit the ability to use the L&T question-answer types anywhere in a topic. Though we can use them in a specialized topic/section specific to assessments, we also benefited from the ability to include questions as a domain specialization, making it possible to include a quick true-false question in the middle of a content topic, and so forth. This could be a significant limit. 3) On object and video/audio, I'd say ditch object and go with html video/audio from the start. 4) On note, I'm intrigued with the idea of using aside. This may get tricky, in that html asides behave more like a special-purpose section (asides typically start with a heading/title, and we don't include a title for notes).  But I like the idea of ditching note for aside, assuming we can include a way to easily create the various special-purpose asides that would be useful for education. And as an aside, reveal.js uses aside as a container for the presentation speaker notes. So we might have to expect different groupings of content into an aside from html output processing. Thanks. John Hunt Senior Technical Content Architect IBM Enterprise Social Software john_hunt@us.ibm.com From:         Michael Priestley <mpriestl@ca.ibm.com> To:         dita-lightweight-dita@lists.oasis-open.org Date:         05/31/2015 09:34 PM Subject:         [dita-lightweight-dita] Quick overview of current topic definition with questions for discussion Sent by:         <dita-lightweight-dita@lists.oasis-open.org> Figuring it might be easier to discuss something higher level than the actual DTD files... Here's the current (rough) structure of the strawman: Topic specialization/customization ---------- Can be specialized by defining a new topic element and a body element that incorporates section modules in a specific sequence/organization. Section specializations are designed to be easily sharable across topic specializations. Each section specialization can include further-specialized block elements if needed. Can be extended by incorporating domains at the phrase or attribute level. Attributes and content model behaviors can be modified by redefining attributes and declaring appropriate constraints: Out of the box constraints available are: filters - controls whether @props attribute and any of its specializations are available reuse - controls whether @id and @conref are available on blocks variable-content - controls whether @keyref is available on <ph> , <image>, <data> localization - controls whether @dir, @xml:lang, and @translate are available on most elements nested-blocks - controls whether lists can be nested Q: in this model, you can easily share specialized section designs across topic specializations, but you cannot easily share specialized block-level designs (eg a specialized table) across section specializations. Is that acceptable? The alternative is to either open up full domain specialization for blocks as well as phrases,  or create a new method of extension that is parallel to domain extension but leverages the basic content model entities instead of creating redefinable entities for every mention of every element. Q: do we want to open up/doc redefining other content model entities arbitrarily, eg to add your own elements back in from base DITA? Q: do we want to break DITA here, by allowing the introduction of specialized elements through entity redefinition as well? What would be the processing model implications? Q: do we want to also consider breaking DITA in the way we declare constraints, to make it simpler and more flexible? For example adding in new elements, just declare them in the constraints attribute as (+xxx); removing existing elements, same thing but -xxx. Topic content model ---------- The following common content models are controlled with entities: common-inline: inline text, ph and its specializations, image, and data all-inline: same as common-inline plus xref, data, and data's specializations common-blocks: p, ul, ol, dl, pre, object, and object's specializations all-blocks: same as common-blocks plus simpletable nested-blocks: same as all-blocks (but only used in the content model of other blocks, so it can be redefined to turn off block nesting) Structural elements - all elements have default class attribute topic - requires @id, plus defaulted values for ditaarch and domains title - contains common-inline, has  entity-controlled localization attributes shortdesc - contains common-inline, has  entity-controlled localization attributes prolog - contains any number of data elements body - contains all-blocks, followed by any number of sections; has  entity-controlled localization attributes section - contains optional title, followed by all-blocks; has  entity-controlled localization, filters, reuse attributes Block-level elements (except table, object) - all elements have default class attribute, plus entity-controlled localization, filters, reuse attributes p - contains all-inline ul/ol - contains any number of li li - contains nested-blocks dl - contains any number of dlentry dlentry - contains dt, dd dt - contains all-inline dd - contains nested-blocks pre - contains all-inline; has defaulted xml:space attribute Table elements  - all elements have default class attribute, plus optional localization, filters, reuse attributes simpletable - contains optional sthead, any number of strow; sthead/strow - contains any number of stentry stentry - contains common-blocks Object and image elements - all elements have default class attribute object - contains optional desc, followed by any number of param; has data, type, height, width, name, usemap attributes plus entity-controlled localization, filters, reuse attributes desc - contains common-inline, has  entity-controlled localization attributes param - contains nothing, has required name and optional value attributes image - contains optional alt element; has href, height, width attributes plus  entity-controlled localization and variable-content attributes alt - contains common-inline, has  entity-controlled localization and variable-content attributes Inline elements ph - contains all-inline; has entity-controlled localization and variable-content attributes data - contains number data elements; has optional name/value attributes, plus entity-controlled variable-content attributes xref - contains common-inline; has href, format, scope attributes, plus entity-controlled localization and variable-links attributes Q: object has been defined as an entity to allow video and audio to be introduced as specializations; do we want to just ditch object, and go with video/audio from the start? Q: this list doesn't include <note> - I know that's been controversial, and I'm open to including it - do we want to map it to an html5 <aside> element? Maybe even rename it to that, to broaden its potential usage? Q: this is using simpletable, elsewhere I've tried a simplified form of CALS. Does anyone have a preference? Either way we're not allowing any complex table features - no column spanning, etc. Maybe we start with simpletable, but allow for the possibility of people reintroducing full table during customization? I almost wish we could just go with HTML tables here for the sake of easy mapping to HTML5, but that would really break all our existing DITA tooling. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley


  • 3.  Re: [dita-lightweight-dita] Quick overview of current topic definition with questions for discussion

    Posted 06-29-2015 16:35
    Here is a re-posting Michael Priestley's post from 5/31/15. We discussed this in today's LW DITA SC meeting. The specialization proposal is at the top. Mark On 5/31/2015 6:33 PM, Michael Priestley wrote: Figuring it might be easier to discuss something higher level than the actual DTD files... Here's the current (rough) structure of the strawman: Topic specialization/customization ---------- Can be specialized by defining a new topic element and a body element that incorporates section modules in a specific sequence/organization. Section specializations are designed to be easily sharable across topic specializations. Each section specialization can include further-specialized block elements if needed. Can be extended by incorporating domains at the phrase or attribute level. Attributes and content model behaviors can be modified by redefining attributes and declaring appropriate constraints: Out of the box constraints available are: filters - controls whether @props attribute and any of its specializations are available reuse - controls whether @id and @conref are available on blocks variable-content - controls whether @keyref is available on <ph> , <image>, <data> localization - controls whether @dir, @xml:lang, and @translate are available on most elements nested-blocks - controls whether lists can be nested Q: in this model, you can easily share specialized section designs across topic specializations, but you cannot easily share specialized block-level designs (eg a specialized table) across section specializations. Is that acceptable? The alternative is to either open up full domain specialization for blocks as well as phrases,  or create a new method of extension that is parallel to domain extension but leverages the basic content model entities instead of creating redefinable entities for every mention of every element. Q: do we want to open up/doc redefining other content model entities arbitrarily, eg to add your own elements back in from base DITA? Q: do we want to break DITA here, by allowing the introduction of specialized elements through entity redefinition as well? What would be the processing model implications? Q: do we want to also consider breaking DITA in the way we declare constraints, to make it simpler and more flexible? For example adding in new elements, just declare them in the constraints attribute as (+xxx); removing existing elements, same thing but -xxx. Topic content model ---------- The following common content models are controlled with entities: common-inline: inline text, ph and its specializations, image, and data all-inline: same as common-inline plus xref, data, and data's specializations common-blocks: p, ul, ol, dl, pre, object, and object's specializations all-blocks: same as common-blocks plus simpletable nested-blocks: same as all-blocks (but only used in the content model of other blocks, so it can be redefined to turn off block nesting) Structural elements - all elements have default class attribute topic - requires @id, plus defaulted values for ditaarch and domains title - contains common-inline, has  entity-controlled localization attributes shortdesc - contains common-inline, has  entity-controlled localization attributes prolog - contains any number of data elements body - contains all-blocks, followed by any number of sections; has  entity-controlled localization attributes section - contains optional title, followed by all-blocks; has  entity-controlled localization, filters, reuse attributes Block-level elements (except table, object) - all elements have default class attribute, plus entity-controlled localization, filters, reuse attributes p - contains all-inline ul/ol - contains any number of li li - contains nested-blocks dl - contains any number of dlentry dlentry - contains dt, dd dt - contains all-inline dd - contains nested-blocks pre - contains all-inline; has defaulted xml:space attribute Table elements  - all elements have default class attribute, plus optional localization, filters, reuse attributes simpletable - contains optional sthead, any number of strow; sthead/strow - contains any number of stentry stentry - contains common-blocks Object and image elements - all elements have default class attribute object - contains optional desc, followed by any number of param; has data, type, height, width, name, usemap attributes plus entity-controlled localization, filters, reuse attributes desc - contains common-inline, has  entity-controlled localization attributes param - contains nothing, has required name and optional value attributes image - contains optional alt element; has href, height, width attributes plus  entity-controlled localization and variable-content attributes alt - contains common-inline, has  entity-controlled localization and variable-content attributes Inline elements ph - contains all-inline; has entity-controlled localization and variable-content attributes data - contains number data elements; has optional name/value attributes, plus entity-controlled variable-content attributes xref - contains common-inline; has href, format, scope attributes, plus entity-controlled localization and variable-links attributes Q: object has been defined as an entity to allow video and audio to be introduced as specializations; do we want to just ditch object, and go with video/audio from the start? Q: this list doesn't include <note> - I know that's been controversial, and I'm open to including it - do we want to map it to an html5 <aside> element? Maybe even rename it to that, to broaden its potential usage? Q: this is using simpletable, elsewhere I've tried a simplified form of CALS. Does anyone have a preference? Either way we're not allowing any complex table features - no column spanning, etc. Maybe we start with simpletable, but allow for the possibility of people reintroducing full table during customization? I almost wish we could just go with HTML tables here for the sake of easy mapping to HTML5, but that would really break all our existing DITA tooling. Michael Priestley, Senior Technical Staff Member (STSM) Enterprise Content Technology Strategist mpriestl@ca.ibm.com http://dita.xml.org/blog/michael-priestley