DITA and XMetaL Discussion
Fa March 14, 2017 at 10:02 am
Unable to create PDF file due to foreign elementMarch 14, 2017 at 10:02 amParticipants 3Replies 4Last Activity 5 years, 10 months ago
I usually create all the documentation using XMetaL (using XMetaL 11.0), but for one particular project, my colleagues have created the DITA files (they do not use XMetaL) and they have included an element that XMetaL does not recognize. They need this to be included in the htm files that are generated when building their software, so removing it is not an option.
The element added is
and has an “anchor” attribute (e.g. )
I have a few years ago (using XMetaL 6) successfully generated the pdf. Back then, I think the only thing I did was to add an attribute for condition (output=”htm”, so that would be
). XMetaL still would not show the tags on view, but at least it was able to just ignore it when building the pdf. However, this does not seem to work now, even with my old XMetaL. So I must have done something back then that worked, I just don't remember what it was.
Is there any way to just add that element so that it would be recognized by XMetaL? Or is there any other workaround?
Thank you in advance!
FaDerek Read March 15, 2017 at 6:12 pm
Reply to: Unable to create PDF file due to foreign elementMarch 15, 2017 at 6:12 pm
Do you know what the purpose of the element is?
Do the people that are adding it know what it is for?
Are they aware that they are adding an element to the document that is making the document invalid?
By far the simplest solution would be to replace this element with an equivalent valid DITA element.
If you cannot modify the XML so it is valid you could create a specialized DITA DTD. DITA defines something called “specialization”. This allows you to create a DTD that defines a select number of elements from the standard DITA DTDs as well as define new elements based on existing DITA elements (effectively performing the same “function” but having a different name). You would need to have someone familiar with creating a specialized DITA DTD do this. Once that is done the process for configuring XMetaL Author Enterprise to recognize that DTD as a DITA DTD is quite simple: you just fill in a couple of fields in a dialog and restart the software. Note that in this case you would still need to modify the XML files to change their PUBLIC id so that they no longer reference the standard DITA DTDs (because they are not standard DITA they are specialized). You would modify the XML's DOCTYPE declaration to use the PUBLIC id for the specialized DITA DTD. For all the information we document about DITA specializations see the Help topic: Working with DITA > DITA Specializations.
Of course any DTD used with XMetaL Author can simply be modified directly to allow any element, but that is a bad idea when working with a standards-based DTD like DITA as you are then creating files that are not compatible with the standard. It is only something you would do if you are in complete control of the DTD (in other words, you created or “own” the DTD, and you can roll out that change to everyone and all tools that need it).Derek Read March 16, 2017 at 1:30 am
Reply to: Unable to create PDF file due to foreign elementMarch 16, 2017 at 1:30 am
One more point of clarification, you say “They need this to be included in the htm files that are generated when building their software”.
It sounds like this element ends up in the final output, meaning that it does not necessarily need to be in the DITA content itself. I suspect what might have occurred with the older version of the DITA Open Toolkit is that it did not recognize the element as being DITA, and it had some form of bug that caused it to pass this element through to the HTML output unmodified. Either newer versions of the DITA OT have corrected this bug or they are simply validating the document properly (stopping all output).
If that is the case then replacing it with a valid DITA element and then altering the DITA Open Toolkit (its XSLT) so that it inserts
into the HTML output when it sees that element (and possibly element + specific attribute value) is probably what you would want to do.
I'm not even clear on that point though, because
doesn't exist as part of any HTML spec that I'm aware of, so adding it to an HTML file would make that HTML invalid as well. Perhaps the HTML is custom as well? And it is being displayed with some custom browser or other software (so not really HTML, but perhaps based on HTML)?Fa March 20, 2017 at 2:11 pm
Reply to: Unable to create PDF file due to foreign elementMarch 20, 2017 at 2:11 pm
Thank you very much Dereck for your detailed answers. You raise some very good points in them.
I have already looked at the possibility to create our own DTD, but as you will have noticed, I have no experience with it at all and very limited knowledge and understanding of DITA in general. And I don't think the company is willing to purchase custom-made DTDs, so that's kind of out of the question. Also the point you raised of no longer having standard DITA raises a red flag.
I will try to understand better why they need these and how they are converted.
Right now your second suggestion really seems the best (where we would use valid DITA elements and modify the xslt to convert those elements to whatever they want in the html output). So thank you again for taking the time of posting a second reply with this suggestion!
I will follow up on this as soon I get something new to tell.
FaFa June 20, 2017 at 2:12 pm
Reply to: Unable to create PDF file due to foreign elementJune 20, 2017 at 2:12 pm
Hi Derek (and anyone else interested)!
Following up on this topic (sorry about the long delay!).
After discussion with my colleagues why they had ended up creating their own elements, it turned out that the main (and probably only) reason why they did that is that the program they develop uses context sensitivity.
The help file they create is a simple “single html file”.
Since they are writing their code for the different modules before the corresponding help topics even exist, they already create a context sensitive link within the software pointing to an element that does not yet exist (in a file that does not yet exist either).
At first, they tried to use the topic id attribute value as a unique identifier, but it failed because of the way the conversion is done. When DITA-OT processes the xml topics, it collects all the links and targets (in this case the topic id's), and it renames all targets in the html to “#unique_01”, “#unique_02”, etc.
I guess the reason behind the behaviour is that since it creates a single html out of lots of small DITA files, it wants to make sure there are no duplicate anchors, and therefore, instead of having a mechanism that checks for duplicate, it just coldly replaces all names for anchors created from elements with new names that it knows are unique.
The drawback in this case is that there is therefore no way of knowing what to link to before the html has been built, and even then it would require a lot of manual work. That's how they came up with the idea of creating the help_anchor elements that they then process to become an html anchor ().
So my question now is: is there
a) a way to force XMetaL (DITA-OT) to keep the elements' IDs intact and transfer them to the href attribute value for anchors () in the html instead of replacing them by the #unique_nn value
b) an existing, valid DITA element that could be use for this purpose?
- You must be logged in to reply to this topic.