Thank you for this
interesting post. Your
mechanism will work for English, and the small group of
languages with a similar primitive morphology. Unfortunately it will
fall apart when you come to translate the XML content into any language with a richer
morphology - the
resultant output will produce
ungrammatical output and the cost of recovery from this will
English is a linguistic freak (a fact that
is lost on most monolingual English
which allows for the relative easy
substitutions that you described. I you
plan to translate your content into other languages
this is not a practical possibility.
XTM International Ltd.
PO Box 2167, Gerrards Cross, SL9 8XF, UK
Tel: +44 (0) 1753 480 479
Mob: +44 (0) 7966 477 181
On 15/01/2013 15:20, Troy Klukewich wrote:
I've been watching people hack DITA for years trying to deal with
product and sometimes feature names in a consistent XML-like way.
Prior to DITA, I worked on a similar XML architecture
(concept/task/reference) with a custom processing kit. With
numerous product names and feature names in an almost continual
state of flux, we decided to treat product names and feature names
as global variables with a mapping file for the literal strings
(in English). The literal product and feature names were then
inserted at build time and appeared in the output. (We used editor
maps to virtually display the same content in the authoring editor
for the convenience of writers.)
The inherent problem with this approach is that the mapped strings
must be translatable. As products and features can have plurals
and possessives, these must also be handled in the mapping file
and accounted for in the variable element.
It is not permissible for instance to have a construct like:
<varProduct>s or <varProduct>'s appear in the XML
content as translators will translate the mapping file elsewhere
and not be able to easily reconcile the plurals and possessives in
the content itself. (I think these were the only variations we had
to worry about, but it's been a while I admit.)
So we expanded the variables schema to include attributes for
plurals and possessives in the variable elements themselves, which
the writers selected at authoring time. This required some
training as the process is a little abstract. You do not for
instance add an apostrophe to the product XML element when
building a possessive, but select an attribute in the editor and
let the build do it.
The mapping file then contained base product and feature names
plus their plural and possessive forms.
A build engineer maintained the mapping files and creation of new
variable codes supporting first instance of new features and
product names. We had workflow where writers would contact the
engineer when needing a new variable value that was not already
covered, though most were set up at the beginning of a release
with the identification of new products and features.
The upside of this approach is that the output for product or
feature names was entirely automated. If feature or product names
changed late, as often happens in the software industry, we
tweaked the mapping file at build time and the writers didn't have
to do anything at all.
As far as graphics and special formatting in some product and
feature names went, we handled this purely at build time with
special processing instructions for the applicable variables.
Otherwise, we're really talking about desktop publishing practices
in XML and I'm not sure if DITA should inherently support this or
if those features should be handled with a custom processing chain
for those particular elements. Strictly speaking, formatting and
graphics are a rendering operation during build time. In XML,
writers shouldn't have to care about how to format a product name
or add special graphics to it. That's my philosophy as an anti-DTP
I'm sure there are other ways to accomplish the same thing, but
this global mapping architecture worked really well, saved a lot
of time, and was just generally really convenient all around for
everybody once implemented.
In short, I inherently think of product and feature names as
variables and whatever architecture handles and processes them
must be able to address the issues of variables in text.
Manager & Information Architect
On 1/14/2013 1:43 PM, Kristen James Eberlein wrote:
A thread about difficulty in reusing products names has cropped
up on the dita-users list.
1) Information architects or editors design a reuse strategy
that revolves around using the <ph> element to hold
product names. They then discover that they cannot put a
<ph> element within any of the following elements:
2) Another team decides to use <keyword> to hold their
product names -- better choice -- but they also discover that
they cannot put a keyword element within a <wintitle>
element; they have to duplicate their product names within
<text> elements for use within <wintitle>
elements. And the <tm> element is not available within
3) Yet another team is stymied because their product name
contains typographic formatting (superscript, subscript, bold
or italic formatting, an inline image) that cannot be
contained in either the <keyword> or <text>
element. And while the text element can nest, the @outputclass
attribute is not available.
Architects and the writers are caught between a strong desire
to reuse content and ensure that product names are
consistently used, and a need to have their company's name
Thoughts about how we might try to address this problem? And
sense about how big (or small) this problem is?