Best practices for vector image (SVG) processing

[Stefan Eike]

Hi,

I'm trying to consolidate recommendations for creating, exporting and using vector images, especially SVGs, in a cross-media publishing DITA-OT environment. Most important output channels (for me) are:

• XSL:FO (FOP)
• oXygen Webhelp

A best practice is like looking for a needle in a haystack. Because the DITA-OT does not support popular proprietary formats like AI (as for example paligo.net does), the best way for using vector images is simply using SVGs. But handling SVGs in a DITA environment is a pain. Sometimes the SVG is not correctly rendered in oXygen, sometimes the scaling (e.g. scalefit) does not work in PDF as expected (but it works for PNG)...

Probably many companies dealing with SVG and the DITA-OT have the same issues. Therefore I'd like to learn from you and contribute the best-practices, e.g., to Leighs DITA for Print book, as a DITA-OT docs PR or as a blog post.

My suggestion is to share experiences and style guide rules, e.g. export settings for Adobe Illustrator, XSL scripts to fix common SVG errors, SVG elements and structures that should be avoided, XSL attribute sets for FOP and other renderers...

How do you handle vector images? Or do you even avoid vector formats, use EPS with auto-conversion, ...? Please tell your story.

[Stefan Eike]

I think I've figured out the solution:

You MUST HAVE @width and @height set on the root <svg> element. If not, scaling does not work properly.

You SHALL remove any top-level bounding boxes. You can identify Adobe Illustrator bounding boxes by @id.

<g id="boundingbox"> <rect class="st0" width="331.7" height="283.5"/></g>

You can identify these structures with Schematron. Please find a validation schema below for reference. You can mass-validate SVGs by selecting them in the Project view in Oxygen.

<?xml version="1.0" encoding="UTF-8"?>
<sch:schema
    xmlns:sch="http://purl.oclc.org/dsdl/schematron"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process"
    xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    queryBinding="xslt2">
   
    <sch:ns uri="http://www.w3.org/2000/svg" prefix="svg"/>
   
    <sch:title>Schematron validation</sch:title>
    <sch:p>This helps to find common errors that might cause trouble when publishing SVG images with Apache FOP.</sch:p>
   
    <sch:pattern>
        <sch:rule context="svg:svg" role="error">
            <sch:assert test="@width or @height">
                The attributes <sch:emph>@width</sch:emph> or <sch:emph>@height</sch:emph> <sch:emph>MUST</sch:emph> be set for scaling. Open in Inkscape and resize document to image CTRL + A and SHIFT + CTRL + P.
            </sch:assert>
        </sch:rule>
    </sch:pattern>
   
    <sch:pattern>
        <sch:rule context="svg:svg/svg:g" role="warning">
            <sch:report test="@id = 'boundingbox'" sqf:fix="remove-top-level-bounding-box">
                Remove top-level bounding boxes. They might cause a white border in the output
            </sch:report>
            <sqf:fix id="remove-top-level-bounding-box">
                <sqf:description>
                    <sqf:title>Remove bounding box</sqf:title>
                </sqf:description>
                <sqf:delete match="."/>
            </sqf:fix>
        </sch:rule>
    </sch:pattern>
   
</sch:schema>

[Stefan Eike]

As recommended by Radu, we can also validate images from map level.

    <sch:pattern id="svg-check">
        <sch:rule context="*[contains(@class, ' map/topicref ')][@processing-role = 'resource-only'][contains(@href, '.svg')]">
            <sch:let name="file" value="@href"/>
            <sch:assert test="document($file, .)/svg:svg[1]/@width or document($file, .)/svg:svg[1]/@height" role="error">
                <sch:value-of select="$file"/>

                The attributes <sch:emph>@width</sch:emph> or <sch:emph>@height</sch:emph> <sch:emph>MUST</sch:emph> be set for scaling.
                Open in Inkscape and resize document to image CTRL + A and SHIFT + CTRL + P.
            </sch:assert>

            <sch:report test="document($file, .)/svg:svg[1]/svg:g/@id = 'boundingbox'" role="warning">

                Remove top-level bounding boxes. They might cause a white border in the output
            </sch:report>

        </sch:rule>
    </sch:pattern>