How can I get XML cross-references to translate to Structured FrameMaker?

Report · Nov 20, 2012

I've been using Structured FrameMaker from the beginning, and have designed many EDDs, and about 10 years ago I did some translation of SGML into Structured FrameMaker (7.2) which worked well.

Now, (with FrameMaker 10), I've had to design an EDD to translate XML documents into Structured FrameMaker.

In my EDD I've a CrossReference element called XRef; this has an attribute of ID, which in turn has a value of IDReference and has Special AttributeConrols of ReadOnly.

My target elements in the EDD all have an ID attribute with a value of UniqueID.

My XML document's target xref element has an attribute of linkend, and in XML this works as I'd expect.

When I pass the XML file through the EDD/Template, everything works except that I get an ID = no value, which, of course, results in no display of the cross-reference data in the document.

Oddly, in structured FrameMaker, my element of link, with an attribute of linkend, works as it should, and displays the data. It may not be important, but the value for linkend is IDReference not UniqueID, and this displays correctly (I changed this attribute's value to Unique ID in my EDD and it made no difference to the XRef value in my document).

After making all these EDD changes, I've been careful to save the changes, import them to all files in my book and finally update the book. Everything hangs together - except, of course, that the cross-reference doesn't work.

I'd sincerely appreciate any help or advice other users might have because I'm quite frankly stumped.

Report · Nov 20, 2012

Chris,

I believe you have to use read/write rules to translate the XML attribute linkend to the FrameMaker EDD attribute ID.

attribute "linkend" is fm attribute "ID";

See the Structured Application Guide that comes with FrameMaker.

Van

Report · Nov 20, 2012

Van,

Sorry, didn't know the etiquette with forums (I'd already replied to your e-mail). For completeness, here's what I said:

I already have linkend as an attribute of element link (which works and displays properly).

Changing my r/w rules as you suggested doesn't, unfortunately, change anything.

There is the other thing with the r/w as they come with FrameMaker, in that xref shows its attributes as properties of element "xref"; so, following what you suggest, I'd need to declare (under xref):

attribute "linkend is fm property cross-reference id

I'd already tried that but with no success (I don't think internal to element xref, that I need to say cross-reference "id").

This looks like something specific to the xref element, as opposed to the general purpose ID attribute which appears in pretty well all of our elements for, eh, cross-references purposes. In Structured FrameMaker a legally inserted xref element works correctly, it's just the translation from XML that's causing the problems.

Too, I'm guessing the bit about linkend above is also affected by the earlier listing in the r/w rules:

attribute "id" is fm attribute "ID"'

At the moment, in the description for the xref element I have:

attribute "linkend" is fm property cross-reference ID.

I even saw one note on the web which suggested that departments doing what we're trying to do should just go ahead and re-enter cross-references in the resultant Structured FrameMaker book. A pretty hopeless task given that our books are often many chapters long with hundreds of pages and who knows how many cross-references. This is taking no account of the human-error side of such an undertakaing.

We've not given up hope yet; but thanks for your help, and I'm sorry what you suggested didn't work.

Regards

Chris

Report · Nov 21, 2012

Hi Chris,

I think you should be able to get some help here to get this fixed. For me, though, I need some more clarification, which may help me or somebody else figure this out.

First of all, it seems odd to me that you have an IDReference attribute named "ID". Perhaps there is no problem with that, but then again, perhaps there is something funny going on, since apparently you are using the same attribute elsewhere as a unique ID. Did you consider renaming this to IDRef or something like that? Or, what would be the problem with just keeping the name as "linkend", since this seems to be working with another element called <link>, right? Occasionally, although it is very bad, FM will exhibit hardcoded behavior with respect to certain element and attribute names, overriding anything that you try to customize.

Secondly, you say you have the following rule for <xref>:

attribute "linkend" is fm property cross-reference ID.

I've never tried to do what you are attempting, but it seems that this one rule could be insufficient. You are trying to do two things: 1) Tell FM that the 'linkend' is the xref ID and 2) that the resolved IDRef value should populate 'ID' in the FM document, not 'linkend.' So, it appears to be a bit of a tall order, if that one rule doesn't work. One would think that FM would be able to figure it out, since you can only have a single IDRef attribute on an element, right? But, having said all that, I don't know what else you could do with the rules. Van suggested this:

attribute "linkend" is fm attribute "ID";

...but I'm not sure if that is the right approach, since we aren't talking about a direct transition of a value from one attribute to another. This is a case where a property needs to be resolved to make an FM object (ie, an xref) work. So, it doesn't surprise me that it didn't work, although it was a worthy suggestion.

Thirdly, you didn't mention if you are using a DTD or schema with your structured app (I assume you have all this set up). There are special ways that you have to declare cross-reference elements in each, otherwise some things just don't work right. Have you explored any changes in this area?

Here's one thing I can suggest which I'm pretty sure will solve the problem... a simple XSLT stylesheet. If you are convinced that there is no problem with using an attribute named 'ID' as an IDReference, it would be quite simple to invoke a simple stylesheet upon import that renames all 'linkend' attributes on <xref> elements to 'ID'.

It does seem, though, that you should be able to solve this with read/write rules and DTD/schema setup. Without the ability to experiment directly, I don't have any additional ideas at the moment.

Russ

Report · Nov 21, 2012

Chris,

I agree with Russ that you should NOT name attributes that contain unique IDs and attributes that contain ID references with the same name. Use ID and IDRef or some similar dichotomy.

Also your original post suggested to me that you were using linkend as the ID attribute in the XML targets of your cross-references. That was the reason I suggested the read/write rule

attribute "linkend" is fm attribute "ID";

That is, translate the XML ID linkend to the EDD ID, ID. But it appears that did not work. Anyway, try to resolve the naming issue first.

This may have nothing to do with your situation...But FrameMaker structured documents also record the file name and relative path for a cross-reference to another file, even though this is not displayed in the structure view. This can generate unresolved cross-references. For example, suppose you have a book with two files and a cross-reference from file A to file B. Now you replace file B with file C, in which file C contains an element with the same ID value as the target element in file B. Looking at the structure view, you can see that the IDref vale in file A matches the ID value in file C. But FrameMaker will see this as an unresolved cross-reference. When you resolve it, the IDref does not change in the structure view; it simply changes from unresolved to resolved.

Since you are opening XML that was not exported from a structured Fm file, cross-references may not be resolved when you first open the XML file, especially references between files. I create parts catalogs from raw XML data. The cross-references are established with an import XSLT, but they are all within the same file; and they DO resolve upon opening.

Van

Report · Nov 23, 2012

Van,

Thanks for your reply. I think I may have covered most of what I was trying to do when I replied to Russ this morning (see above).

We've not cracked it yet, but if you can see anything in what I've said that helps, I'd appreciate the advice.

Regards

Chris

Report · Nov 26, 2012

Hi Chris,

At this point, I don't have any additional ideas. Although it might not be feasible to do so, if you were able to send some sample files, I'd be happy to take a look. I think I'd need to do some direct experimentation to get any further. I do think there should be a solution to this, one that is not terribly complex.

Russ

Report · Nov 26, 2012

Russ,

I'm still amazed that people are so helpful; so a big thanks to all.

I'll have to look into this again and see what I can figure out. Trouble is that although the xml stuff is very short, and can be read by any reader, my FrameMaker EDD is 120 and climbing.

I'm still perplexed that this is proving to be so elusive. That said, in just about all the on-line stuff I've read, the general comment seems to be it doesn't work. That's a bit like a red rag to a bull, and I can't believe that so many years into FrameMaker, whatever version, that nobody has solved this "problem". Or at least fallen into the same hole I have.

I'm more than prepared to believe that I've not got the EDD right, because I've never done this xml stuff before, so an easier solution might be if I could see the few lines of an EDD that have solved this, and then try and shoehorn them into my EDD.

Ideas on a postcard!

Regards

Chris

Report · Nov 27, 2012

Hi Chris,

Van and Russ covered the issue well, let me add my thoughts..;)

What does your dtd say about the xref-element?. I had a similar problem ages ago, where the application used XML database and the cross references were using DITA-style linking, the form of xref-element's idref attribute was <db-xpath-to-file>#id-value or link source, like

<intref idref="/a/b/test.xml#abc123"/>.

Framemaker cannot handle this, so I used XSL to create proper xml stuff, in this case we also changed the element name because idref-type attribute naming conventions don't allow xpath-style syntax:

DTD used by frame says:

<!ELEMENT FMrefint EMPTY >

<!ATTLIST FMrefint
refid IDREF #IMPLIED
format CDATA #IMPLIED >

The crucial point is that the the refid attribute is of type IDREF, otherwise things don't work.

r/w rules are:

element "FMrefint"

{

is fm cross-reference element "FMrefint";

attribute "refid" is fm property cross-reference id;

attribute "format" is fm property cross-reference format;

}

EDD is simple:

Element (CrossReference):FMrefint

BR,

Martti

Report · Nov 23, 2012

Russ,

Sorry about the delay in replying; got sidetracked trying to fix some FrameMaker 10 problems; on occasion, it laughs and crashes if we copy an element in a document and paste it to somewhere illegal. This doesn't happen all the time, but it might be something someone might do, so it was interesting to know.

Anyway, back to cross-references.

In our r/w rules we have:

"linkend" is fm attribute "ID";

Can we also have a similar line under the cross-reference element as:

element "xref"

{

is fm cross-reference element "XRef";

attribute "linkend" is fm property cross-reference id;

attribute "role" is fm property cross-reference format;

} ??

At the moment the second line is:

.....attribute ID is fm property cross-reference id;

I tried adding the attribute "linkend" is fm property cross-reference id; (so that I had both linkend and ID) bit but this made no difference.

In general use cross-references work, in that it picks up data in one place in the document, e.g. WorldWideWeb, and repeats it elsewhere. So in our xml file we have a link element with an attribute linkend which, when it's processed (ignoring the handshake code used to link the two - which could be something vague like 12345vvdog), repeats whatever is the target.

Conversely, for a cross-reference, in xml they use an xref element which also has a linkend attribute (similar mysterious secret handshake behind the scenes) which is deemed to point to a list of references. This looks like it might be the stumbling block in that it links to an area in the xml document which is used as an internally generated list of references. Apparently this is only built when the xml book equivelent is finalised, so is not, like the link and linkend coupling described above.

I've passed this back to the xml people, and they are investigating a different way of preparing their cross-reference to a list of references (I'm now thoroughly confused with all these references - good thing the weekend's just around the corner).

I appreciate all you help and advice, I'll admit that this is a lot more difficult to understand than straight-forward EDD element creation along with their respective attributes. Life used to be so much more simple back then!

In sum, what I thought I was doing was allowing an ID attribute with a value of IDReference in my elements, this was deemed to allow for FrameMaker cross-referencing. In Structured FrameMaker, on its own, this works just fine; it all fell flat on its face when trying to import xml. I tried to see whether the xref element's ID attribute could also be a UniqueID, but as just about everyone has said, this is a silly idea. I was just trying stuff to see whether it might make a difference - you'll not be surprised to see that it didn't!

For the moment, I have attributes called ID with a value of IDReference, and I understand you're all suggesting to leave it at that.

If I understand correctly, I could eventually use an IDRef attribute if I wanted a UniqueID value to be used, though I'm not sure what a UniqueID is used or useful for, so will file that for future use.

Again, thanks for the advice and help.

Chris