Re: [dita] Learning and Training Proposal: Allow Topicrefs to NestThemselves (Revised)

[Eliot Kimber <ekimber@reallysi.com>]

In response to the previous clarification of the behavior of nested
topicrefs that both specify @chunk "to-content", I officially withdraw my
proposal (A) for nested topicrefs, leaving only what was proposal (B). Below
is a new, standalone proposal text:

The current learningMapDomain does not allow the *Ref topicref types to
nest. This does not allow the creation of learning content structures that
incorporate content from nested topics using map-based references. For
example, it does not allow the creation of a learning content component that
incorporates glossary entries managed as reusable components. I have at
least one client that has exactly this requirement.

The motivation for this constraint with the SCORM requirement that all
content be structured as single artifacts (e.g., single HTML pages).
However, the @chunk facility allows the SCORM requirement to be satisfied
without the need to restrict topicref nesting.

I also observe that the architectural spec actually assumed that the L&T
design reflected this proposal, with this language from the Chunk topic:

"Identification of a set of topics as a unit

  A curriculum developer wants to compose a lesson for a SCORM LMS (Learning
Management System) from a set of topics without constraining reuse of those
topics. The LMS can save and restore the learner's progress through the
lesson if the lesson is identified as a referenceable unit. The curriculum
developer defines the collection of topics with a DITA map, using the chunk
attribute to identify the learning module as a unit before generating the
SCORM manifest."

This proposal satisfies both the original SCORM requirement and the
map-based reuse requirement.

Proposal: Provide new topicref type learningContentComponentRef, set
default for @chunk on learningContentRef to "to-content"

The learningContentComponentRef topicref type enables references to
subcomponents of Learning Content nodes in a map tree.

Content model changes:

1. Declare new topicref type learningContentComponentRef:

<!ENTITY % learningContentComponentRef.content
                       "((%topicmeta;)?,
                         (% learningContentComponentRef;)*)"
>
<!ENTITY % learningContentComponentRef.attributes
             "%learningDomain-topicref-atts;
              type
                        CDATA
                                  #IMPLIED
              format
                        CDATA
                                  'dita'"
>
<!ELEMENT learningContentComponentRef    %
learningContentComponentRef.content;>
<!ATTLIST learningContentComponentRef    %
learningContentComponentRef.attributes;>
<!ATTLIST learningContentComponentRef %global-atts;
    class CDATA "+ map/topicref learningmap-d/ learningContentComponentRef
">

2. Set default for @chunk on learningContentRef to "to-content":

<!ENTITY % learningContentRef.attributes
             "type
                        CDATA
                                  #IMPLIED
              format
                        CDATA
                                  'dita'"
              navtitle
                        CDATA
                                  #IMPLIED
              id
                        ID
                                  #IMPLIED
              href
                        CDATA
                                  #IMPLIED
              keyref
                        CDATA
                                  #IMPLIED
              keys
                        CDATA
                                  #IMPLIED
              query
                        CDATA
                                  #IMPLIED
              %conref-atts;
              copy-to
                        CDATA
                                  #IMPLIED
              outputclass
                        CDATA
                                  #IMPLIED
              scope
                        (external |
                         local |
                         peer |
                         -dita-use-conref-target)
                                  #IMPLIED
              processing-role
                        (normal |
                         resource-only |
                         -dita-use-conref-target)
                                  #IMPLIED
              linking
                        (targetonly|
                         sourceonly|
                         normal|
                         none |
                         -dita-use-conref-target)
                                  #IMPLIED
              locktitle
                        (yes|
                         no |
                         -dita-use-conref-target)
                                  #IMPLIED
              toc
                        (yes|
                         no |
                         -dita-use-conref-target)
                                  #IMPLIED
              print
                        (yes|
                         no |
                         -dita-use-conref-target)
                                   #IMPLIED
              search
                        (yes|
                         no |
                         -dita-use-conref-target)
                                   #IMPLIED
              chunk
                        CDATA
                                  "to-content"
              %select-atts;
              %localization-atts;"
>


Specification changes:

- Document new element type learningContentComponentRef

- Update documentation for learningContentRef to reflect default value for
@chunk.

Processor Changes

  - Processors that do not currently support @chunk would need to support
it. No change for new topicref type assuming all processors are
specialization-aware.




----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>