Ditamap Editor – "Update All References"

[pshepton]

Hi There,

Using XMetaL Author DITA Edition 5.0 SP1, I have a ditamap containing topicref elements which point to specialized topics, e.g. OptionRef – descended from the reference topic type. The “type” attribute for such “topicref” elements is set to:
type=”OptionRef”

After editing the ditamap in the XMetaL Ditamap Editor, if I run “Update All References”, all the “type” attribute values are changed to “reference”. Then when I run the ditamap through the DITA-OT, I get errors/warnings that the “topicref” “type” attribute value is incorrect.

Is there a way to prevent this from happening?

Thanks,

Peter

Reply

[Derek Read]

This issue was corrected for XMetaL Author Enterprise version 5.1.1.017.

Testing with our current release (5.5 SP1) and the IBM FAQ specialization sample included with the DITA OT shows the following behavior for topicref elements in maps after selecting the “Update All References” option:

1. When the type attribute is set to any value it is not modified (I believe this is the behavior you are complaining about in your release).

2. When the type attribute is not set, and the href points to a “topic” or one of the 3 other standard specialized types (reference, task or concept) the referenced file (the target) is parsed to determine the type and the value is set to match.

3. When the type attribute is not set, and the href points to a specialized topic type that is not one of the 4 listed above it is set to the generic value “topic”. This is correct if am reading the DITA specification correctly. If you wish to set this to a more specific value, and you choose to change it from “topic” to another value such as “faq”, #1 above should apply.

I also see during this testing that the version of the DITA OT that ships with our 5.5 release does not seem to check (or care) about the type attribute. With this version (DITA OT 1.4.2.1) setting the type attribute to anything, including something clearly bogus such as “pizza” does not cause the OT to throw errors, so if that is something you were relying on (perhaps you have customized one of the output transtypes specifically to look for certain type values?) you should be aware of that.

Reply

[severin.foreman]

Hi Derek, Susan, et al.

Sorry to join the conversation so late, but I would like to request a feature related to this issue. For behavior number three, instead of setting the type attribute to “topic” for all specializations outside of the “DITA Big Three,” why not have XMetaL Author parse the source file and set the topic type the same way that it would for the base specializations?

Except for all but the geekiest writers, it is too much to ask people to set special attributes when adding topics to maps (besides perhaps navtitle and collection-type). Add the fact that writers would need to manually enter the topic type and you're practically begging for DOTX018I messages in your build logs.

I hope that it would not be to difficult to implement the feature so long as the specialized DTD has been registered in XMetaL author. Alternately, would it be possible to override the default behavior with a macro?

Best,
Severin

Reply

[Su-Laine Yeo]

Thanks Severin. Your suggestion sounds like something we should consider.

First, to try to clarify the question of whether the OT throws errors when the @type attribute on a map doesn't match the topic type: The OT gives a “warning” message in the log file, but it generates output that looks fine and works, and I believe most users wouldn't even notice the warning message because XMetaL doesn't notify you unless there are actual problems. If you do bring up the log file, you see a warning message like this:

[code][xslt] file:/C:/DOCUME%7e1/syeo/APPLIC%7e1/SoftQuad/XMETAL%7e1/DITA_OT/xsl/common/output-message.xsl:68:20: Warning! [DOTX019W][WARN]: The type attribute on a topicref element does not match the target topic. The type attribute was set to 'pizza', but the topicref points to a more specific 'concept' topic. This may cause your links to sort incorrectly in the output. Note that the type attribute is inherited in maps, so the value 'pizza' may come from an ancestor topicref. Check and make the type of topicref match with the actual type of topic.The location of this problem  was at (File = c:documents and settingssyeomy documentsxmetalsamplesditaSample_Map.ditamap, Element = topicref:1)[/code]

As most people wouldn't even notice the warning, I don't think the fact that the warnings are generated is a good reason by itself to change how XMetaL populates the @type attribute on topicrefs.

There are a couple of reasons I can think of to not automatically populate the @type attribute with values corresponding to specialized topic types:
– Sometimes people create specialized topic types just because they want to add a new structural rule or use fewer element types. In these cases it is is appropriate to process a specialized topic exactly the same way that you would process an unspecialized topic. Using a different @type value would provide no benefit in these cases and would be one more thing that could go wrong in processing.
– It is conceivable that some processing tools could be hardcoded to allow only certain values for @type.

It would be good for us to get a sense of how many people *would* want to do specialized processing based on specialized @type attribute values in topicrefs, so we can balance that need against the above risks. Please reply here if this is something that you need.

Reply

[severin.foreman]

Hi Su-Laine,

Thank you for your response.

>> First, to try to clarify the question of whether the OT throws errors when the @type attribute on a map doesn't match the topic type: The OT gives a “warning” message in the log file

Agreed. And in my own defense, I never referred to the messages as “errors.” 🙂 So the OT gives [WARN] and [INFO] messages when the type attribute on the map does not match the actual topic type. I will also add that many of these are duplicates. I seem to get both WARN and INFO for each occurence. And, aside from the extra messages in the log, the affect on the output could be nil or very minimal (“related” links might not sort correctly at the bottom of the topic output). However, the log for our online help system contains 65,749 of these messages! On a 74Mb log, that is approximately 45Mb of messages.

You are also right that most users do not notice these messages, but I do, and I prefer a clean build whenever I can get it. I tested a build today outside of the XMetaL-hosted OT and found that if I removed all type attributes from the map, the messages were gone. I have an interest in keeping the log files as small and accurate as possible because, in the absense of an industrial strength CMS system, we depend on our build logs to know when there are conref errors or other problems with our content that need fixing.

I also noticed that the WARN and INFO messages occur for the glossentry specialization.

>> There are a couple of reasons I can think of to not automatically populate the @type attribute with values corresponding to specialized topic types:
>> – Sometimes people create specialized topic types just because they want to add a new structural rule or use fewer element types. In these cases it is is appropriate to process a specialized topic exactly the same way that you would process an unspecialized topic. Using a different @type value would provide no benefit in these cases and would be one more thing that could go wrong in processing.

So long as the type attribute is set correctly, the specialized DTD has been added to XMetaL and the OT catalog files are up to date, I do not see what could go wrong with setting the type attribute to the correct topic type. It would have the benefit of producing cleaner log files.

>>  It is conceivable that some processing tools could be hardcoded to allow only certain values for @type.

I would suggest that such a processing tool would not fully support DITA specialization, and as such, would be significantly flawed.

I would also like to add that I am sorry for referring to you as Susan in my previous post. Please accept my apologies for the mistake.

Best regards,
Severin

Reply

[Su-Laine Yeo]

Hi Severin,

No worries about the name mixup, and it's my turn to apologize for taking so long to respond. I did some investigation and have good news: Version 1.5 of the DITA Open Toolkit will, if I understand things correctly, no longer give warning messages when the “type” attribute does not exactly match the topic type. So people who use specialized topic types should see a lot fewer warning messages in their output logs.

Details are here: http://sourceforge.net/tracker/index.php?func=detail&aid=1771123&group_id=132728&atid=725074

The next major release of XMetaL will probably include version 1.5 of the DITA Open Toolkit, or a later version if there is one. Version 1.5 of the DITA Open Toolkit is part of the DITA 1.2 Configuration Kit for XMetaL which is available upon request to customers on maintenance, however we do not offer support services for this version of the toolkit at this time.

Regards,
Su-Laine

Reply

[severin.foreman]

Hi Su-Laine,

Thanks for the info. We are using one of the pre-release milestones of 1.5, currently, so the warning fix must be in a later version than what we have. I cracked open the release notes to see if I was on M21 or M23, but the notes were for 1.4.2.1, so no luck there!

I am assuming that the DITA 1.2 Configuration kit is only for XMetaL Author 6.0, correct? We are currently on 5.5. Do you have any documentation for the configuraiton kit? I am investigating DITA 1.2 features, and am interested to see how your product will support some of the new features, espeically keyrefs.

Best,
Sev

Reply

[Su-Laine Yeo]

Hi Severin,

Yes, the DITA 1.2 Configuration Kit requires XMetaL Author Enterprise 6.0 to be installed. I'll send you the documentation.

Cheers,
Su-Laine

Reply

[Author]

Posts