DITA 1.2 Feature Article: Acronym Best Practices

White paper from the OASIS DITA Adoption Committee. Authored by DITA Translation Subcommittee. Published 24 May 201.

The draft DITA 1.2 spec says, "When the writer provides a keyref to a glossentry topic that contains a <glossSurfaceForm> element, a process should emit the surface form in introductory contexts where the term might be unfamiliar to the reader or in other contexts where a precise term is appropriate. In other contexts a process should submit the abbreviated form of
the term. Note that the definition of an introductory context will differ for every deliverable format."

In other words, the spec leaves open the question of whether to expand a term in the first occurrence in the book or the first occurrence in each chapter.

I agree it would make sense for DITA publishing tools, such as the DITA Open Toolkit, to expand terms once per chapter. I don't know if any DITA publishing tools do this yet.

Su-Laine Yeo, Solutions Consultant for XMetaL, JustSystems


Hello, all...

Has the following proposal already been discussed?

For deliverables in book (e.g. PDF) form, many tech pubs organizations require that the expanded form of a term (the surface form) be used not only for the 1st occurrence in the book but also for the 1st occurrence in each chapter. One organization that I'm aware of required the surface form at the beginning of each major (topmost) section of each chapter.

Would it be possible to add to the spec for the <abbreviated-form> element that when rendering from the bookmap specialization, the processor must output the surface form for the first use in each chapter?


Steve Fogel, Information Architect, Oracle Corporation.

XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I