4 messages in org.oasis-open.lists.ditaFW: [dita] Question: local content in...| From | Sent On | Attachments |
|---|---|---|
| Su-Laine Yeo | Apr 26, 2011 3:22 pm | |
| Su-Laine Yeo | Apr 26, 2011 4:39 pm | |
| Bruce Nevin (bnevin) | Apr 29, 2011 8:28 am | |
| Bruce Nevin (bnevin) | May 3, 2011 7:50 am |
| Subject: | FW: [dita] Question: local content in <abbreviated-form> element with keyref | |
|---|---|---|
| From: | Bruce Nevin (bnevin) (bne...@cisco.com) | |
| Date: | May 3, 2011 7:50:23 am | |
| List: | org.oasis-open.lists.dita | |
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-l...@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:bne...@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-l...@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:bne...@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.
--------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php