Creating a Definition List/Glossary in PDF

[clarkbrendan]

Hi, I'm new to making DITA Content and am looking to make a relatively simple piece of user documentation (pdf) as my pilot project. While I am trying Oxygen with the 30 day free trial, I am trying not to rely on it. Therefore, any transformations I am making are done directly through DITA OT.

One of the important things in this documentation is a list of definitions that is referenced throughout the document. I considered using a definition list and xrefs, but I'd like each definition to be a separate topic to make them easier to reuse and I'm a big fan of the glossSurfaceForm and glossAcronym attributes. However, whenever I use abbreviated-form, it will display the correct text, but it won't actually link to the page where the definitions are. Whereas if I use xref with the glossEntryies/glossrefs it will link correctly but it won't display right (only displays term rather than surfaceForm and acronym)

I am using print="yes" in all of my glossrefs, in fact, if I don't, it won't even complete the transform (if I'm using a reference to it anywhere that is).

All of this works perfectly when transforming to html, but it is very important that this user documentation be in pdf format to make it more easily accessible.

Also, on another note, would someone quickly detail how I might change the formatting of the glossary so that it doesn't look like an individual section for each definition but instead more like an actual definition list ("Definitions" as title at the top, followed by a list of words with the definition next to each one). Perhaps even grouping the individual glossary entries into an intermediate file?

One other idea I had that I would have liked to implement but found no good way of going about it is a making a definition list where each entry in the list only appears in the final publication if it is referenced somewhere in the DITA files. Not sure if this is at all possible, but it would be an extremely effective tool for the purposes of reusability in documents pertaining to the same field.

This whole part of the process has been a whole lot more confusing than I thought it would be given how simple a list of definitions is and how common it is in good user documentation. Thanks in advance for any and all help!

[xephon]

Maybe these whitepaper help

http://www.oasis-open.org/committees/do ... 112008.doc

https://groups.oasis-open.org/higherlog ... t_id=35766

You can also find examples in the spec

https://www.oxygenxml.com/dita/1.3/spec ... ments.html

You can find more of those and some other useful links on my website https://stefan-jung.org/dita-getting-started/

[clarkbrendan]

I appreciate the feedback! The website especially is going to make it easier for me to learn the concepts I need to get started. Unfortunately regarding this issue I had already read a lot of the documentation you sent and what I hadn't was just rehashing the information in a slightly different way. My primary problem is that abbreviated-form doesn't actually link to the glossary item when rendering as a pdf. Does anyone have a full example where this (or something similar) works when compiled? I don't know what I'm doing wrong. Below are (the important parts) of what I'm putting in each file. I'm compiling using this command: dita --input=test.ditamap --format=xhtml

test-glossentry.dita:
<glossentry id="test-entry">
<glossterm>CAD</glossterm>
<glossdef>a set of software used to create designs digitally</glossdef>
<glossBody>
<glossSurfaceForm>CAD (Computer Aided Design)</glossSurfaceForm>
<glossAlt>
<glossAcronym>CAD</glossAcronym>
</glossAlt>
</glossBody>
</glossentry>

test-map.ditamap:
<glossref keys="cad" href="test-glossentry.dita" print="yes" processing-role="normal" format="dita"/>

test-topic:
<p>In engineering, <abbreviated-form keyref="cad"/> is used to make detailed plans before manufacturing the product</p>

[xephon]

I remember that I had a lot of headache because of that. And I figured out a solution which worked for me, but is not really following the given examples in the whitepapers. I am attaching you a solution based on your data, which should at least work for XHTML. What you are trying to do could work. But if you are planning to translate content like this, you might ran into issues, when using inline strings like so:

In engineering, <term keyref="GLS_CAD"/> is used ...

This might work in many cases, but when you translate, you have to consider about inflecting languages. And some languages are really weird, like Finnish, for example. Substantives may inflect in a very weird way, so what works in English might not work in other languages. If you only have to provide English, relax and enjoy the simply life.

To be on the safe side, do this:

In engineering, <term keyref="GLS_CAD">CAD</term> is used ...

This is redundant and more verbose, but translatable.

If you check the open issues, you will find some related to abbreviated-form: https://github.com/dita-ot/dita-ot/issu ... bbreviated+

glossary.zip

(23.06 KiB) Downloaded 5 times

[clarkbrendan]

Thank you for the link to the bugs on Github! One of the closed issues, "abbreviated-form and term dont link to entry in PDF output" detailed my problem quite well. The cause of the problem was one of the defaults of glossref, @linking. It defaults to none meaning that nothing can link to the glossentry. Similar to "print=no" being the default, "linking=none" is a really weird and unintuitive default for glossref. I feel that this should be revised, but based on complaints I've found around the internet regarding the "print=no" default, it seems it has been this way for a while.

Also, I don't want to use <term keyref="GLS_CAD">CAD</term> because I want the term to change depending on the glossary entry values "glossSurfaceTerm" and "glossAcronym". I'm trying to understand your point regarding translation, but I can't wrap my head around what you are getting at.

Regardless, that fixed the problem, now abbreviated-form actively links correctly to the glossary reference because I set "linking=target-only".

I am still trying to figure out how to format the glossary better though seeing as right now it is very bulky due to treating each term as a separate section rather than a concise looking list of definitions. Any chance you could point me towards a guide or two on editing how topics are displayed?

[xephon]

Unfortunately I don't have code to change the appearance of the glossary. Why do you use the old XHTML? Why not the Oxygen Webhelp or at least HTML5? If you are more interested building a terminology instead of a glossary, try my terminology plug-in. You'll find the link on my website.

[clarkbrendan]

Actually that was a typo in one of my replys, whoops. I'm not using xhtml, that was just a test I was running to see if it transformed right into that language. At the moment at least I'm exclusively compiling into pdf, once I get a full piece of documentation that looks good in that output, maybe I'll look into also using it with oxygen webhelp or something similar, but my first goal is to get it right in pdf format.

What's the difference between a terminology and a glossary? Currently I'm using a glossary because, based on the research I did, that's the most full featured way to make a set of definitions for the user to reference back to throughout the paper.

Thanks again for all the help you've given me so far, I really appreciate it.

[xephon]

A terminology is not something like a chapter which is meant to be used in a document. It is a reflection of the concepts and terms you use in your organization, including unwanted synonyms and covering multiple languages.

[clarkbrendan]

To be honest, I still don't understand the difference. As far as I can tell, a definition list, glossary, and terminology are all meant to accomplish about the same thing, providing a consolidated list of the terms and definitions used throughout some document (be that a website, pdf, or otherwise). If you can actually provide a list of concrete differences (on the theoretical level) between the three and perhaps a couple examples as to how they should be used differently I'd appreciate it, but right now they're equivalent in my head.

With that being said, I'm still trying to figure out how the heck to go about doing this. Clearly glossentry has all of the information stored in it that I want, but I still can't figure out how to compile individual glossentries into a single definitions section that looks nice. From what I can tell there's a glosslist element in bookmaps, but there's no good equivalent to them in regular maps. Perhaps is there some way I can retrofit glosslists as an element inside of regular maps? I kinda feel like that defeats the point of standardizing my documentation using dita though...

I'm kinda frustrated by this point, it's not your guys' fault, but the lack of good information on how to do stuff that "supposedly" dita is designed for (making good, clean, modular user documentation with flexible formatting) makes me think dita may be a badly designed tool. If this isn't the case, then I'm really surprised how bad the end-user documentation is for a tool made by people who make user documentation for a living. What's so frustrating is that it feels like with a little bit of polishing around the edges and maybe a little restructuring this tool could be incredibly user-friendly and useful to large companies and indie developers alike.

[Radu]

Linking for completeness to Brendan's post on Stack Overflow:
https://stackoverflow.com/questions/782 ... using-dita

[clarkbrendan]

Okay, so I have figured out how to fix my linking problem and my displaying problem. As stated previously, for linking, the problem was the default is "no" for glossentries, I needed to change that to something else, I chose "normal".

For displaying concisely it was a bit trickier, but I got some great advice from Radu on the stackexchange post detailing how the xsl handles glossentries by default. I needed to create a custom plugin with a custom xslt file that overrides how the processor formats the glossentry value. Below is the code for said formatting (I'm also changing the link color) as well as a picture of the current result.

I am still trying to figure out how to sort the glossentries as well as only display the ones being referenced, but I'm still having a very difficult time doing that. I tried following the guide by Radu seen here: https://blog.oxygenxml.com/topics/sort_ ... tries.html, but when I add the xslt file and change it from "glossarylist | topicgroup[@outputclass='glossarylist']" to "topichead[@outputclass='myGlossary']", the entries just disappear and I haven't found a way to prevent this. I'd like to continue working on this and would appreciate any feedback you guys can give, but for now I'm going to call it good in regards to this piece of documentation.

Primary formatting:

image.png (64.7 KiB) Viewed 278 times

Secondary formatting:

image.png (31.99 KiB) Viewed 278 times

image.png (11.35 KiB) Viewed 278 times

Final Result:

image.png (16.74 KiB) Viewed 278 times

[Radu]

Hi,
I'm glad you made good progress!
So just to understand, if you use a <topicgroup> with a specific outputclass to group these topicrefs, the XSLT template you wrote properly sorts them but if you use a <topichead> with a similar outputclass, the XSLT template matches it but no longer presents the glossentries in the PDF?
Regards,
Radu

[clarkbrendan]

Okay, you're right, I really should have tested the base case first as that's what the xslt was originally designed for.

To clarify: When using the original xsl with a <topicgroup> with the outputclass "glossarylist", the entryies show up (albeit with the abbreviated-form not working), but they do not sort themselves. With the change I made and using <topichead> with the outputclass "myGlossary", the entries don't show up at all.

I think both of these are caused by the first part working:

image.png (9.62 KiB) Viewed 244 times

but the second part not matching correctly (evidenced by the fact that I get the same result regardless of the outputclass I use in both cases)

image.png (54.42 KiB) Viewed 244 times

I'm not sure why this is and I'm not familiar enough with the xslt matching syntax to try to fix it (didn't find any examples of using @outputclass in a match like this within the primary xsl-fo files of the pdf2 plugin), any idea as to what I should try or where I can look to become more familiar with this kind of matching syntax?

Also, if you wouldn't mind Radu, I'd appreciate a "brief" explanation of how this solution is supposed to work. I have a vague idea of how the second part works, but I don't understand at all what the following piece does:

image.png (9.62 KiB) Viewed 244 times