FW: [dita] Question: local content in <abbreviated-form> element with keyref

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

The <abbreviated-form> element has a fairly complex content model but it
should probably be empty because there are good reasons never to render
any content in it. Discussion below.

Comment?

	/Bruce

> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
> Sent: Monday, May 02, 2011 5:56 PM
> To: Bruce Nevin (bnevin)
> 
> Hi Bruce,
>
> Yes, that's a good summary of where my question lies. Given that
> <abbreviated-form> can contain content, and actually has a pretty
> complex content model, I think it would surprise users to have tools
> ignore that content all the time. It's a bit strange that this isn't
> simply defined as always being an empty element. However, the reasons
> you gave for the expected behaviour that you describe are reasonable
> too.
>
> Do you want to send your most recent message below to the TC? I think
> this needs wider discussion. The most correct solution, unfortunately,
> will probably be to leave the processing of content within
> <abbreviated-form> undefined for now.
>
> Su-Laine
>
>-----Original Message-----
>From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
>Sent: Fri 4/29/2011 4:47 PM
>To: Su-Laine Yeo
>Subject: RE: [dita] Question: local content in <abbreviated-form>
element with keyref
>
>Looking again at what you wrote I think I waaay overshot the mark. My
>apology for any annoyance. You're right, it doesn't say explicitly that
>content of <abbreviated-form> should not be rendered. That's because
the
>spec author was describing an empty element, so there is no content.
But
>you want there to be content as a fallback. So that's where your
>question actually lies.
>
>There should be no fallback in the publishing environment, there should
>be an error if the referenced <glossentry> topic can't be found.
>
>In the authoring environment, I said that according to the spec the key
>name is all you've got for fallback. There's a lot wrong with using
>local <abbreviated-form> content as a fallback. It could be quite
>misleading about the published result. You're inviting inconsistency
and
>error. You're multiplying the occurrences of words to be translated,
>because translators won't skip over them, and that can mount up to a
big
>expense. And of course it's another bit to author, each time the term
>occurs.
>
>        /B
>
>> -----Original Message-----
>> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com]
>> Sent: Friday, April 29, 2011 6:37 PM
>> To: Bruce Nevin (bnevin)
>> Subject: RE: [dita] Question: local content in
>> <abbreviated-form> element with keyref
>>
>> Hi Bruce,
>>
>> Where does it say that the content of <abbreviated-form>
>> should never be rendered? I can't find it mentioned at all.
>> If it's not mentioned, then maybe it can be used as fallback
>> text if the keyref-processing stuff fails.
>>
>> Su-Laine
>>
>> -----Original Message-----
>> From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com]
>> Sent: Friday, April 29, 2011 8:29 AM
>> To: Su-Laine Yeo; dita
>> Subject: RE: [dita] Question: local content in
>> <abbreviated-form> element with keyref
>>
>> As I read the description in 3.2.4.2.1, the content of the
>> <abbreviated-form> element "should" never be rendered. In its
>> place, the content of one of the elements in the referenced
>> <glossentry> topic "should" be rendered, the choice depending
>> on the context. Consequently, the content of the
>> <abbreviated-form> element "should" be no more than a
>> mnemonic to the author.
>>
>> That way, the author's topic don't have empty <term> elements
>> in them (or specializations thereof, like this).
>>
>> On the other hand, why pay translators to translate content
>> that is never rendered? That would be an advantage of leaving
>> them empty as indicated in the lang ref. Translate once in
>> the glossary, and instruct translators how to understand the
>> <abbreviated-form> element in context if their tools are not
>> capable of rendering them properly.
>>

Omitted here is the "way over the mark" reply to Su-Laine's question
"where does it say that it shouldn't be rendered?", which I include here
for completeness:

> -----Original Message-----
> From: Bruce Nevin (bnevin) 
> Sent: Friday, April 29, 2011 7:33 PM
> To: Su-Laine Yeo
> Cc: Bruce Nevin (bnevin)
> Subject: RE: [dita] Question: local content in 
> <abbreviated-form> element with keyref
> 
> I get there from the fact that the content of the 
> <abbreviated-form> element is not mentioned at all in the 
> rules in "3.2.4.2.1 abbreviated-form", and the example shows 
> an empty element. The elements that the rules say to render 
> are all children of <glossentry>. Here's the relevant excerpt:
> 
> Renderers should follow these rules when displaying an 
> <abbreviated-form> element that refers to a glossentry topic:
> 
> 1.	In an introductory context, processors SHOULD render 
> the surface form of the term by displaying the contents of 
> the glossSurfaceForm element from the referenced glossentry topic.
> 
> 2.	If the glossentry topic does not contain a 
> glossSurfaceForm element or the glossSurfaceForm element is 
> empty, processors SHOULD render the contents of the glossterm 
> element in introductory contexts.
> 
> 3.	In non-introductory contexts, processors SHOULD render 
> the abbreviated form of the term by displaying the contents 
> of the <glossAcronym> element from the referenced glossentry topic.
> 
> 4.	If the glossentry topic does not contain a glossAcronym 
> element or the glossAcronym element is empty, processors 
> SHOULD render the contents of the glossterm element in 
> non-introductory contexts.
> 
> From the point of view of someone authoring a topic, we would 
> expect the content to be in the term element in the topic. 
> From the point of view of someone managing terms, their long 
> and short forms, and their abbreviations, you want that 
> centralized in the glossentry topic where you write it 
> (correctly!) once and reuse it many time.
> 
> One compromise (contrary to the example) is to put some 
> content in the term element in the topic, understanding that 
> rendering ignores it. Wiser might be to have the authoring 
> tool look up the term and render it according to the above 
> rules, or if unable to look it up to render the key name, 
> which presumably is mnemonic. Here's the example:
> 
> <section>An <abbreviated-form keyref="abs"/> helps a driver 
> to stop. For this reason many find an <abbreviated-form 
> keyref="abs"/> useful.
> </section>
> 
> The reference is to this glossentry topic:
> 
> <glossentry id="abs-definition">
>   <glossterm>Anti-lock Braking System</glossterm>
>   <glossBody>
>     <glossSurfaceForm>Anti-lock Braking System 
> (ABS)</glossSurfaceForm>
>     <glossAlt>
>       <glossAcronym>ABS</glossAcronym>
>     </glossAlt>
>   </glossBody>
> </glossentry>
> 
> Assuming lookup is successful...
> (1) "In an introductory context" (e.g. if this were the first 
> use in the topic) render the <glossSurfaceForm> content:
> 	An Anti-lock Braking System (ABS) helps a driver to stop.
> (2) In that context, if <glossSurfaceForm> is missing or 
> empty, use the <glossterm> content:
> 	An Anti-lock Braking System helps a driver to stop.
> (3) In other contexts, render the <glossAcronym> content:
> 	An ABS helps a driver to stop.
> (4) In those other contexts, if <glossAcronym> is missing or 
> empty, use the <glossterm> content as under Rule 2.
> 
> If lookup is not possible, all you've got in this example is 
> the key name, and the spec doesn't tell you to put any 
> content in the <abbreviated-form> element.
> 
> The full example with both <glossSurfaceForm> and 
> <glossAcronym> content:
>  An Anti-lock Braking System (ABS) helps a driver to stop. 
> For this reason many find an ABS useful.
> 
> With only <glossAcronym>:
>  An Anti-lock Braking System helps a driver to stop. For this 
> reason many find an ABS useful.
> 
> With only <glossSurfaceForm>:
>  An Anti-lock Braking System (ABS) helps a driver to stop. 
> For this reason many find an Anti-lock Braking System useful.
> 
> With failed lookup (neither <glossSurfaceForm> nor <glossAcronym>):
>  An Anti-lock Braking System helps a driver to stop. For this 
> reason many find an Anti-lock Braking System useful.
>