Home Forums DITA and XMetaL Discussion Can you pull a PDF file into a bookmap? Reply To: Can you pull a PDF file into a bookmap?

Derek Read

Reply to: Can you pull a PDF file into a bookmap?

RenderX XEP (used by XMetaL Author Enhanced PDF via RenderX XEP deliverable) supports the embedding of PDFs within other PDFs, so yes, this would be possible. As it works right now if you create a topic, embed an and reference a PDF file RenderX will attempt to embed the PDF inside the PDF that it is generating. There are limitations to this as XMetaL Author Enterprise and the DITA Open Toolkit are not really designed with this in mind, but you can get around those issues. To see this in action you can do the following:

1. Save your PDF to an empty folder (example: C:EmbedTesttest.pdf)
2. Create a DITA topic in the same folder:

 PDF Embedding Test

3. Generate output from the topic using the deliverable “XMetaL Enhanced PDF via RenderX XEP”. At this point if you open the output PDF you will notice that the embedded PDF image is not there. This is because by default the DITA OT only copies certain image types (certain file extensions like JPG and GIF) into the right place for RenderX to locate them when it goes to embed them in the output PDF.
4. Manually copy the file “test.pdf” into the following folder:
5. Generate output again, using “XMetaL Enhanced PDF via RenderX XEP”. This time the PDF image will be embedded inside your output PDF. I'm attaching both the test.pdf and my for reference.

You will note several issues with the above test because of the way the DITA OT currently works:
1. The image is included inside a topic and so appears on a page along with header and footer (exactly what you don't want).
2. The image has been scaled in order to fit on the page (“actual size” is 8.5 x 11inches in PDF land, but I have scaled it to 340x440px). RenderX and the DITA OT do not automatically scale images that do not fit inside a particular container block (this is in the XSL-FO). There are strategies for that, but in your case this would likely not be needed if your pages are all exactly the right size.
3. The DITA OT doesn't automatically copy the PDF image into the right place for RenderX to locate it.

So, to get what you are looking for would require customization work to be done to the DITA Open Toolkit. You may also need to decide how you wish to code the DITA map or specially coded topics that will contain references to these PDF files (a DITA specialization might make coding any XSLT easier but creating the specialized DTD would in itself add more work). These decisions would drive the changes needed in the XSLT that generates the XSL-FO used by RenderX to generate the PDF output (or the latter might drive the former). You might be able to get away with markup similar to what I have above, perhaps by adding a special identifier that can be used by the XSLT so that it knows this is a special topic and to generate the right XSL-FO for it. Perhaps something like this:


Alternatively (as you suggest) you might alter the code that handles bookmap files, so that you might have something like this in your bookmap:

These things would likely be a significant amount of work and a service one of our partners may be able to help with if you don't have anyone in house that is familiar with making changes to the DITA OT. Or you might be lucky and someone else may have already done something like this that they are willing to share. Two possible other locations for this type of information:

Also note that in order to view the PDF inline while editing in XMetaL Author Enterprise would require customization of the editor itself. This would require some scripting work and a configuration changes but it can be done. Though I suspect it may not be a requirement in your case and that generating output is higher priority. This is also something our partners can generally help with.