Tuesday, March 16, 2010

Writing in DITA - Tip #1

Problem statement

Theoretically, the <xref> tag can contain plain text. It must therefore be possible to write something like:

<xref format="html"
href="http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/topic/com.ibm.swg.im.cognos.ug_fm.8.4.0.doc/ug_fm_id21834Troubleshooting.html#Troubleshooting" scope="external">Troubleshooting guide</xref>
The authoring tool we use at work (Arbortext Editor) very decidedly does not think so.
So, the resulting output looks, er, ugly.

Workaround

Step 1: Insert a <desc> tag inside the <xref> tag, type something within the <desc> tag (it shows up as hovertext in transformed output), and then type something just outside the <desc> tag but still within the <xref> tag. Like this:
Step 2 (optional): Delete the <desc> tag.
Step result

Musings

I am fairly sure the problem is not a DITA bug but an Arbortext Editor bug. Anyone seen anything similar?

Post script,2 days after original post

See an alternate solution here.

Another post script, 20 days after the original post

The Arbortext people found this blog post and offered to help but by that time I had already found a solution. I am impressed by their follow-up - they are really trying to keep track of user pain points and minimising the attendant frustration. Thank you Arbortext (and Liz Fraley).
I'm still not sure, though, if it's not an Arbortext bug. The error message box is captioned "Arbortext..." and it has a bug number. The problem was I couldn't find a list of error messages (and possible resolutions) in the Arbortext help. Per my understanding, the problem seems to be - text selected within an xref tag cannot be overwritten; it can be removed only if it is not selected AND some other text is typed in AND the "generate referenced text" button clicked again. Maybe it's not a bug. But as far as I know, a standard method of deleting text is by overwriting it.  Maybe an error message section in the help docs would help?

6 comments:

Liz Fraley said...

This sounds like a problem with your install. Are you using a specialization? I can't reproduce this problem on any of the versions of Editor that I have. Did you create an appsave and submit a case to support?

Anindita Basu said...

Thanks Liz for taking the time out to help. Well, the problem cannot be reproduced by my team-mates either! And we're all using the same DITA specialisation and the same Editor version. I tried looking through the Editor help for an explanation of the error message but couldn't find anything. Um, no, I haven't submitted anything to support yet - I wanted to explore this further before raising a request.

Liz Fraley said...

Hi Anidita - sorry it took me so long to get back to you. I forgot to bookmark your page. It sounds like you had a problem on install or something got corrupted somewhere along the way. Is it still happening? There is a way for us to find out what's happening, but quite frankly, that would be considered work on our part. Feel free to contact me offline if you want to pursue this further.

Liz Fraley said...

BTW: Mind correcting the post? This isn't an Arbortext Editor bug.

Anindita Basu said...

Am not sure if it isn't an Arbortext Editor bug. If it's not a bug, it must be a quirk :)
I've updated the post.

Liz Fraley said...

You get the error from Arbortext because something isn't there that it expects/needs to do what you want to do. As yours was the only installation that has this issue (out of everyone on your team), it makes me think something went wrong in install or is otherwise wrong with your system. As a result, the issue isn't intrinsic to Arbortext, but Arbortext was the one that found the problem on your system. (That's a good thing.) Reinstall fixed the problem?