References to UI messages in Documentation

> From Tim's comments on Requirements for localisable DTD design:
>
> 2.14 References to UI messages in Documentation
> Yep, by all means provide clues that such a string might be 
> a UI message (eg. Docbook's <computeroutput> or <screen> tags) 
> do this at the moment - clues which we use in our TM system to 
> aid segmentation...
> but I don't know if I'd call-out message strings directly -- 
> the XML document would be illegible without the message resource 
> file being avaiable, it might be better to just mark up the 
> section, and let the TM system fill in the translation.

Good point.

I guess, for many issues, will need to look at various possible scenarios,
provide some kind of list of preference for them, and have corresponding tags
when needed. That is where both the tag set specification and the "techniques"
(guidelines) document will need to be supporting each other.

I suppose we may even come up with cases where tags would be mutually exclusive:
"If you do it this way use these tags, otherwise use those tags".


Another aspect of UI reference that is, as far as I can tell (but I'll be happy
to be corrected), not covered by XLink, is the need for possible
searches/replaces in the text to use. There is a translate() function in XPath
that helps, but its not enough for real S&R.

A crude example: If you have <menuItem id="Open">&amp;Open...</menuItem> in your
UI file, where &amp; is used to mark a hotkey, you probably do not want that
ampersand in your documentation. The same goes for "...". So, somehow, the text
needs to go from "&Open..." in the UI document to "Open" in the linked document.

I don't think solving something like this should be our job, but we should
provide feedback to XLink or other WGs in cases like that.

-ys

Received on Wednesday, 23 February 2005 13:28:59 UTC