RE: [dita] Product names and reuse

["Jim Tivy" <jimt@bluestream.com>]

I think a term is a concept and the concept is not changed by
capitalization, possessive and stems.  So I would go for one glossary entry
with multiple glossAlts.  Yes, tm and others would have to be allowed in
glossterm and glossAlt/glossShortForm as well as term - for now you might
get away with the unicode character for tm.

> -----Original Message-----
> From: Mark Poston [mailto:mark.poston@mekon.com]
> Sent: January-17-13 1:33 AM
> To: Eliot Kimber; Jim Tivy; dita
> Subject: Re: [dita] Product names and reuse
> 
> Eliot,
> 
> We looked at various options for using conkeyref to do as you say. The
> difference being that we looked at using synonyms for each variant. But
this
> still has the same problems when translating because there is not always a
> one-to-one relationship.
> 
> Problems is there just too many variants to manage. It's not just
> singular/plural and possessive options, but also capitalisation - when
terms
> are used at the beginning of sentences. So the list of variations gets
quite
> long for a given term.
> 
> Luckily for us, the use of terms did need also require navigational links
to the
> glossary entries so it was an ideal solution. Compromises on reuse had to
be
> made though.
> 
> Kind regards
> 
> Mark Poston
> Senior Technical Consultant
> Mekon Ltd.
> Tel. +44 20 8722 8461
> Mob +44 7515 906032
> Skype mark_mekon.com
> 
> 
> 
> 
> On 16/01/2013 20:27, "Eliot Kimber" <ekimber@rsicms.com> wrote:
> 
> >Another potential issue with the glossary-based approach is that the
> >currently-defined behavior for any keyref-based reference from <term>
> >or <keyword> to a topic is to make the reference into a working
> >navigational hyperlink, which would often not be desired.
> >
> >If you wanted to use a glossary entry to hold variant forms of the term
> >for use by conkeyref, you're still faced with the problem that <tm>
> >can't contain <ph>, <text> can't contain <tm>, etc.
> >
> >You could create multiple glossary entries, one for each variation and
> >put the necessary markup in the <glossterm> element, and then use a key
> >naming convention to have a base part of the name plus a distinguishing
> bit, e.g.
> >"prodname_base", "prodname_singular", "prodname_singular_possessive",
> >but that would be a lot of glossary entry topics which wouldn't
> >otherwise be naturally related to each other, so that seems not so good.
> >
> >I will observe that the "variables" mechanism I defined in DITA for
> >Publishers (and proposed but withdrew in the face of complexity
> >objections)
> >could easily be adapted to do something like what Troy outlined, since
> >the mechanism is completely semantic and doesn't depend on any existing
> >DITA conref or addressing facilities.
> >
> >It also addresses the scoping requirement that keys don't meet in DITA
> >1.2 (and may never meet given our progress to date on defining scoped
> keys).
> >
> >
> >Cheers,
> >
> >E.
> >
> >
> >On 1/16/13 1:20 PM, "Jim Tivy" <jimt@bluestream.com> wrote:
> >
> >> Yes, I like the term and glossary approach.  If the name of the
> >>feature (term
> >> name) is changed, then you can use a "who references me" on the
> >>glossary entry  and read the topics to ensure that they still make
> >>sense.  If the meaning of  the feature name changes significantly then
> >>there will be problems so all its  contexts have to be checked.
> >> For plurals and possessives or other alternative forms of the term
> >>the link or  glossref key should go to the appropriate
> >>glossAlt/glossShortForm entry.
> >> Note, glossShortForm is not fully appropriate but I see no other more
> >>appropriate tag.
> >>
> >> If we can use a fragment identifier in the glossref href then this
> >>linking to  different forms could be like this:
> >>
> >> <glossref keys="front.panel.plural"
> >> href="geFrontPanel.dita#TopicId_FrontPanel/altplural"/>
> >>
> >> For translation, it sounds like there are potential problems with
> >>word  inclusion mechanisms such as this term one.  Unless translation
> >>tools also let  the translator view the "who references me" to review
> >>the contextual effect of  their translations these problems may
> >>persist and the entire word inclusion  mechanism is brought into
> >>question for translation output.
> >>
> >>
> >> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
> >>Behalf  Of Mark Poston
> >> Sent: January-16-13 2:58 AM
> >> To: dita@lists.oasis-open.org
> >> Subject: Re: [dita] Product names and reuse
> >>
> >>
> >> Andrzej,
> >>
> >>
> >>
> >> I would be interested to understand more about how, in your unbiased
> >>opinion,  these issues can be resolved in DITA. Or, indeed, whether
> >>you think that they  cannot be resolved and need the support of 3rd
> >>party tools when translation is  required.
> >>
> >>
> >>
> >> In a project I have recently been working on we came to the
> >>conclusion that  reuse methodologies were not appropriate due to the
> >>reasons you have stated.
> >> The translation vendor concerned raised their concerns about having
> >>to  translate reused terms (not just product names).
> >>
> >>
> >>
> >> The actual solution was more about having to translate terminology
> >>whilst  still needing to link to glossary entries. The result was that
> >>we used <term>  tags to link to glossary entries. Where no content was
> >>defined in the term,  the value could be pulled from the glossary
> >>entry itself. This gave the  translators, however, the ability to do
> >>what they needed within the scope of  the <term> tag.
> >>
> >>
> >>
> >> This solution, however, would still fall apart if names or terms
> >>completely  changed.
> >>
> >>
> >>
> >> I can't see that there can be a completely DITA-based solution to
> >>this issue,  especially when translation is required.
> >>
> >>
> >>
> >> Kind regards
> >>
> >>
> >>
> >> Mark Poston
> >>
> >> Senior Technical Consultant
> >>
> >> Mekon Ltd.
> >>
> >> Tel. +44 20 8722 8461
> >>
> >> Mob +44 7515 906032
> >>
> >> Skype mark_mekon.com
> >>
> >>
> >>
> >> From: Andrzej Zydron <azydron@xtm-intl.com>
> >> Organization: XTM-INTL
> >> Date: Tuesday, 15 January 2013 18:34
> >> To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
> >> Subject: Re: [dita] Product names and reuse
> >>
> >>
> >>
> >> Hi Troy,
> >>
> >> 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 be extensive.
> >>
> >> English is a linguistic freak (a fact that is lost on most
> >>monolingual English
> >> speakers) 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.
> >>
> >> Best Regards,
> >>
> >> Andrzej Zydroń
> >> ---------------------------------------
> >> CTO
> >> XTM International Ltd.
> >> PO Box 2167, Gerrards Cross, SL9 8XF, UK
> >> email: azydron@xtm-intl.com <mailto:azydron@xtm-intl.com>
> >> Tel: +44 (0) 1753 480 479
> >> Mob: +44 (0) 7966 477 181
> >> skype: Zydron
> >> www.xtm-intl.com <http://www.xtm-intl.com/>
> >>
> >>
> >>
> >>
> >>
> >>
> >>
> >> 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 guy.
> >>>
> >>> 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.
> >>>
> >>> Troy Klukewich
> >>> Manager & Information Architect
> >>> Fusion HCM
> >>> Oracle Corporation
> >>>
> >>> 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.
> >>>
> >>> Problem descriptions
> >>> 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:
> >>> * <uicontrol>
> >>> * <wintitle>
> >>> 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
> >>><text>.
> >>>
> >>> 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 render correctly.
> >>>
> >>> Thoughts about how we might try to address this problem? And sense
> >>>about how  big (or small) this problem is?
> >>>
> >>> --
> >>> Best,
> >>> Kris
> >>
> >
> >--
> >Eliot Kimber
> >Senior Solutions Architect, RSI Content Solutions "Bringing Strategy,
> >Content, and Technology Together"
> >Main: 512.554.9368
> >www.rsicms.com
> >www.rsuitecms.com
> >Book: DITA For Practitioners, from XML Press,
> >http://xmlpress.net/publications/dita/practitioners-1/
> >