Pages: 1
Print
Author Topic: Reuse inside (book)map titles  (Read 5962 times)
leo71
Member

Posts: 25


« on: September 03, 2009, 05:32:13 AM »

Hi,

Assume you have a list of product names stored centrally as ph elements.
Assume you use those product names in all your product user guides.

The first place where you want to reuse that product name is?

Yes, in your map title, or you bookmap booktitle or booktitlealt.

However, if you try for example to insert a ph/@conref, XMetal 5.5 says the following:
Error: The referenced element may contain content from domains that are not allowed in the referencing element.

This error message is the same in both a map and bookmap.

I don't know if this is different for newer DITA-OT versions, or how XMetal protects us from doing illegal things. However, inserting a ph is allowed according the DTD. So why not a ph with @conref.

Thanks in advance.

Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #1 on: September 03, 2009, 12:37:22 PM »

XMetaL Author Enterprise 5.1 and 5.5 use the following rules when checking referenced content.

Quote from: XMetaL Author Enterprise Help
Validating referenced content
When you validate a document, referenced content is not checked for validity. Referenced content is checked for validity when you refresh references. If there is invalid local content and you jump to the validation error, the local content is displayed.

When a content reference is created, or the refresh process is run on a content reference, the reference is checked to ensure that it is valid in the current context.

Content references must conform to the following requirements:

  • The target file specified must exist
  • The target ID in the target file must exist
  • The target document must be valid XML
  • The target must be a different node than the source node, i.e., it must not be a circular reference
  • The target element and the source element must be of the same type or the target element must be generalizable back to the source type
  • The target domain set must be equal to or a subset of the source domain set
  • The target element must be a descendent of a topic or a map

The assumption being made here by me is that you wish to reference content from a topic inside a map and these two file types have different domain attributes. This includes our "reusable component" specialization as well which is a specialization of the standard DITA Topic DTD.

I can see your point in wanting to reuse this type of content in maps, and some versions (perhaps all) of the DITA OT do not seem to check the target domain rule (second to last in the list above) and will happily produce output using such conref'd content without raising any errors or warnings despite what the DITA Architectural Specification states and our understanding of it (that this is not allowed, which one might argue is overly-protective)...

Quote from: DITA Version 1.1 Architectural Specification OASIS Standard, 1 August 2007
If the referenced element is the same type as the referencing element and the list of domains in the
referenced topic instance (declared on the domains attribute) is the same as or a subset of the list of domains in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the placeholder element. In the preferred approach, a processor resolving a conref should tolerate specializations of valid elements and generalize elements in the content fragment as needed for the referencing context.

Workaround:
If you wish to take advantage of the current state of the DITA OT, one workaround you may try that will allow you to violate this rule using XMetaL Author Enterprise 5.1 and 5.5 is to first insert your conref'd <ph> into a standard DITA topic file saved to the same folder as the map (so the paths will be the same), then copy and paste that element into your map file with the map open in TagsOn view (aka: "XML View of Map"). XMetaL does not perform the referenced content checks during a paste. However, you will be notified of this issue at a later time for other events that trigger this check (by default opening a document runs this check as well as selecting the 'Refresh All References' option on the Edit menu or pressing F11).

I cannot predict which consequences this workaround will have now or in the future. You may also wish to raise this with the DITA Technical Committee at OASIS.

It seems to me that in theory it might be possible for us to create a reusable component specialization that includes both the map and topic domains. I will raise that possibility with our development team.
« Last Edit: September 03, 2009, 12:41:50 PM by Derek Read » Logged
leo71
Member

Posts: 25


« Reply #2 on: September 04, 2009, 02:50:21 AM »

Thanks for the workaround.

I understand the considerations and to protect ourselves to do illegal reuse between domains.
However for those generic items like ph; i don't see the benefit.

Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2621



WWW
« Reply #3 on: December 17, 2009, 04:54:14 PM »

If you feel the domain checking behavior in XMetaL Author Enterprise 5.5 and 6.0 is not desirable you may use the attached MCR file to disable it.

To use this, unzip the attached file into your <xmetal install path>\Author\Startup folder. Restarting XMetaL Author Enterprise 5.5 or 6.0 will load this MCR file which should disable the protective domain checking functionality.

I believe most people will wish to retain the current behavior and unless you really know what the consequences are you should leave the current behavior as it is. We cannot predict what issues this might raise for 3rd party software, particular versions of the DITA OT (perhaps running "stand alone" or integrated with other software you might be using), other transformation processes, CMS systems you may have integrated with XMetaL Author Enterprise, or any other 3rd party software you may use. Any of these might also use similar domain checking behavior that this MCR allows you to disable in our software.

Be sure to fully test this before using it in a production environment.

You should also be fully aware of any expectations other DITA-aware software you are using may have and as such it would make sense to run any content through a complete workflow from file creation through all of your processes.

* xmee_60_20091217.zip (1.08 KB - downloaded 377 times.)
Logged
Pages: 1
Print
Jump to:  

email us