Topics

How to constraint elements of Standard Highlighting domain module #constraints


 

Hello Team,
Good Morning!

I am currently working on example:2.5.5.6.3 constrain a domain module. referring to  http://docs.oasis-open.org/

use case :The requirement is to apply constraints on dita elements of highlighting domain module and remove them from the DTD files reason being business doesn't want to give access to all the dita elements provided by web-editor,basically limiting element choices for authors.

example
: An information architect wants to use only a subset of the elements defined in the highlighting domain. She wants to use  <sup>, <sup>but not <b> ,<i>,<line-through>, <overline>, <tt> .She wants to integrate this constraint into the DTD's / document-type shell for tasks


  1. I am not trying to create new DTD schema instead I would like to make use of standard or default highlighting domain module provided by OASIS (//OASIS//ENTITIES DITA 1.3 Highlight Domain//EN"  "../../base/dtd/highlightDomain.ent) to constraint  <b> ,<i>,<line-through>, <overline>, <tt> and allow <sub>,<sup> elements.
  2. The example in document is intended for the users who has custom DTD schema i.e ACME(//ACME//ENTITIES DITA Highlighting Domain Constraint//EN" "acme-HighlightingDomainConstraint.mod")and they would like to restrict the elements from the custom highlighting domain.My requirement is different from the example in the document.
  3. I feel the information provided in the document is insufficient and targets the audience who works on custom DTD schema's and it is difficult for the DITA newbie's like me to understand that high level example.Please,guide me on how to achieve above mentioned use case.Please,throw some light on the different ways to achieve this use case.
Thanks,
Meghana Pathroju.


Kristen James Eberlein
 

Hi, Meghana.

I understand your use case well. The problem here is that constraints ONLY can be applied if you are using company-specific document-type shells (DTDs). You CANNOT apply constraints to the out-of-the-box OASIS DTDs.

Depending on the editor that you authors are using, you might be able to hide elements from the authors. This is certainly true of the desktop version of Oxygen XML Editor. It does require creating a custom framework for Oxygen installations.

I am sorry that you found the example in the spec to be difficult. As one of the spec editors, I can reinforce your sense that the target audience is DITA practioners who develop company-specific DTDs, constraints, and specialization -- as well as engineers who design and build DITA processors. The target audience for the spec is not people new to DITA.

While there are now quite a few good books that are resources for people new to DITA, I do not think that any of them delve into the more technical aspects of implementing DITA.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 8/31/2020 4:21 AM, Meghana wrote:
Hello Team,
Good Morning!

I am currently working on example:2.5.5.6.3 constrain a domain module. referring to  http://docs.oasis-open.org/

use case :The requirement is to apply constraints on dita elements of highlighting domain module and remove them from the DTD files reason being business doesn't want to give access to all the dita elements provided by web-editor,basically limiting element choices for authors.

example
: An information architect wants to use only a subset of the elements defined in the highlighting domain. She wants to use  <sup>, <sup>but not <b> ,<i>,<line-through>, <overline>, <tt> .She wants to integrate this constraint into the DTD's / document-type shell for tasks


  1. I am not trying to create new DTD schema instead I would like to make use of standard or default highlighting domain module provided by OASIS (//OASIS//ENTITIES DITA 1.3 Highlight Domain//EN"  "../../base/dtd/highlightDomain.ent) to constraint  <b> ,<i>,<line-through>, <overline>, <tt> and allow <sub>,<sup> elements.
  2. The example in document is intended for the users who has custom DTD schema i.e ACME(//ACME//ENTITIES DITA Highlighting Domain Constraint//EN" "acme-HighlightingDomainConstraint.mod")and they would like to restrict the elements from the custom highlighting domain.My requirement is different from the example in the document.
  3. I feel the information provided in the document is insufficient and targets the audience who works on custom DTD schema's and it is difficult for the DITA newbie's like me to understand that high level example.Please,guide me on how to achieve above mentioned use case.Please,throw some light on the different ways to achieve this use case.
Thanks,
Meghana Pathroju.


ekimber@contrext.com
 

If you simply want to disallow the use of specific elements from a domain you can do this in the DTD shell--no need for a separate constraint module.

But note that this does require that you have custom DTD shells (see https://www.xiruss.org/tutorials/dita-specialization/, in particular, Chapter 3, Document Type Shell tutorial).

In the shell DTD you "integrate" domain using domain-integration parameter entities, i.e., (here take from the basetopic.dtd but it will be similar in any of the OASIS-provided DTD shells):

<!-- ============================================================= -->
<!-- DOMAIN EXTENSIONS -->
<!-- ============================================================= -->

...

<!ENTITY % ph "ph |
%hi-d-ph;
">


Here "%hi-d-ph;" is a reference to a parameter entity that includes all the element types from the Highlight domain (base/dtd/highlightDomain.ent):

<!ENTITY % hi-d-ph
"b |
i |
line-through |
overline |
sup |
sub |
tt |
u"
That has the effect of allowing all the elements to occur wherever <ph> is allowed.

This entity, %hi-d-ph, is the "domain integration parameter entity".

Instead of referring to %hi-d-ph in the domain integration parameter entity you can simply refer to the element types you want to allow;

<!-- ============================================================= -->
<!-- DOMAIN EXTENSIONS -->
<!-- ============================================================= -->

...

<!ENTITY % ph "ph |
sup |
sub
">

This is a constraint and, per DITA 1.x rules, should be declared in the @domains attribute just as you would declare a constraint module, but we're removing the @domains attribute in DITA 2.0 and as far as I know no tool will complain that you didn't declare this constraint.

Note that you need to define this constraint in the shell DTD for each topic type you're using.

Cheers,

E.
--
Eliot Kimber
http://contrext.com


On 8/31/20, 3:21 AM, "Meghana" <main@dita-users.groups.io on behalf of @Meghana> wrote:

Hello Team,
Good Morning!

I am currently working on example:2.5.5.6.3 constrain a domain module. referring to http://docs.oasis-open.org/

use case :The requirement is to apply constraints on dita elements of highlighting domain module and remove them from the DTD files reason being business doesn't want to give access to all the dita elements provided by web-editor,basically limiting element choices for authors.
example: An information architect wants to use only a subset of the elements defined in the highlighting domain. She wants to use <sup>, <sup>but not <b> ,<i>,<line-through>, <overline>, <tt> .She wants to integrate this constraint into the DTD's / document-type shell for tasks


Reference I followed to achieve this: http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/example-contraints-subset-domain.html


1. I am not trying to create new DTD schema instead I would like to make use of standard or default highlighting domain module provided by OASIS (//OASIS//ENTITIES DITA 1.3 Highlight Domain//EN" "../../base/dtd/highlightDomain.ent) to constraint <b> ,<i>,<line-through>, <overline>, <tt> and allow <sub>,<sup> elements.
2. The example in document is intended for the users who has custom DTD schema i.e ACME(//ACME//ENTITIES DITA Highlighting Domain Constraint//EN" "acme-HighlightingDomainConstraint.mod")and they would like to restrict the elements from the custom highlighting domain.My requirement is different from the example in the document.
3. I feel the information provided in the document is insufficient and targets the audience who works on custom DTD schema's and it is difficult for the DITA newbie's like me to understand that high level example.Please,guide me on how to achieve above mentioned use case.Please,throw some light on the different ways to achieve this use case.

Thanks,
Meghana Pathroju.