Using SVG images with DITA OT 3.0.x
615 views
Skip to first unread message
David Lange
May 13, 2018, 7:21:04 AM5/13/18
to DITA-OT Users
Hi DITA Fans,
we are using XML-FO heavily throughout our software development for generating PDFs (Apache FOP 2.2) for technical documentations. In the recent days we have considered to evaluate DITA as a next logical step to enable other documentation Format Exports such as HTML5. Many initial tests have been passed successfully, however we are struggeling with the SVG part. We have plenty of external SVG Images that need to be references from dita topics. Our environment currently is Windows 7 (10 soon) with DITA Open Toolkit 3.0.4. installed. The following is the test topic we are using:
<topic id="svg-test-topic">
<title>SVG Test Topic</title>
<body>
<p>SVG with svgref:</p>
<fig>
<title>Figure Caption</title>
<svg-container>
<svgref href="media/svg/apple.svg" format="svg"/>
</svg-container>
</fig>
</body>
</topic>When using the format pdf2 the temporary directory contains the topic.fo without the Image being references or inlined. Instead it states empty fo:blocks:
<fo:block space-after="0.6em"
space-before="0.6em"
text-indent="0em">SVG with svgref:</fo:block>
<fo:block id="d76e11">
<fo:block font-size="10pt"
font-weight="bold"
keep-with-previous.within-page="always"
space-after="10pt"
space-before="5pt"
line-height-shift-adjustment="disregard-shifts"
font-family="Helvetica, Arial Unicode MS, Tahoma, Batang, SimSun">Figure 1: Figure Caption</fo:block>
</fo:block>
</fo:block>In a final setup we would like to use the svgref element together with the @keyref attribute.After a bit of investigating throughout the stylesheets within the DITA Open Toolkit fileset it seems that there is no rule to transfrom the svgref element.
Can anyone help me to understand the suggested way to incorporate SVG files within our DITA files? Is there any additional plugin required? Thanks a lot.
Christophe M.
May 13, 2018, 11:04:22 AM5/13/18
to David Lange, DITA-OT Users
Hi David,
If the question is how to refer to svg files in topics in general, use <image> instead of <svg-container>.
Cheers,
Christophe
Sent from Mail for Windows 10
--
You received this message because you are subscribed to the Google Groups "DITA-OT Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-user...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
David Lange
May 13, 2018, 1:15:40 PM5/13/18
to DITA-OT Users
Hi Christophe,
thanks for you reply. I know <image> can handle svg graphics and I use it also for now.
However DITA 1.3 states <svg-container> in its documentation (https://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/langRef/technicalContent/svg-container.html) and therefore I thought it can be used together with the DITA Open Toolkit. In fact I could not find any limitation saying that for svg graphics <image> shall be used instead of <svg-container>.
We are dealing with more than 10000 pages of PDF documentation including several hundreds of SVG graphics. This circumstance requires highly optimized PDF output. When using <image> the XML-FO will include the file as a <fo:external-graphic>. I am not quite sure if this will have negative effect on the PDF navigation speed (scrolling, searching, etc.). Therefore we embed the graphic using <fo:instream-foreign-object> instead. When speaking DITA <svg-container> seem to be the matching part here.
Can you point out the differences between <image> and <svg-container> and if it supported by DITA Open Toolkit?
mrob
May 13, 2018, 7:40:12 PM5/13/18
to DITA-OT Users
Hi David,
I have used SVG files with DITA-OT a few times. It works fine with the <image> tag and the contents of the SVG file are embedded directly into the pdf file as drawing primitives. I gather that DITA-OT delegates the heavy lifting to FOP, which in turn delegates the SVG-to-PDF conversion to a Batik transcoder.
From your dita test file, it looks to me like DITA-OT doesn't support <svg-container>. I understand that you want optimal performance, but even if support for <svg-container> were added it might not make any significant difference performance-wise. For SVG, the FO output from DITA-OT would use either <fo:external-graphic> or <fo:instream-foreign-object>. Since it looks like FOP itself delegates the conversion, my suspicion is that there probably isn't much difference between those two, as the question is probably just where Batik looks for the source SVG before transcoding, i.e., either embedded "instream" or in an external file. Again, the result will be embedded in the resulting pdf file.
If you wanted to test this before diving in with DITA, I'd say find the document in your set that includes the largest number of SVG files, and extend your test file to embed all of them, interspersed with paragraphs of Lorem Ipsum text. Then run it through DITA-OT and see if the resulting PDF is acceptable. The formatting won't be what you want, but it would be an adequate test. It shouldn't take more than an hour to do this with a lot of global find-replace in a text editor.
In my experience, the main effort with DITA-OT is building a plug-in and getting all the formatting details right. For this, I have used the book DITA for Print and come to online forums when I got in trouble. The Yahoo Groups DITA forum is more active than this one.
HTH
I have used SVG files with DITA-OT a few times. It works fine with the <image> tag and the contents of the SVG file are embedded directly into the pdf file as drawing primitives. I gather that DITA-OT delegates the heavy lifting to FOP, which in turn delegates the SVG-to-PDF conversion to a Batik transcoder.
From your dita test file, it looks to me like DITA-OT doesn't support <svg-container>. I understand that you want optimal performance, but even if support for <svg-container> were added it might not make any significant difference performance-wise. For SVG, the FO output from DITA-OT would use either <fo:external-graphic> or <fo:instream-foreign-object>. Since it looks like FOP itself delegates the conversion, my suspicion is that there probably isn't much difference between those two, as the question is probably just where Batik looks for the source SVG before transcoding, i.e., either embedded "instream" or in an external file. Again, the result will be embedded in the resulting pdf file.
If you wanted to test this before diving in with DITA, I'd say find the document in your set that includes the largest number of SVG files, and extend your test file to embed all of them, interspersed with paragraphs of Lorem Ipsum text. Then run it through DITA-OT and see if the resulting PDF is acceptable. The formatting won't be what you want, but it would be an adequate test. It shouldn't take more than an hour to do this with a lot of global find-replace in a text editor.
In my experience, the main effort with DITA-OT is building a plug-in and getting all the formatting details right. For this, I have used the book DITA for Print and come to online forums when I got in trouble. The Yahoo Groups DITA forum is more active than this one.
HTH
Radu Coravu
May 14, 2018, 3:07:03 AM5/14/18
to mrob, DITA-OT Users
Hi,
The DITA OT issue for supporting svg-container is registered here:
https://github.com/dita-ot/dita-ot/issues/1123
Eliot Kimber has a set of plugins which add support for svg-container (among other things which may not be necessary anymore):
https://github.com/dita-community/dita13-dita-ot-1.x-support
https://github.com/dita-community/dita13-dita-ot-1.x-support
For the PDF output this XSLT stylesheet handles the svg-container:
https://github.com/dita-community/dita13-dita-ot-1.x-support/blob/master/org.dita-community.dita13.pdf/xsl/svg-d2fo.xsl
https://github.com/dita-community/dita13-dita-ot-1.x-support/blob/master/org.dita-community.dita13.pdf/xsl/svg-d2fo.xsl
--
You received this message because you are subscribed to the Google Groups "DITA-OT Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-users+unsubscribe@googlegroups.com.
David Lange
May 14, 2018, 1:28:47 PM5/14/18
to DITA-OT Users
Hi,
thanks for all the good advices. We will move ahead with the <image> tag. For our full software build cascade for sure this will take a few days/weeks for immplementation. Afterwards I will see the performance outcome and if interested I can provide you with detailed results. Most likely that further fine-tuning will become a need.
Thanks,
David
To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-user...@googlegroups.com.
David Lange
May 15, 2018, 11:18:15 AM5/15/18
to DITA-OT Users
Hi again,
just a quick addition to the SVG question. The <image> tag works fine, however the figure is not "searchable" within the HTML output. With <object> this would be a suitable alternative, however this element does not suppoert @keyref with DITA-OT 3.0.4.:
Line 13:Attribute "keyref" must be declared for element type "object".I am a bit wondering since the release notes are saying https://github.com/dita-ot/dita-ot/issues/1783 it is supported. Other people seem to face the same problem (https://github.com/dita-ot/dita-ot/issues/2620). Does anyone has an update or workaround on this?
Thanks a lot!
mrob
May 16, 2018, 1:06:37 AM5/16/18
to DITA-OT Users
I'm not sure what you mean by "searchable". The usual approach would be something like this:
<fig frame="none">
<title>The Handshake</title>
<image href="handshake.jpg" placement="break">
<alt>The Handshake</alt>
</image>
</fig>
In your case, it would be an SVG file, of course.
Could you post the DITA you're trying to get working for this?
Radu Coravu
May 16, 2018, 1:07:56 AM5/16/18
to David Lange, DITA-OT Users
Hi David,
According to the DITA 1.3 standard the DITA object element does not have the @keyref attribute:
https://www.oxygenxml.com/dita/1.3/specs/langRef/base/object.html
https://www.oxygenxml.com/dita/1.3/specs/langRef/base/object.html
so you should use "@datakeyref" instead (which suffers from the issue I added some time ago
(https://github.com/dita-ot/dita-ot/issues/2620)) or use the "@data" attribute to directly refer to the resource.
Or better yet, create a DITA HTML output customization plugin which overrides the image processing and if the image @href ends with ".svg" outputs an HTML object element.
For example for XHTML-based outputs the XSLT template "DITA-OT/plugins/org.dita.xhtml/xsl/xslhtml/dita2htmlImpl.xsl" has a template named ""topic-image"" which you can override in your own HTML plugin customization.
There is a DITA OT issue I added some time ago for this:
https://github.com/dita-ot/dita-ot/issues/2496
https://github.com/dita-ot/dita-ot/issues/2496
To unsubscribe from this group and stop receiving emails from it, send an email to dita-ot-users+unsubscribe@googlegroups.com.
David Lange
May 16, 2018, 1:19:06 PM5/16/18
to DITA-OT Users
Hi together,
@mrob: "searchable" means the <image> tag does not allow to find text within the svg image when using a "Ctrl+F" operation in the browser. <object> instead does support this.
@Radu:
I know the issues you have mentioned and I can confirm the behavior described there. Until native support in DITA-OT is available, I will go for the plugin solution. Thanks a lot!
Regards,
David
Reply all
Reply to author
Forward
0 new messages