Workaround: Automate replacement of ampersands in attributes with &

[Derek Read]

Products:
XMetaL Author Enterprise and Essential 5.5 and 6.0
May also affect older versions.

Issue Description:
An issue handling documents that encode ampersands using the numeric entity reference & has been identified. This issue is being tracked as PROD00032599 and may be addressed in a future release.

The issue described here and the workaround for it is specific to numbered character entity references for the ampersand character & only.

When an XML document is opened into TagsOn or Normal view and the document contains an escaped ampersand in the form & inside an attribute value XMetaL Author does not retain the numeric entity (this is expected behavior and is working as designed). As with other numeric entities it is expanded, in this case to an ampersand (&), and the product does no further processing.

However, when an unescaped ampersand appears in a document it is considered invalid (as per W3C XML validation rules) and validation errors are (correctly) raised. This forces the author to correct these issues by manually escaping each ampersand as &

When XMetaL sees & it leaves it as it is (and does not convert it to & as with the numeric entity). When inserting the 5 characters that need to be escaped in XML, XMetaL inserts them as the named entities (when necessary) & ' " < >

It is assumed that clients expect the numeric entity  to remain (which is probably not something we could easily support) -OR- have the numeric entity & automatically replaced with the named entity & (which is what this script does).

Purpose of the Script:
Find ampersand characters that should be escaped and escape them, while leaving existing entities as they are.

An alternative to using this particular script workaround would be to batch process all legacy documents to replace occurrences of & with &

Demo Code:
Before using this script please read the notes and comments in the MCR file (which also includes some legal stuff). Basically, this code is provided as a demo and should be treated as if it were completely untested. I have tested it as best I can, but it has not gone through our regular rigorous test process. You may also wish to adapt this code by altering the script logic itself as you may find that the functionality does not meet the exact needs of your end users, etc.

Please also do not use this script without the permission of the people that maintain your XMetaL installation (if that isn't you). Although the possibility is low given the way I have coded this it could conflict with special customizations or scripts, 3rd party tools or plug-ins, a specific work-flow they have set up and wish you to follow, or any number of other things I cannot guess at. I would recommend telling them about your wish to have something like this and let them integrate it and test it for you.

Installation, Uninstallation, Script Logic, etc:
See comments in MCR file.

Reply

[Derek Read]

One other thing that having this script in place should help with is when a user enters an unescaped ampersand directly into an attribute value using the Attribute Inspector.

Reply

[scorho]

Does this also work for help product titles?

A product I'm documenting has an ampersand in the product name, so I used one in the map title. That seems to work OK, except that “&” appears in the product name on the help page title bar.

Reply

[Derek Read]

This script is meant for use with client-created customizations for documents initially created with 3rd party software that encode an ampersand using the numeric entity reference & (XMetaL Author itself will not encode an ampersand using a numeric entity reference).

Perhaps you could describe your issue in more detail.
Which Schema or DTD are you working with?
What do you mean by “help page title bar”?

Reply

[scorho]

Sorry. I meant the map title, which appears at the top of our WebHelp screen as the document title in a title bar.

I was able to get the ampersand by looking at the map in XML View, as described elsewhere in the forums. Only problem is, since I did that, I can only save topics if I go into Plain text View. If I try to save from any other view, I get a bunch of errors (last time I counted it was 58) that I have to click through before the file will save. So I solved one problem, but the solution caused another one.

Here are a couple of the errors I get. they're not very helpful.

concept:5:concept_D67B12FA9E744C36A2E78178EC81CFF6

and:

conbody:1:-topic/body concept/conbody

Like I said, I get more than 50 messages like this whenever I save unless I'm in plain text view.

Reply

[Derek Read]

These errors are not something I've seen before and a little surprising. Is the title on the error dialog simply “XMetaL Author Enterprise”?

Do you see the same errors if you press F11 or select “Refresh All References” in the Edit menu?

Can you provide a copy of the map, or perhaps a snippet from it that will give us some idea of what it contains? This is probably the best option, otherwise it might take a long time to guess what's going on. Please also let us know which version of XMetaL Author Enterprise you are running.

If a CMS system is involved here that will change things significantly. Please let me know if that is so, and which CMS system you are using.

You seem to have submitted a case along these lines to XMetaL Support as well. Would you prefer to deal with the issue here on the forum or move it to XMetaL Support? We'd prefer not to deal with the same issue in two places at once.

Reply

[scorho]

This issue still hasn't gone away. Refreshing references doesn't make any difference.

The worst thing is, if I forget to go into Plain Text view before saving a topic with a table, I get the usual errors, but then I get one that says “thead1: – topic/thead” that just keeps popping up. The only way to get past that is to kill xmetal in the task manager, which means, of course, that I lose changes.

I've gotten used to saving in Plain text, but it is annoying. I also have a co-worker who is going to have to make the same “fixes” to include an ampersand in the map title, but we're hesitant, in case he ends up with the same problem.

Reply

[Derek Read]

Sorry, I must have been sleeping when I read your message about “errors”…

The errors you are seeing are not really “errors”, they are alerts I put in to help a developer understand the script. They appear on purpose so that someone that takes this demo code and integrates it into their own customization would see that it is navigating to each element in the document. It displays the element name, how many attributes that element has set and the value. Because this is demo code (meant to be integrated into a customization) I didn't want it to be usable right away. I wanted developers to read everything in the file and understand it and then test it before unleashing it on their users.

From my original post:
“Before using this script please read the notes and comments in the MCR file (which also includes some legal stuff).”

The information in the comments in the MCR include a description of the issue, how it works (the basic logic of the script), some warnings about how it deals with entities, how to install, how to uninstall, etc.

There is one line you would need to alter to suppress the alerts:

Application.Alert(rng.ContainerName + “:” + attrCount + “:” + attrValue);

Comment that out, or delete it, and you will not see any.

Reply

[Derek Read]

See the following posting for an updated version of my original script that now handles < > in addition to &:
http://forums.xmetal.com/index.php/topic,1392

It escapes these characters immediately after you have entered them in the Attribute Inspector (so you no longer need to enter them manually as entities).

It also finds and replaces any occurences of these characters in all attributes in a document whenever it is validated so that an end user should never see a validation error related to unescaped copies of these characters in attributes (unless they are saving from Plain Text view).

Reply

[Author]

Posts