DITA: how do output the non-<abbreviated-form> of a glossent

[bridget.rooney]

Hi there,

I hope this is in the right place?
And I'll say thanks for your time first before getting into all the verbose detail below: )

I want to add a list of acronyms (loa) in my output (PDF and webhelp at this time). This should show the glossterm or glossSurfaceForm text (in my case, both are the same: I am happy to use either if I can get it working). In other words, it would print the long form of the glossentry and not the <abbreviated-form>.
I don't want items in the loa to be linked.
So I want a page in the PDF that is:

Acronyms used in this Help
Application Programming Interface (API)
Point of Sales (POS)
...

I don't want to print the entire acronym file (only either the <glossterm> or the <glossSurfaceForm>).
But I am also using the <abbreviated-form> as normal to reference the terms (glosssurfaceform on first occurrence, acronym on subsequent uses), and this all works perfectly.

I use a <map> to bind my topics (not a bookmap).
I've created a map to hold glossentry items: when I include them as topicrefs, the entire glossentry file prints out; when I include them as glossrefs nothing prints (as expected).
I've included the map that links glossentry items into the map.

*** I've created glossentry topics like this:
<glossentry id="glossentry_ol4_ghm_jp">
<glossterm>Application Programming Interface (API)</glossterm>
<glossdef></glossdef>
<glossBody>
<glossSurfaceForm>Application Programming Interface (API)</glossSurfaceForm>
<glossAlt>
<glossAcronym>API</glossAcronym>
</glossAlt>
</glossBody>
</glossentry>


*** I've included a map of these glossentry items, each added as (and this map is added as a mapref in the main map):
<map>
<title>DITA Topic Map</title>
<topicref href="common/source/GLOS_acrm_API.dita" keys="api"/>
...
</map>


*** I've referenced the item in topic as follows:
<li>Use the provided <abbreviated-form keyref="api"/> to do xyz...</li>

and this works as expected.


But I want to additionally include a list of acronyms.

Thanks so much for your time and help

[sorin_ristache]

Hello,

So I want a page in the PDF that is:

Acronyms used in this Help
Application Programming Interface (API)
Point of Sales (POS)
...

I don't want to print the entire acronym file (only either the <glossterm> or the <glossSurfaceForm>).
But I am also using the <abbreviated-form> as normal to reference the terms (glosssurfaceform on first occurrence, acronym on subsequent uses), and this all works perfectly.

The problem is that the PDF transformation does not select the same glossary description as the XHTML and WebHelp ones. Let's work with your example:

*** I've created glossentry topics like this:
<glossentry id="glossentry_ol4_ghm_jp">
<glossterm>Application Programming Interface (API)</glossterm>
<glossdef></glossdef>
<glossBody>
<glossSurfaceForm>Application Programming Interface (API)</glossSurfaceForm>
<glossAlt>
<glossAcronym>API</glossAcronym>
</glossAlt>
</glossBody>
</glossentry>


*** I've included a map of these glossentry items, each added as (and this map is added as a mapref in the main map):
<map>
<title>DITA Topic Map</title>
<topicref href="common/source/GLOS_acrm_API.dita" keys="api"/>
...
</map>

If in the DITA XML topic you have:

Code: Select all

 <p> TERM: <term keyref="api"/> </p>

 <p> ABBR: <abbreviated-form keyref="api"/> </p>

the PDF output will replace <term keyref="api"/> with the text content of <glossterm> and <abbreviated-form keyref="api"/> with the text content of <glossSurfaceForm>, which you don't want:

Code: Select all

TERM: Application Programming Interface (API)

ABBR: Application Programming Interface (API)

but the WebHelp output will replace <term keyref="api"/> with the text content of <glossSurfaceForm> and <abbreviated-form keyref="api"/> with the text content of <glossAcronym>, which is what you want.

You can't have the same output in both PDF and WebHelp output for the <abbreviated-form keyref="api"/> element even if you place the same content in <glossSurfaceForm> and <glossAcronym>, because the PDF transformation will prefer <glossSurfaceForm> to replace <abbreviated-form keyref="api"/>, but the WebHelp one will prefer <glossSurfaceForm> for <term keyref="api"/>. I suppose using the same content in all elements (<glossterm>, <glossSurfaceForm> and <glossAcronym>) is not a solution for you, because you want Application Programming Interface (API) in some contexts and API in other contexts.

We will report this consistency problem between PDF and XHTML/WebHelp outputs to the DITA-OT project.

[sorin_ristache]

In fact the DITA 1.2 specification from OASIS says that in the PDF output the longer form should be used (<glossSurfaceForm> or <glossterm>) for the first <abbreviated-form> element and <glossAcronym> should be used for the second <abbreviated-form> element, third one, etc. This is necessary for defining the glossary term for the reader on the first occurrence and using the abbreviated form (<glossAcronym>) on subsequent occurrences.

In WebHelp output the <glossAcronym> is always used for <abbreviated-form> because WebHelp is a form of electronic publishing format which allows tooltips and hyperlinks to the full definition of the glossary term. So the term can be fully defined on the first occurrence by attaching a tooltip and/or a hyperlink to the abbreviated form.

To conclude: you get the list of acronyms in both output formats if you make sure you have at least one preceding reference of type <abbreviated-form> to each glossary term before the reference in the list of acronyms. Preceding reference means a reference of type <abbreviated-form> to the same glossary term, occurring in one of the topics that come in the DITA map before the list of acronyms.