Adding one .dita file to .ditamap changes transformation of whole document?!

[mleneis]

Hello,

First post here - this may well be a stupid question but I've no idea what search strings to even use to try to solve this one.

I'm building a small PDF out of a dozen small .dita files. Each file validates and is well-formed (not definitive, I know). I have had build errors in the past, so am troubleshooting by buildng the ditamap up one file at a time to make sure it builds.

I've just reached a point where the ditamap builds a PDF just fine (using default DITA Map PDF predefined scenario, no customisation to transformation at all yet). As soon as I add the next file and click Apply Transformation Scenario (same process as I have been using all along), it appears to build successfully but the built PDF is a single-topic output with one of the sample files and NONE of the files in the ditamap, including the newly-added file (a build I did last week, with a different filename - I then deleted that ditamap and emptied the Recycle Bin).

It's definitely the new file - if I pull it out of the ditamap, it builds a PDF that looks as expected. I put the file back in and build, I get the PDF with none of the other topics in the ditamap, just one of the sample flower files that came with Oxygen.

The file itself is valid and I'm editing it in text mode, not seeing anything that could be referring to the sample flower file.

I'll carry on troubleshooting - recreate the .ditamap will be my next step - but was wondering if anyone's ever seen this? It seems a bizarre error to have!

[mleneis]

Update:
I built a new .ditamap from scratch. Again, all was fine for all the files before this one. In this ditamap, when I add the file that caused problems earlier, it claims to build successfully, but there isn't actually any .pdf in the location it claims to have built to.

Still troubleshooting, but it seems to be pointing to a problem in the one .dita file. I can rebuild it but am curious what I did and how to avoid it in future?

Thanks!
Mary

[Radu]

Hi Mary,

Oxygen uses the DITA Open Toolkit to publish DITA content to various output sources.

I'm building a small PDF out of a dozen small .dita files. Each file validates and is well-formed (not definitive, I know). I have had build errors in the past, so am troubleshooting by buildng the ditamap up one file at a time to make sure it builds.

One hint unrelated to your problem is to use the "Validate and Check for Completeness" action from the DITA Maps Manager view, it should be useful to detect usual linking problems in your DITA Map project.

It's definitely the new file - if I pull it out of the ditamap, it builds a PDF that looks as expected. I put the file back in and build, I get the PDF with none of the other topics in the ditamap, just one of the sample flower files that came with Oxygen.

The DITA Open Toolkit usually has trouble publishing when a topic is referenced from a folder which is outside the folder where the DITA Map is located. So as a general rule you should try to keep all referenced topics and resources in folders which are descendants of the folder where the DITA Map is located.
So this might be the case, maybe you are referencing the topic directly in the DITA Map instead of copying it to a folder which is a descendent of the folder where the DITA Map is located.

If this is not the case, maybe you can send us a small DITA Map sample at support@oxygenxml.com and we'll look into it.

You should also try to join the DITA Users List, there are a lot of DITA related discussions there every day.

Regards,
Radu

[mleneis]

Hello Radu,

Thanks for your prompt reply! Sorry I didn't mention file structure initially - all the files are in the same folder as the Ditamap, so that shouldn't be an issue. I will go try the DITA users board as you're right, I'm sure this isn't an Oxygen problem, it's my eternal nemesis the DITA OT!

Thanks,
Mary

[mleneis]

Actually, Radu, I'm not sure if it's DITA-OT or Oxygen that's the hiccup here.

I've troubleshot it down to certain image files. There are some image files that seem to be rejected by Oxygen when I Insert Image Reference. Oxygen tells me "Cannot display image (hover for details) <filepath>". When I hover for details, I get "Not enough memory to load image. The application exceeded the available memory: 622MB. To avoid stability issues, please restart the application. If the problem persists, it is recommended to increase the amount of memory available to the application."

I can't identify what's wrong with some images and not with others:

• All the files are screenshots saved as .png files;
  all are located in an Images file that's in the same directory as the dita files and ditamap;
  all files are named with lowercase letters and numbers (no spaces or other characters) ending in .png. Example of failed filenames are "edit_mc1.png" and "edit_mc2.png", but "edit_mc3.png" is fine.
  The files vary between 2KB and 86KB, although the ones that fail are never uniformly a certain size range - one that failed is 71KB, but others are 17KB, 15KB, 19KB. Nothing excessive.
  All were screenshots saved through Paint (yeah, we're high-budget here).

I seem to be identifying conclusively that the images that don't display in Oxygen are the ones that break the build. I'm not sure whether that's correlation or causation. Any ideas why? Do they contain too much blue? Too many vertical lines?

Thank you!

[Radu]

Hi Mary,

Your intuition might be correct.

PNG files are usually small on disk because they are usually very compressed (they are like an archive of the original image).
But when loaded in the memory of an application (Oxygen or the DITA-OT) the image might take a lot of memory depending on the width and height. Usually to know how much space an image will take in the internal memory (for being displayed in the Author page for example) you multiply (width * height * 4) in order to obtain the number of occupied bytes.

If you want you can send us a sample DITA project with some of those images and we'll take a look at them.

You can also try to increase the maximum internal memory available both for Oxygen:

http://www.oxygenxml.com/doc/ug-oxygen/ ... ments.html

and for the DITA Open Toolkit:

http://www.oxygenxml.com/doc/ug-oxygen/ ... anced.html

Regards,
Radu

[mleneis]

Hello again Radu! Thanks for all your help with this, I really appreciate it.

Good point about the .png file - I hadn't thought of that. I'm going through the files to see what's failed... it looks like it's mostly big-window screenshots, but sometimes smaller ones that occur later in the same document.

Interesting new twist - after having removed any broken image files from the .dita documents yesterday, I was going through them again today, and found one that must have appeared fine yesterday but is a broken image icon today. Now I get the alert "Error reading PNG metadata". The whole thing builds as expected, but ignores that image. I'm assuming that's an unrelated issue that I'll work on separately, but thought I'd mention it in case you know of any reason it's a related symptom.

I've already increased the DITA-OT memory from 256MB to 512MB, but will increase memory to Oxygen as well. (And convince my boss it's time for a splurge at Crucial!)

I'll create a small test-document and send it to you - will look to see what the best way is, via email or if you have a submission system. Sorry to be such a n00b!

Thanks,
Mary

[Radu]

Hi Mary,

You can either contact us using the support@oxygenxml.com email address or by filling out this form:

http://www.oxygenxml.com/techSupport.html

Regards,
Radu

[mleneis]

(Followup: Saw the email address in one of your previous messages, will send a small ditamap to that address.

Checked the oxygen13.2.vmoptions file and VM is already set to 700MB, which I understand is the maximum it'll take.)

[mleneis]

I think we crossed posts in the ether there! I've sent a sample to the email address. Thank you ever so much for your help!

-Mary

[Radu]

Hi Mary,

I took a look at the images and here are my findings:

All image dimensions are small so no out of memory problem should arise from this.
Both Oxygen and the DITA Open Toolkit are Java applications so you get the same behavior in them. Oxygen cannot display the image when editing a topic and the DITA OT cannot publish it.
I tried loading using the usual Java libraries the image called restore1.png and an out of memory occurred.
I do not quite know if this is a bug in the Java image handling libraries or a problem in the PNG images themselves but the image cannot be properly loaded by the Java libraries.

But I think that the problem lies in the PNG image itself.

When we edit images for our user manual we usually use GIMP which is a free and very good image editor:

http://www.gimp.org/

I loaded the restore1.png in GIMP, saved it and then the Java libraries had no problem interpreting it.

So my suggestion to you would be to try and use a different image editor than MS Paint, try GIMP for example.

Regards,
Radu

[mleneis]

Thank you ever so much, Radu! You are a support god!

I have re-saved the problem images (as jpegs this time) and it all builds cleanly and beautifully!

You have reinforced my suspicion of Paint - thanks for the recommendation of a better (free) tool. (I've just started this job and can't justify too many licences to my boss, especially as I'm buttering him up for the Oxygen licence - and I'm a Mac user at home so not familiar with what tools are good for Windows.)

Thank you again, I really appreciate all your help. Please let your boss know whatever you're paid, it's not enough.

Have a great weekend (if you get one)!
Mary