Loading ...
Sorry, an error occurred while loading the content.

[Specialization][DITA 1.1] When to rename an element tag?

Expand Messages
  • ghkrause
    Dear specialization specialists at dita-users! Today I have a maybe philosophical question related to DITA 1.1. Without confirmation from others in the
    Message 1 of 10 , Apr 1, 2009
    • 0 Attachment
      Dear specialization specialists at dita-users!

      Today I have a maybe philosophical question related to DITA 1.1.
      Without confirmation from others in the community or additional
      thoughts I am not keen enough to proceed my specialization task ...

      A structural specialization where my only intend is to reduce
      the options that the default dita dtd offers comprises:
      - less child elements (like no <ol> in <p>)
      - fixed sequence of child elements instead of a flexible
      choice of children

      Do I need to do any of the following steps for this restricted
      specialization scenario?
      a) Change Public ID in DOCTYPE statement?
      b) Change root node name?
      c) Change element name of any modified element?

      I assume that (a) is a good idea, (b) is optional and (c)
      is not necessary - do you agree?

      Use case:
      Currently I think of maintaining two sets of DTD: a restricted
      one for authoring and the DITA standard DTDs in Open Toolkit.
      Editing would follow the more rigid DTD but any valid DITA topic
      from other sources would validate when rendered as part of a map.
      In this case I consider neither a, b nor c to be helpful.
      ==> This is a special specialization that may not be regarded
      as specialization or at least is difficult to detect.

      Problem:
      Authors that know DITA or that use standard DITA manuals and
      cheat sheets are confused due to the fact that they cannot guess
      from the name of tag whether its structure is 'DITA standard' or
      'Gunnar's reduced'.

      Any comment is appreciated!

      Gunnar H. Krause, Senior Manager, Qimonda TechDoc
    • Deborah Pickett
      Hi Gunnar, ... [...] ... That s about right. Personally I would consider (a) mandatory outside of a just testing sandbox, to save my authors from any
      Message 2 of 10 , Apr 1, 2009
      • 0 Attachment
        Hi Gunnar,

        ghkrause wrote:
        > Today I have a maybe philosophical question related to DITA 1.1.
        > Do I need to do any of the following steps for this restricted
        > specialization scenario?
        [...]
        > a) Change Public ID in DOCTYPE statement?
        > b) Change root node name?
        > c) Change element name of any modified element?
        > I assume that (a) is a good idea, (b) is optional and (c)
        > is not necessary - do you agree?

        That's about right. Personally I would consider (a) mandatory outside
        of a "just testing" sandbox, to save my authors from any confusion.

        A good example of (b) and (c) in action is the DITA <concept> document
        type. The content model of <conbody> is a little more restrictive than
        <topic>'s <body>.

        In the case of the concept document type, it was chosen to do both (b)
        and (c), because it might happen that you have a ditabase <dita> element
        which has both <topic> and <concept> children. With that scenario, (b)
        and (c) become mandatory because you can't have the same element with
        different content models in different parts of the ditabase document.

        If you aren't going to mix-and-match your document type with the shipped
        one of the same name, then (b) and (c) become up to personal preference
        (and perhaps depend on what you are trying to represent with those
        document types). I tended to always change the element names because I
        wanted to be more interoperable with material that was authored from
        outside my group.
      • seth park
        Definitely change the dtd identifier. Any change means it s not what it was. i wouldnt change the core vocabulary just because i wanted to change the grammar.
        Message 3 of 10 , Apr 1, 2009
        • 0 Attachment
          Definitely change the dtd identifier. Any change means it's not what it was.

          i wouldnt change the core vocabulary just because i wanted to change the grammar. it can be a very contrived process to come up with unique element names. unless there is a clear benefit and you are making the vocabulary more semantically relevant, i dont see any value in arbitrarily changing element names...not for the sake of making it appear to be different from core DITA. the dtd identifier should inform users that the grammar is different.

          in general, i wouldnt rename an element unless there was a business reason for doing so, such as more intuitive authoring, more efficient reporting, or more precise control of presentation.

          -seth
        • leha_spas
          Hallo Gunnar, I was always convinced that (c) is actually a MUST in DITA specialization given you plan to change element content model. Otherwise how can
          Message 4 of 10 , Apr 2, 2009
          • 0 Attachment
            Hallo Gunnar,

            I was always convinced that (c) is actually a MUST in DITA specialization given you plan to change element content model. Otherwise how can content later on go through possible generalization? Also point mentioned by Deborah with ditabase would be another consequence of such violation.

            In article about specialization: http://www.ibm.com/developerworks/xml/library/x-dita2/  there is a section "Appendix: Rules for specialization" with summary table of specialization rules. All "Allowed specialization" in table are starting with "Rename..". there is no option named just "Change model"

            So my question would be: is option (c) really an optional thing or a MUST according to DITA Specialization?

            This can be more seen as "Customization of subset". Here is what DITA spec is saying about his(http://docs.oasis-open.org/dita/v1.1/CD01/archspec/speclimits.html ):

            "DITA markup is organized into domain and structural type modules so that authoring groups can easily select the markup subset they require by creating a new document type shell. However, when an authoring group requires a subset of markup rules that does not follow the boundaries of the type modules (for example, global removal of certain attributes or elements), you can if necessary create a customized document type for the sake of enforcing these rules at authoring time, as long as the document types are validated using a standards-compliant document type at processing time.

            A customized subset document type should be created without editing of the type modules. The document type shell can override entities in the module files, including attributes and content models, by providing a new definition of the entity before importing the module files.

            Customized subset document types are not conformant with the DITA standard, and may not be supported by standards-conformant tools. For example, if you customize document types to remove the <xref> element, you may not be able to use off-the-shelf DITA editors to create your content."

            IMHO approach with new element names is more appropriate. And to go this way will not mean  inventing new vocabulary like mentioned by seth park in previous post. It is enough to introduce own prefix to changed elements. In this way editors will clearly distinguish 'Gunnar's reduced' elements from standard DITA.

            BTW: If  (c) is MUST than (b) will a MUST too. See http://docs.oasis-open.org/dita/v1.1/CD01/archspec/infodom.html  :
            "When new elements are introduced through structural specialization, the elements that contain the new elements must be specialized as well; and the new container elements must have their containers specialized in turn, all the way to the root element for the module (for example, the <topic> element or <map> element)."


            ----
            Alexey Spas | Senior IT Manager

            Phone +49 (0)711-993385 94
            Fax +49 (0)711-993385 99
            www.ditaworks.com 

            --- In dita-users@yahoogroups.com, "ghkrause" <gunnar.krause@...> wrote:
            >
            > Dear specialization specialists at dita-users!
            >
            > Today I have a maybe philosophical question related to DITA 1.1.
            > Without confirmation from others in the community or additional
            > thoughts I am not keen enough to proceed my specialization task ...
            >
            > A structural specialization where my only intend is to reduce
            > the options that the default dita dtd offers comprises:
            > - less child elements (like no <ol> in <p>)
            > - fixed sequence of child elements instead of a flexible
            > choice of children
            >
            > Do I need to do any of the following steps for this restricted
            > specialization scenario?
            > a) Change Public ID in DOCTYPE statement?
            > b) Change root node name?
            > c) Change element name of any modified element?
            >
            > I assume that (a) is a good idea, (b) is optional and (c)
            > is not necessary - do you agree?
            >
            > Use case:
            > Currently I think of maintaining two sets of DTD: a restricted
            > one for authoring and the DITA standard DTDs in Open Toolkit.
            > Editing would follow the more rigid DTD but any valid DITA topic
            > from other sources would validate when rendered as part of a map.
            > In this case I consider neither a, b nor c to be helpful.
            > ==> This is a special specialization that may not be regarded
            > as specialization or at least is difficult to detect.
            >
            > Problem:
            > Authors that know DITA or that use standard DITA manuals and
            > cheat sheets are confused due to the fact that they cannot guess
            > from the name of tag whether its structure is 'DITA standard' or
            > 'Gunnar's reduced'.
            >
            > Any comment is appreciated!
            >
            > Gunnar H. Krause, Senior Manager, Qimonda TechDoc
            >
          • Chris Turchin
            Hi Gunnar, Since a subset is (DTD) valid according the to the rules of the superset, I do question if it is really worth the effort to rename each and every
            Message 5 of 10 , Apr 3, 2009
            • 0 Attachment
              Hi Gunnar,

              Since a subset is (DTD) valid according the to the rules of the superset, I do question if it is really worth the effort to rename each and every changed element. Even the spec does not seem to imply it is necessary:

              "The (subset) document type ... can override entities in the module files ... by providing a new definition of the entity before importing the module files."

              Nothing there indicating I must rename the elements including these new entities.

              For example, assuming I wanted to subset <entry> in <table> and not allow #PCDATA parallel to <p>, would I then have to subset and rename <entry> because its model is reduced? But I would then have to update the content model of <row> to contain <chrisEntry> and <tbody> to contain <chrisRow> etc. etc.?

              I just don't see the benefit. However, I definitely do see the benefit of providing authors with a reduced set of options when authoring DITA. Most XML editors provide the application developer features to suppress unwanted elements and attributes from the author (I like XMetaL's ability to turn domain specializations on and off, for example). For me it becomes a question, if I need a subset, is it easier to do it in the editor or in the information model?

              Regards,
              --chris


              On Thu, Apr 2, 2009 at 2:44 PM, leha_spas <leha@...> wrote:
              Hallo Gunnar,

              I was always convinced that (c) is actually a MUST in DITA specialization given you plan to change element content model. Otherwise how can content later on go through possible generalization? Also point mentioned by Deborah with ditabase would be another consequence of such violation.

              In article about specialization: http://www.ibm.com/developerworks/xml/library/x-dita2/  there is a section "Appendix: Rules for specialization" with summary table of specialization rules. All "Allowed specialization" in table are starting with "Rename..". there is no option named just "Change model"

              So my question would be: is option (c) really an optional thing or a MUST according to DITA Specialization?

              This can be more seen as "Customization of subset". Here is what DITA spec is saying about his(http://docs.oasis-open.org/dita/v1.1/CD01/archspec/speclimits.html ):

              "DITA markup is organized into domain and structural type modules so that authoring groups can easily select the markup subset they require by creating a new document type shell. However, when an authoring group requires a subset of markup rules that does not follow the boundaries of the type modules (for example, global removal of certain attributes or elements), you can if necessary create a customized document type for the sake of enforcing these rules at authoring time, as long as the document types are validated using a standards-compliant document type at processing time.

              A customized subset document type should be created without editing of the type modules. The document type shell can override entities in the module files, including attributes and content models, by providing a new definition of the entity before importing the module files.

              Customized subset document types are not conformant with the DITA standard, and may not be supported by standards-conformant tools. For example, if you customize document types to remove the <xref> element, you may not be able to use off-the-shelf DITA editors to create your content."

              IMHO approach with new element names is more appropriate. And to go this way will not mean  inventing new vocabulary like mentioned by seth park in previous post. It is enough to introduce own prefix to changed elements. In this way editors will clearly distinguish 'Gunnar's reduced' elements from standard DITA.

              BTW: If  (c) is MUST than (b) will a MUST too. See http://docs.oasis-open.org/dita/v1.1/CD01/archspec/infodom.html  :
              "When new elements are introduced through structural specialization, the elements that contain the new elements must be specialized as well; and the new container elements must have their containers specialized in turn, all the way to the root element for the module (for example, the <topic> element or <map> element)."


              ----
              Alexey Spas | Senior IT Manager

              Phone +49 (0)711-993385 94
              Fax +49 (0)711-993385 99
              www.ditaworks.com 

              --- In dita-users@yahoogroups.com, "ghkrause" <gunnar.krause@...> wrote:
              >
              > Dear specialization specialists at dita-users!
              >
              > Today I have a maybe philosophical question related to DITA 1.1.
              > Without confirmation from others in the community or additional
              > thoughts I am not keen enough to proceed my specialization task ...
              >
              > A structural specialization where my only intend is to reduce
              > the options that the default dita dtd offers comprises:
              > - less child elements (like no <ol> in <p>)
              > - fixed sequence of child elements instead of a flexible
              > choice of children
              >
              > Do I need to do any of the following steps for this restricted
              > specialization scenario?
              > a) Change Public ID in DOCTYPE statement?
              > b) Change root node name?
              > c) Change element name of any modified element?
              >
              > I assume that (a) is a good idea, (b) is optional and (c)
              > is not necessary - do you agree?
              >
              > Use case:
              > Currently I think of maintaining two sets of DTD: a restricted
              > one for authoring and the DITA standard DTDs in Open Toolkit.
              > Editing would follow the more rigid DTD but any valid DITA topic
              > from other sources would validate when rendered as part of a map.
              > In this case I consider neither a, b nor c to be helpful.
              > ==> This is a special specialization that may not be regarded
              > as specialization or at least is difficult to detect.
              >
              > Problem:
              > Authors that know DITA or that use standard DITA manuals and
              > cheat sheets are confused due to the fact that they cannot guess
              > from the name of tag whether its structure is 'DITA standard' or
              > 'Gunnar's reduced'.
              >
              > Any comment is appreciated!
              >
              > Gunnar H. Krause, Senior Manager, Qimonda TechDoc
              >





              --
              Chris Turchin <chris@...>
            • Eliot Kimber
              ... The key is that a subsetting DTD is explicitly an authoring convenience, not either a conforming configuration or specialization. The DTD works fine but it
              Message 6 of 10 , Apr 3, 2009
              • 0 Attachment
                On 4/3/09 10:16 AM, "Chris Turchin" <turchinc@...> wrote:

                > Hi Gunnar,
                >
                > Since a subset is (DTD) valid according the to the rules of the superset, I
                > do question if it is really worth the effort to rename each and every
                > changed element. Even the spec does not seem to imply it is necessary:
                >
                > "The (subset) document type ... can *override entities *in the module files
                > ... by providing a new definition of the entity before importing the module
                > files."
                >
                > Nothing there indicating I must rename the elements including these new
                > entities.

                The key is that a subsetting DTD is explicitly an authoring convenience, not
                either a conforming configuration or specialization. The DTD works fine but
                it is not, itself, a conforming DITA DTD *because the DITA spec defines how
                you must construct and configure DTDs*.

                That is, DITA conformance is not just about content models but also about
                DTD and schema implementation design patterns.

                DITA 1.2 provides more configuration flexibility and provides the new
                constraint specification that are both intended to make this type of
                constraining without requiring specialization both easier and more likely to
                conform.

                For example, one could imagine a tool that takes a constraint spec and
                generates new authoring DTDs that enforce those constraints. You could also
                imagine generating Schematrons that validate the same constraints. Neither
                tool should be hard to implement.

                Cheers,

                Eliot

                ----
                Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
                email: ekimber@... <mailto:ekimber@...>
                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>
              • ghkrause
                Hello Alexej and others, Where is the problem with generalization of my example? Any without children named is valid, whether I prohibited while
                Message 7 of 10 , Apr 3, 2009
                • 0 Attachment
                  Hello Alexej and others,
                  Where is the problem with generalization of my example?
                  Any <p> without children named <ol> is valid, whether
                  I prohibited while editing or just personally limited
                  which childs I use.
                  Generalization is the inverse of specialization and my
                  question is then of course, whether such a change is
                  called specialization at last. Your 2nd link calls it
                  "subsetting".

                  At least one DITA editor with a special map editor has
                  a currently a limit of map-only editing, even bookmap
                  which is part of DITA standard cannot be opened in
                  map editor.

                  If I disable a domain like mapgroups in map.dtd - how do
                  you call this?
                  - subsetting
                  - customizing
                  - specializing

                  Thanks for your time and thoughts!
                  -ghk

                  --- In dita-users@yahoogroups.com, "leha_spas" <leha@...> wrote:
                  >
                  > Hallo Gunnar,
                  >
                  > I was always convinced that (c) is actually a MUST in DITA
                  > specialization given you plan to change element content model. Otherwise
                  > how can content later on go through possible generalization? Also point
                  > mentioned by Deborah with ditabase would be another consequence of such
                  > violation.
                  >
                  > ...
                  > http://www.ibm.com/developerworks/xml/library/x-dita2/
                  > ...
                  > http://docs.oasis-open.org/dita/v1.1/CD01/archspec/speclimits.html
                • Eliot Kimber
                  ... Configuration. Modifying shell DTDs to include or remove modules is configuration . Specialization is the act of defining new element types (with new
                  Message 8 of 10 , Apr 3, 2009
                  • 0 Attachment
                    On 4/3/09 10:32 AM, "ghkrause" <gunnar.krause@...> wrote:


                    >
                    > If I disable a domain like mapgroups in map.dtd - how do
                    > you call this?
                    > - subsetting
                    > - customizing
                    > - specializing

                    Configuration.

                    Modifying shell DTDs to include or remove modules is "configuration".

                    Specialization is the act of defining new element types (with new names)
                    based on existing types.

                    Configuration and specialization are formally defined in the DITA spec.

                    "subsetting" is modifing the existing content models to impose constraints
                    that cannot be imposed by DITA-provided configuration methods. This is not a
                    formally-defined action because the result is, by definition, not conforming
                    to the DITA specification. But it describes it as being something that can
                    be useful to do in order to impose local constraints.

                    Cheers,

                    Eliot

                    ----
                    Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
                    email: ekimber@... <mailto:ekimber@...>
                    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>
                  • bobthomastagsmiths
                    Hi Gunnar, I created an authoring plug-in that implements the list restriction along with some other
                    Message 9 of 10 , Apr 6, 2009
                    • 0 Attachment
                      Hi Gunnar,

                      I created an authoring plug-in  that implements the list restriction along with some other restrictions. As you might expect, the DTDs use different public identifiers for the shell DTDs. You, or anyone else, is free to use this plug-in or to modify it.

                      This plug-in uses entity overides to restrict the elements that authors see during writing. The DTDs are subsets; it is impossible to create a parsing XML instance with this plugin that will not also parse against their base-DITA DTD counter-part. These DTDs are non-compliant with the DITA standard because the standard does not support entity overrides for content models in DITA 1.1. The biggest draw-back with that is that, when the DTD version changes, I have to ensure that the entity overrides still correctly subset their corresponding content-model entities in  the new version. If you inter-operating with an organization that has not restricted the content models, there is some chance of confusion. However, there are no other negative consequences.

                      Using this plug-in is not risky. I have a client that has been using a similar version of this plug-in with the DITA Open Toolkit for the past three years, and there has never been a problem.

                      You may face some challenges setting up your editing environment to use the plug-in. But, these are the same problems that you would face with any specialization. Like any other specialization, this plug-in cannot be deployed in Framemaker. The only way to achieve the plug-in's content model restrictions in Framemaker would be through making extensive modification to the DITA EDD.

                      The fact that the DITA standard did not provide a mechanism for subsetting content models has been a shortcoming of the standard. However, that shortcoming will be largely removed once the constraints mechanism is introduced in DITA 1.2. Once DITA 1.2 is released, I plan to re-factor the authoring plug-in using the constraints mechanism; this will make the plug-in DITA compliant.

                      Bob Thomas
                      Tagsmiths, LLC
                      +1 720 201 8260



                      --- In dita-users@yahoogroups.com, "ghkrause" <gunnar.krause@...> wrote:
                      >
                      > Dear specialization specialists at dita-users!
                      >
                      > Today I have a maybe philosophical question related to DITA 1.1.
                      > Without confirmation from others in the community or additional
                      > thoughts I am not keen enough to proceed my specialization task ...
                      >
                      > A structural specialization where my only intend is to reduce
                      > the options that the default dita dtd offers comprises:
                      > - less child elements (like no <ol> in <p>)
                      > - fixed sequence of child elements instead of a flexible
                      > choice of children
                      >
                      > Do I need to do any of the following steps for this restricted
                      > specialization scenario?
                      > a) Change Public ID in DOCTYPE statement?
                      > b) Change root node name?
                      > c) Change element name of any modified element?
                      >
                      > I assume that (a) is a good idea, (b) is optional and (c)
                      > is not necessary - do you agree?
                      >
                      > Use case:
                      > Currently I think of maintaining two sets of DTD: a restricted
                      > one for authoring and the DITA standard DTDs in Open Toolkit.
                      > Editing would follow the more rigid DTD but any valid DITA topic
                      > from other sources would validate when rendered as part of a map.
                      > In this case I consider neither a, b nor c to be helpful.
                      > ==> This is a special specialization that may not be regarded
                      > as specialization or at least is difficult to detect.
                      >
                      > Problem:
                      > Authors that know DITA or that use standard DITA manuals and
                      > cheat sheets are confused due to the fact that they cannot guess
                      > from the name of tag whether its structure is 'DITA standard' or
                      > 'Gunnar's reduced'.
                      >
                      > Any comment is appreciated!
                      >
                      > Gunnar H. Krause, Senior Manager, Qimonda TechDoc
                      >
                    • leha_spas
                      Hallo Gunnar, Regarding generalization: You are right. There is no problem with generalization process from content model point of view. I m just wondering
                      Message 10 of 10 , Apr 6, 2009
                      • 0 Attachment
                        Hallo Gunnar,

                        Regarding generalization: You are right. There is no problem with generalization process from content model point of view.  I'm just wondering what should be placed in "class" attribute for generalized "restricted" elements?

                        Second part of class identifier will not change, so the only way to differentiate such element from its parent will be a first part of class attribute.  But since the root element did not change as well, than the first part of class identifier need to be defined in some kind of DITA infotype vocabulary and be unique.

                        Example:

                        If you have a taskbody element with class="- topic/body task/taskbody" what will it be for  "restricted" taskbody? Element name is the same, so is the root element name.

                        Reasonable answer I see here is: class="- topic/body task/taskbody mytask/taskbody" where "mytask" is some kind of short unique identifier of your infotype.

                        Generally speaking as Eliot mentioned it looks like restricting/subsetting in DITA is just out of spec in 1.1, but this does not mean that I can't be used in practice. More than that since many people use it I think we will include this functionality in set of modeling features of our tool (I think it will fall into list of "non-DITA compliant" operations with model). I will notify you as soon as this feature will be ready so you can to update your installation and try it.

                        ----
                        Alexey Spas | Senior IT Manager

                        Phone +49 (0)711-993385 94
                        Fax +49 (0)711-993385 99
                        www.ditaworks.com  
                        blog.ditaworks.com 

                        --- In dita-users@yahoogroups.com, "ghkrause" <gunnar.krause@...> wrote:
                        >
                        > Hello Alexej and others,
                        > Where is the problem with generalization of my example?
                        > Any <p> without children named <ol> is valid, whether
                        > I prohibited while editing or just personally limited
                        > which childs I use.
                        > Generalization is the inverse of specialization and my
                        > question is then of course, whether such a change is
                        > called specialization at last. Your 2nd link calls it
                        > "subsetting".
                        >
                        > At least one DITA editor with a special map editor has
                        > a currently a limit of map-only editing, even bookmap
                        > which is part of DITA standard cannot be opened in
                        > map editor.
                        >
                        > If I disable a domain like mapgroups in map.dtd - how do
                        > you call this?
                        > - subsetting
                        > - customizing
                        > - specializing
                        >
                        > Thanks for your time and thoughts!
                        > -ghk
                        >
                        > --- In dita-users@yahoogroups.com, "leha_spas" leha@ wrote:
                        > >
                        > > Hallo Gunnar,
                        > >
                        > > I was always convinced that (c) is actually a MUST in DITA
                        > > specialization given you plan to change element content model. Otherwise
                        > > how can content later on go through possible generalization? Also point
                        > > mentioned by Deborah with ditabase would be another consequence of such
                        > > violation.
                        > >
                        > > ...
                        > > http://www.ibm.com/developerworks/xml/library/x-dita2/
                        > > ...
                        > > http://docs.oasis-open.org/dita/v1.1/CD01/archspec/speclimits.html
                        >
                      Your message has been successfully submitted and would be delivered to recipients shortly.