Cannot add custom profiling attribute

[icemaple14]

I want to add a custom profiling attribute called "deployment", and it has values like standy、ha、cluster.
It‘s not defined by DITA，so I must modify the DTD file.
I added some definitions in task.dtd (I don’t know where to add it better), and imitate like the deliveryTargetAtt:

Code: Select all

<!-- ============================================================= -->
<!--             DOMAIN ATTRIBUTES DECLARATIONS                    -->
<!-- ============================================================= -->

<!ENTITY % deliveryTargetAtt-d-dec
  PUBLIC "-//OASIS//ENTITIES DITA 1.3 Delivery Target Attribute Domain//EN"
         "../../base/dtd/deliveryTargetAttDomain.ent"
>%deliveryTargetAtt-d-dec;

<!ENTITY % deploymentAtt-d-dec
PUBLIC "-//OASIS//ENTITIES DITA 1.3 Deployment Attribute Domain//EN"
        "../../base/dtd/deploymentAttDomain.ent"
>%deploymentAtt-d-dec;

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

<!ENTITY % props-attribute-extensions
  "%deliveryTargetAtt-d-attribute;"
>
<!ENTITY % base-attribute-extensions
  ""
>
<!ENTITY % props-attribute-extensions
  "%deploymentAtt-d-attribute;"
>

<!-- ============================================================= -->
<!--                    DOMAINS ATTRIBUTE OVERRIDE                 -->
<!-- ============================================================= -->

<!ENTITY included-domains
                          "&task-att;
                           &abbrev-d-att;
                           &deliveryTargetAtt-d-att;
                           &equation-d-att;
                           &hazard-d-att;
                           &hi-d-att;
                           &indexing-d-att;
                           &markup-d-att;
                           &mathml-d-att;
                           &pr-d-att;
                           &relmgmt-d-att;
                           &sw-d-att;
                           &svg-d-att;
                           &ui-d-att;
                           &ut-d-att;
                           &xml-d-att;
                           &taskbody-constraints;
                           &deploymentAtt-d-att;
  "
>

And then I added a deploymentAttDomain.ent, which contains the code below:

Code: Select all

<!ENTITY % deploymentAtt-d-attribute
  "deployment
                          CDATA
                                    #IMPLIED"
>

<!-- ============================================================= -->
<!--                    DOMAIN ENTITY DECLARATION                  -->
<!-- ============================================================= -->

<!ENTITY deploymentAtt-d-att
  "a(props deployment)"
>

However, when I try to add this attribute in Oxygen Editor, for example, "select <uicontrol deployment="ha">Settings</uicontrol>", it warned like this :Attribute "deployment" is not allowed to appear in element "uicontrol".
It seems that the new attribute does not work. So is there anything wrong when modifying the DTD?

[Radu]

Hi,

The base DITA DTDs provided with the DITA Open Toolkit which comes bundled in Oxygen were created by the DITA OASIS standard, they must remain as they are.
You can find here a link to a tutorial which describes in detail how a DITA DTD specialization should be constructed as a separate DITA Open Toolkit plugin:
https://www.oxygenxml.com/doc/versions/ ... ation.html
But this means that once you build that plugin and install it, all your DITA topics, tasks will need to have special DOCTYPE declaration referencing the custom DTDs.
And you need to create specialization DTDs for all the DITA types you are interested in (maps, tasks, topics).
If you create such a DITA OT plugin following the tutorial and it still does not work you can attach it to an email and we can try to find some time to take a look at it (support@oxygenxml.com).
An alternative would be to use one of the current DITA profiling attributes with the profiling attribute groups feature:
https://www.oxygenxml.com/doc/versions/ ... roups.html

Regards,
Radu

[icemaple14]

Hi, Radu. Thanks for reply.
I've read the tutorial you provided, but I still don't understand. We use many plugins to generate PDF, DOCX, CHM, and HTML files. Does that mean I should modify all of those plugins to add my profiling attribute? That would be too complex.

I also tried using profiling attribute groups, but it seems that they only divide an attribute into different groups. It demands that the object must belong to only a single parent attribute. For example, I need to distinguish between the following attributes: hardware vs virtualization; Windows vs macOS for the client; Windows vs Linux for the server; standard vs HA vs Cluster. Those cannot be distinguished using only a "platform" attribute. And attribute groups can't solve it because I need to use all 4 groups of attributes at the same time.

I also tried using the subject schema map, but found out that only attribute like "product" works. I bound some values to the 'rev' attribute, and set the ditaval to exclude it, but it didn't work.

I'm so disappointed with the DITA standard in recent years. Why does it provide so few choices and make specialization so difficult?

[Radu]

Hi,
Please see some remarks below:

I've read the tutorial you provided, but I still don't understand. We use many plugins to generate PDF, DOCX, CHM, and HTML files. Does that mean I should modify all of those plugins to add my profiling attribute? That would be too complex.

You need only one DITA OT plugin. Some time ago I followed the tutorial I recommended and created a sample plugin based on it which adds a profiling attribute named "phase-of-moon", I just created a public GitHub repository with my plugin, maybe you can download a zip with the repository and use it to get started:
https://github.com/oxygenxml-incubator/ ... in-sample/
The sample repository also has samples, a sample map, a sample topic and a subject scheme map which defines fixed values for the "phase-of-moon" attribute.
You can see that both the sample DITA map and topic point to the DTDs in the plugin using custom DOCTYPE public ID's which get mapped by the plugin using a catalog.xml to the custom map.dtd and topic.dtd.

I also tried using profiling attribute groups, but it seems that they only divide an attribute into different groups. It demands that the object must belong to only a single parent attribute. For example, I need to distinguish between the following attributes: hardware vs virtualization; Windows vs macOS for the client; Windows vs Linux for the server; standard vs HA vs Cluster. Those cannot be distinguished using only a "platform" attribute. And attribute groups can't solve it because I need to use all 4 groups of attributes at the same time.

I think you can use profiling attribute groups for what you want. Using the "platform" attribute you can have multiple groups inside it like "hardware" and "virtualization" each with its own defined values.

I also tried using the subject schema map, but found out that only attribute like "product" works. I bound some values to the 'rev' attribute, and set the ditaval to exclude it, but it didn't work.

The "rev" attribute is not considered a profiling attribute by the DITA standard. The list of predefined profiling attributes (@audience, @deliveryTarget, @otherprops, @platform, and @props) can be found in the specification:
https://www.oxygenxml.com/dita/1.3/spec ... dproc.html
Using @rev you can only flag content (use the DITAVAL to highlight certain elements having the @rev attribute).

I'm so disappointed with the DITA standard in recent years. Why does it provide so few choices and make specialization so difficult?

The DITA standard has always worked this way. In general with XML you validate it using a schema or DTD. So if you add a new attribute/element you need to make changes to the used schema.
But the base DITA DTDs are provided by the Oasis DITA standard and they way that you should not modify them directly. So this is why a DITA OT plugin which contributes mappings for custom DOCTYPE public IDs and custom DTDs is usually used.
We have users who like you have edited directly the base DITA DTDs, but it's not a best practice and you also need to share your modifications with others if you are working in a team.
One more useful thing, in Oxygen if you open a DITA topic for example in the main editor there is a toolbar button named "Open associated schema" which opens for you the DTD which is used by Oxygen for validation/editing/publishing.

Regards,
Radu

[icemaple14]

Hi, Radu. Glad to recieve your reply again. You‘re so kind and patient.
It's great to hear that one DITA OT plugin is needed. But it's actually still a little complex. Now I intend to use profiling attribute groups to solve the problem, and try not to introduce too many attributes to the project as most of them turned out useless after serveral years.
I'll try your more advices later during working, thanks!