Search code examples
xmlxsltpdf-generationdocumentation-generationdita

Creating a Modular Definition List using DITA


TLDR; I want to make a concise list of modular definitions using DITA OT transforming to PDF

Hi, I'm an indie developer trying to learn how to make good user documentation. I want it to be modular and easy to maintain and edit. With that in mind I've decided to make xml-based user documentation following a common standard like Dita. I want my documentation to compile to a PDF and I'm using DITA OT for transformation.

With that in mind, I started to make my first piece of documentation an issue, I can't seem to make a good modular definition list. The standard definition list element is hard to reference and all of the definitions are held in one file. So, I thought I'd try the other route, using glossentries. They seem to be very modular, one term per file, as well as have some nice features like easy referencing and rendering the term differently the first time it appears in the primary documentation.

However, I ran into some serious problems compiling each definition together.

I tried just putting a list of glossrefs in order on a page, but they rendered extremely badly making each definition a giant section header and displaying the surface term and acronym on new lines. I'd prefer something much more like a concise definition list with the term on the left and definition on the right.

I also tried putting them in the glossarylist element, but that element is only available in a bookmap and I want a much simpler piece of documentation than that (I don't want to separate things by chapters and the like).

Finally I tried putting the definitions in a separate ditamap and using a mapref. This still had the same rendering problems, but at least it lets me compile all of the definitions into a single intermediary file.

What I'm really looking for is some way to edit the xsl files or something to at least have a concise list of definitions. If possible after that, I'd like to have those definitions automatically sort themselves and only have a definition appear if it is referenced somewhere else in the documentation. Attached is a picture of what it currently looks like vs what I want it to look like as well as the basic dita files I'm using.

What I have What I'm trying to get, notice the terms are now more concise and in alphabetical order

I am open to solutions other than dita, but they must be modular and keep formatting and data separate.

Thanks in advance for any help!

Update: I now am much closer to what I am looking for! Using Radu's answer as a guide, I was able to make a custom plugin that changes the formatting of the glossentries. However, I'm having a very hard time figuring out how to increase the space between definitions... Any idea what the best way to go about this is? I think it's probably an attribute set of some sort, but I'm having a very hard time finding examples of them, any idea where the pre-existing ones are declared?

I'll also attach the most important segment of my code for reference! (Any pointers for making it more versatile are appreciated)

    <xsl:template match="*[contains(@class, ' glossentry/glossentry ')]" mode="processTopic">
    <fo:block>
      <!-- TODO: Replace with mode="commonattributes" -->
      <xsl:call-template name="commonattributes"/>
      <fo:block>
        <xsl:attribute name="id">
          <xsl:call-template name="generate-toc-id"/>
        </xsl:attribute>
        <fo:inline xsl:use-attribute-sets="__glossary__term">
          <xsl:apply-templates select="*[contains(@class, ' glossentry/glossterm ')]/node()"/>: 
        </fo:inline>
        <fo:inline xsl:use-attribute-sets="__glossary__def">
          <xsl:apply-templates select="*[contains(@class, ' glossentry/glossdef ')]/node()"/>
        </fo:inline>
      </fo:block>
    </fo:block>
  </xsl:template>

Solution

  • Adding a link also to your post on the Oxygen XML forum for completeness: https://www.oxygenxml.com/forum/post73981.html#p73981

    The DITA XML standard is usually used in commercial enterprise applications where people take the time to customize the published output using XSLT (or CSS for HTML-based outputs or when using CSS-based PDF processors) in order to achieve their desired results. XML-based documentation in general is based on semantic meaning, you do not control how the content will be displayed directly from the XML content but you rely on the publishing engine (in this case the DITA OT) which has default XSLT stylesheets handling elements in a default way and which can be enhanced with plugins to style content in different ways.

    A <glossentry> is considered by the DITA XML standard as being an extension of <concept> which is an extension of <topic>: https://www.oxygenxml.com/dita/1.3/specs/archSpec/technicalContent/dita-glossary-topic.html For example in Oxygen if you open a glossentry topic and select in the Outline view the root element, then look in the "Attributes" view, it's default @class attribute value is "- topic/topic concept/concept glossentry/glossentry ". The DITA OT's XSLT stylesheets for XSL-FO based PDF publishing match class attribute values for elements and produce certain XSL-FO elements. There is some specialized glossentry handling in the stylesheet "DITA-OT/plugins/org.dita.pdf2/xsl/fo/glossary.xsl" but only if part of a glossarylist. Other than that the default handling for a DITA <concept> from "DITA-OT/plugins/org.dita.pdf2/xsl/fo/concept.xsl" will apply. In general for XSL-FO based PDF processing people would create DITA OT plugins to add XSLT stylesheets with templates which match certain elements and style them in different ways than the base handling for the element.