DITA Publishing - Glossary & References

davdup
Posts: 17
Joined: Wed May 29, 2019 5:43 pm

DITA Publishing - Glossary & References

Post by davdup » Mon Jun 03, 2019 10:35 am

Hi,
I'm quite new to DITA publishing, as we used to publish using DocBook5 for our technical documents. I want further investigate DITA publishing mainly due to the powerfull Responsive WebHelp and PDF (via CSS publishing). And I have two basic - but very important for us - things that I would like to do with DITA:
1- build an "automated" glossary based on terms that I would call inside my DITA content, anywhere it appears. For example each time I have the accronym "ROV" inside my DITA content, I would like to insert something like

Code: Select all

<term>ROV</term>
, and in the final output (WebHelp or PDF) this would point to a Glossary section, where the user will find "ROV: Remotely Operated Vehicle". Ideally in the Webhelp content, a popover <div> would appear when the user mouseover the term, displaying the definition... Also I would love that the glossary build itself based on the terms that are present on the DITA content (and only these terms), among a complete/general glossary that contains all the terms that we may have to use on our documents... My feeling is that I need to use the <glossary> document type, and benefits from the various values defined in each <glossentry>, but I would really like to have something as simple and automated as possible. I do not want to have to manually select each term which is used in my DITA content to build the gloassary (like in the Flowers example of your distribution). Is it possible?
2- build a "Reference documents" section where we would have entries like this:

Code: Select all

[1] AO-111-123456............ Document Title #1
[2] AO-111-34566778............ Document Title #2
... 
and refer to these lines inside the DITA content with xref that would display either the

Code: Select all

[1]
, or the title or both. Is there a way to achieve this with DITA (I'm sure there is! :))
Thanks for your help!
Regards

David

Radu
Posts: 6329
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA Publishing - Glossary & References

Post by Radu » Tue Jun 04, 2019 10:58 am

Hi David,

Here's how people using DITA with abbreviated forms usually work:

https://www.oxygenxml.com/dita/1.3/spec ... -form.html

1) You define a glossentry DITA topic file containing the abbreviated definition and explanation:

Code: Select all

<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>
2) You refer to that topic in your main DITA Map and assign a key definition to it like:

Code: Select all

<glossref keys="abs" href="antilock.dita"/>
3) In all places where you want to refer to the abbreviation you insert the "abbreviated-form" element like this:

Code: Select all

<abbreviated-form keyref="abs"/>
We do not have any other functionality.

About the second question, when you use a DITA "xref" to refer to a DITA topic, and the xref element is empty, it does not have any text content inside it, automatically the title of the target topic will be presented on it. Otherwise, if you set custom text inside the xref, that text will be presented. Again, this is the current functionality available.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

davdup
Posts: 17
Joined: Wed May 29, 2019 5:43 pm

Re: DITA Publishing - Glossary & References

Post by davdup » Tue Jun 04, 2019 11:53 am

Thank you very much for your answer!
In fact I was hoping something more "practical" and automated was possible...
We currently have something in place with Docbook5 which works really fine: we have an abbreviation.xml file which contains all our glossary entries, with unique xmlIDs, and when we write a new document we simply insert

Code: Select all

<xi:include href="abbreviations.xml" xpointer="SCR"/>
wherever we have the "SCR" abbreviation.
At the beginning of the Docbook file, we insert the xml files as references like this:

Code: Select all

<section>
      <title>Definitions &amp; Abbreviations</title>
      <xi:include href="abbreviations.xml" xpointer="element(/1)"/>
</section>
And in the transformation process, the complete docbook file is scanned and only the abbreviations that are used are displayed in this section.
Same for the references (we have to deal with thousands of reference docs). We have a "library" docbook file (basically a table where each row is a document, with a unique doc number, xmlID, and attributes which define where this document is referred to in our documents). At the beginning of the transformation for one of our report (with its own unique document number), this huge table is stripped from all the documents that do not need to be displayed in the references section, and a table is built, giving each one a sequential number ([1], [2], etc...) a unique xmlID that allows to refer to it in the document...
In short: the process is as automated as possible, and we only have to maintain a few files (abbreviations, definitions, document library) that are used in ALL of our documents.
In fact my main reason for considering a switch to DITA is the availability of the DITA to responsive WebHelp and DITA to PDF based on CSS which are much more attractive and modern than what is available with DocBook file...
Perhaps you would have some suggestion to have a "modern" output available for DocBook? or to develop some equivalent solution with DITA?
Thanks a lot for your help!
Regards

David

Radu
Posts: 6329
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA Publishing - Glossary & References

Post by Radu » Wed Jun 05, 2019 8:10 am

Hi David,

What you did as a customization for DocBook can probably (with some effort) be also done for DITA publishing.
At the last DITA North America conference there was this presentation:

https://www.slideshare.net/drmacro/defi ... s-for-free

Along with some support materials they provided:

https://github.com/drmacro/dita-glossar ... publishing
https://github.com/wbrisett/markentries
https://github.com/wbrisett/excel2glossary

but you probably need to become familiar with DITA publishing, with its plugin based architecture and try to re-implement this custom solution in DITA.

About this remark:
In fact my main reason for considering a switch to DITA is the availability of the DITA to responsive WebHelp and DITA to PDF based on CSS which are much more attractive and modern than what is available with DocBook file...
Perhaps you would have some suggestion to have a "modern" output available for DocBook? or to develop some equivalent solution with DITA?
We have an internal issue to provide DocBook to WebHelp responsive but looking at how things are right now, at the number of people working for the DITA to WebHelp output and their current objectives, we will probably not provide DocBook to Responsize WebHelp in the short to medium term. Also looking at the fact that DocBook is starting to be less used and is being replaced with DITA in many companies again does this may not justify the amount of work and the maintenance over many years of a DocBook to WebHelp Responsive solution.

About DocBook to PDF using CSS, indeed for DITA we have created ourselves the set of CSSs used for printing (which have lots of content in common with the CSSs used for visual editing).
We already have CSSs used for editing DocBook in the Author visual editing mode, but they probably need to be enhanced with print-specific instructions. I will add an internal issue for this.
Our Chemistry user's guide contains various resources about styling tables, creating table of contents so it is possible for the current DocBook CSSs to be enhanced to be used also with the Chemistry CSS-based processor:

https://www.oxygenxml.com/doc/versions/ ... a_toc.html

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

davdup
Posts: 17
Joined: Wed May 29, 2019 5:43 pm

Re: DITA Publishing - Glossary & References

Post by davdup » Wed Jun 05, 2019 10:33 am

Hi Radu,
Thanks a lot for your answer! This material is indeed very interesting, but a little bit out of reach for my beginner's skills!! :(
I will have a look anyway and try to understand as much as I can...
I should have added that the switch to DITA is also motivated - as you mention - by the lack of activity, development and resources on the DocBook side. We should probably have moved to DITA directly in the first place a few years ago when we decided to move to a structured XML authoring solution for our document, but it was not the case unfortunately.

By the way, I found a solution yesterday to "filter" the content of one DITA file (my reference document list/table) using the profiling (with audience, otherprops, platform, product or props attributes) This already provides a good solution. And I have a new (probably dumb!) question: is it possible to filter a DITA file directly from a DITAMap or BookMap (meaning for example calling the same DITA file several times in a single Map, with different filters, resulting in different sections in the final output)? The profinling is made on the whole Map at the processing stage, but is there a way to filter directly the topic content?

Best regards

David

Radu
Posts: 6329
Joined: Fri Jul 09, 2004 5:18 pm

Re: DITA Publishing - Glossary & References

Post by Radu » Wed Jun 05, 2019 12:17 pm

Hi David,
is it possible to filter a DITA file directly from a DITAMap or BookMap (meaning for example calling the same DITA file several times in a single Map, with different filters, resulting in different sections in the final output)? The profinling is made on the whole Map at the processing stage, but is there a way to filter directly the topic content?
There is a DITA feature called branch filtering which allows referring to DITA topics and maps multiple times in a DITA Map but with different filters:

https://blog.oxygenxml.com/2015/09/dita ... -next.html
https://www.oxygenxml.com/demo/DITA_13.html

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

davdup
Posts: 17
Joined: Wed May 29, 2019 5:43 pm

Re: DITA Publishing - Glossary & References

Post by davdup » Wed Jun 05, 2019 12:36 pm

That's great! Thank you very much!

Post Reply