Suggestion: use value of id attribute of <syntaxdiagram> element as the SVG file name

[GrahamHannington]

Currently, HTML5 output generates SVG files with names such as _d47e18.svg.

Instead, I would like the SVG file names to match, or at least contain, the value of the id attribute of the <syntaxdiagram> element.

For example, the following DITA:

<syntaxdiagram id="syntax-cmd-a">

would generate an SVG file named syntax-cmd-a.svg (if necessary, prepended or appended with some additional string—even that original generated file name—to ensure uniqueness).

Why?

My particular use case: to build PDF and HTML, I use a proprietary inhouse documentation build tool that is currently based on a backlevel version of DITA OT and the svg-syntaxdiagrams plugins. That tool has some issues generating syntax diagrams. For reasons not relevant to this issue, I cannot, at least in the short term, upgrade that tool myself.

As a (hopefully, temporary) workaround, I am bypassing the syntax diagram processing in that tool: I use the latest DITA OT and svg-syntaxdiagrams to generate SVG files from <syntaxdiagram> elements. I then include those SVG files via <image> elements for use with the inhouse documentation build tool.

This works. It would just be nicer for me if the SVG files matched (or contained) the id attribute value of the original element.

[GrahamHannington]

While investigating this workaround, I discovered a nit in the existing code.

I used an <image> element to include an SVG file (built using the latest svg-syntaxdiagrams plugins) in a DITA topic, then I used DITA OT (3.5.2) to build a PDF.

In the context of that PDF, the SVG "fell back" all the way to Helvetica ("base" PDF font). Turns out, Helvetica is wider than fonts listed earlier in that font-family list: the text in the syntax diagram overran the lines before and after.

[GrahamHannington]

Can anyone offer me guidance on what to change in the source to achieve this (use id as .svg file name)?

[robander]

I believe that this section is what determines the file name, but it's been a long time since I've been in there so it's possible the same change is needed in more than one spot: https://github.com/robander/svg-syntaxdiagrams/blob/master/com.ibm.ditatools.svg-diagrams/xsl/stage1-svgobject-ddita.xsl#L70

Offhand, I'm not sure what sort of conflicts you might run into if you end up with duplicate IDs on diagrams -- the generated portion of the file name was set up to avoid that issue. If the syntax using id="syntax-cmd-a" resulted in just syntax-cmd-a.svg then you'd definitely need extra logic to handle conflicts.

Given the as-is nature of the code, I don't expect to be making functional changes like this, but hopefully that spot above is enough get you what you need.

[GrahamHannington]

Belated thanks for the pointer! Yes, that was the spot. 👍

I've replaced the definition of the external-svg-name variable with this:

    <xsl:variable name="external-svg-name">
      <xsl:variable name="syntaxdiagram-id">
        <xsl:value-of select="ancestor-or-self::*[contains(@class,' pr-d/syntaxdiagram ')]/@id"/>
      </xsl:variable>
      <xsl:value-of select="concat(translate(encode-for-uri($syntaxdiagram-id), '%', ''), '_', generate-id(.))"/>
    </xsl:variable>

I'm not gonna pretend this is anything other than what it is: a quick-and-ugly hack to get what I want: the ID attribute of the <syntaxdiagram> element in the external SVG file name.

For example, if the DITA source is:

<syntaxdiagram id="syntax-abend">

then the SVG file name is:

syntax-abend_d40e1005.svg

If there's no ID attribute, then the file name is simply:

_d40e1005.svg

I acknowledge that this is an idiosyncratic change for my specific use case. I'm not going to waste anyone's time with a PR. 🙂