Syntax diagrams in SVG

Post here questions and problems related to editing and publishing DITA content.
Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Syntax diagrams in SVG

Post by Graham Hannington »

Dear Oxygen developers,

I spend much of my time developing IBM-brand documentation. In that doc ecosystem, syntax diagrams in DITA now get formatted to SVG.

However, I've recently started working on a non-IBM-brand product, outside the IBM doc ecosystem.

I've just tried formatting a DITA topic with a syntax diagram using the DITA OT HTML5 transformation scenario in Oxygen XML Author 22.1. The diagram is output as "brackets'n'braces" text.

Have you considered integrating "syntax diagrams in SVG" with the Oxygen distribution?
Radu
Posts: 9018
Joined: Fri Jul 09, 2004 5:18 pm

Re: Syntax diagrams in SVG

Post by Radu »

Hi Graham,

Right, Robert Anderson presented this project at one of our DITA OT Day meetups about 3 years ago:

https://www.youtube.com/watch?v=Q-Bc2nu7mcM

I considered adding these plugins to Oxygen's DITA OT "plugins" folder but it's not been something asked for by our users, you are probably the first one to ask for this. There are lots of DITA OT plugins and we try to include the ones which seem to be useful for a significant number of clients.
Of course, you can install the plugins yourself in the DITA OT bundled with Oxygen, or copy Oxygen's DITA OT separately and install them in that separate DITA OT folder:

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

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Syntax diagrams in SVG

Post by Graham Hannington »

I was going to reply by attaching an example SVG file (with file extension .svg) generated by a DITA-OT instance to which I'd added that plugin, and then, hopefully, refer to the URL of that attachment (if I could figure it out) in an img tag in the reply, but I hit a snag: attempting to attach the .svg file resulted in the following error from this forum website:
Invalid file extension: txc_syntax_summary_detail_auxiliary.svg
Nits, really. Still, for what it's worth:
  • I'd like to be able to attach a .svg file to a forum post
  • I'd like to be able to present that .svg in a forum post via an img tag
Radu
Posts: 9018
Joined: Fri Jul 09, 2004 5:18 pm

Re: Syntax diagrams in SVG

Post by Radu »

Hi Graham,

Thanks for the request, I added an internal issue for our web site devs.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
AndreaB
Posts: 1
Joined: Fri Apr 22, 2022 10:04 am

Re: Syntax diagrams in SVG

Post by AndreaB »

Hello Radu,
I would like to join this request. We recently acquired an IBM product with all the associated documentation, which contain plenty of syntax diagrams, We have installed the plugins locally in the Dita OT folder, but can't get them to work. I know that my Australian collegaues, who are working on non-IBM products, face the same problem. Maybe you could reconsider adding the plugin to Oxygen?
Regards Andrea
alex_jitianu
Posts: 1008
Joined: Wed Nov 16, 2005 11:11 am

Re: Syntax diagrams in SVG

Post by alex_jitianu »

Hi,

I've added your vote to include the plugin and increased the issue's priority.
I've installed the plugin myself and it seemed to work just fine. I'm writing the steps I took here and perhaps you can draw inspiration from it:
1. I've downloaded the last: from https://github.com/robander/svg-syntaxd ... s/v2.0.zip and unzipped it.
2. I've went to {oxygenInstallDir}\frameworks\dita\DITA-OT3.x\plugins (if you are using an external DITA-OT, you should copy it there instead) and copied in it the following folder from within the archive (basically all the folders from within the archive root folder):
com.ibm.ditatools.svg-diagrams
com.moldflow.dita.plus-allhtml-svgobject
com.moldflow.dita.plus-allhtml-syntaxdiagram
com.moldflow.dita.plus-allhtml-syntaxdiagram-svgobject
com.moldflow.dita.plus-html-topics-twopass
com.moldflow.dita.svgobject
com.moldflow.dita.syntaxdiagram.consolidated
com.moldflow.dita.syntaxdiagram2svg
3. I've started Oxygen, opened a map in the DITA Maps Manager and run the Run DITA-OT Integrator transformation scenario.
4. I've pasted inside a topic:

Code: Select all

<syntaxdiagram>
  <title>CopyFile</title>
  <groupseq><kwd>COPYF</kwd></groupseq>
  <groupcomp><var>input-filename</var><kwd>*INFILE</kwd></groupcomp>
  <groupseq><var>output-filename</var><kwd>*OUTFILE</kwd></groupseq>
  <groupchoice> <var>input-filename</var> <kwd>*INFILE</kwd></groupchoice>
  <groupchoice> <var>output-filename</var> <kwd>*OUTFILE</kwd></groupchoice>
</syntaxdiagram>
5. I've published the map to HTML5 and the SVG was generated.

I you still don't succeed in making the plugin work, I suggest opening an issue on the plugins GitHub project.

Best regards,
Alex
Graham Hannington
Posts: 48
Joined: Mon Jun 13, 2016 11:23 am

Re: Syntax diagrams in SVG

Post by Graham Hannington »

I've published the map to HTML5 and the SVG was generated
Works for me, too!

About the output, though...

I run the following command from a Windows command prompt, in the directory containing the input syntax.dita file, using DITA-OT (3.7.2) with the svg-syntaxdiagrams (2.0) plugins to build html5:

Code: Select all

c:\tools\dita-ot-3.7.2\bin\dita --input=syntax.dita --format=html5 --output=out
This produces an HTML file in the out folder containing <object> elements that refer to .svg files in the out\svgobject folder.

All good so far.

However: I've seen HTML files, built by someone else, that contain these SVG syntax diagrams inline in the HTML; that is, the HTML contains the <svg> element itself, rather than an <object> element that refers to an external .svg file.

I don't know how to reproduce that behavior: that is, how to instruct DITA-OT (with those plugins) to include the SVG syntax diagrams inline in the HTML.

I'll ask the creators of those HTML files how they did that, but there's a chance they might not know, so I thought I'd ask here, too, because I need to know the answer soon.

Furthermore: the inline SVG that I've seen in those other HTML files is not identical to the SVG in the external .svg files that I get.

For example, the inline <svg> elements lack the width and height attributes that are in the external .svg files that I get. That's a problem, because it means that the inline SVG scales with its container; which, in this particular context, is not desirable: I don't want the syntax diagrams to dynamically scale.

Does anyone know how the SVG gets inlined, as opposed to the <object>-tags-that-refer-to-external-svg-files that I get?
Last edited by Graham Hannington on Wed Aug 24, 2022 12:09 pm, edited 1 time in total.
Post Reply