Pages: 1
Print
Author Topic: Unable to create PDF file due to foreign element  (Read 513 times)
Fa
Member

Posts: 18


« on: March 14, 2017, 04:02:24 AM »

Hi!

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 <Help_anchor> and has an "anchor" attribute (e.g. <help_anchor anchor="general"></help_anchor>)

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 <help_anchor anchor="general" output="htm"></help_anchor>). 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!

Fa
« Last Edit: March 15, 2017, 07:24:21 PM by Derek Read » Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2469



WWW
« Reply #1 on: March 15, 2017, 12:12:08 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).
Logged
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2469



WWW
« Reply #2 on: March 15, 2017, 07:30:24 PM »

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 <Help_anchor> 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 <Help_anchor> 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)?
« Last Edit: March 15, 2017, 07:32:54 PM by Derek Read » Logged
Fa
Member

Posts: 18


« Reply #3 on: March 20, 2017, 08:11:19 AM »

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.

Best regards,
Fa

Logged
Fa
Member

Posts: 18


« Reply #4 on: June 20, 2017, 08:12:30 AM »

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 (<a href="...">).

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 (<a>) in the html instead of replacing them by the #unique_nn value
or
b) an existing, valid DITA element that could be use for this purpose?

Thank you!
Logged
Pages: 1
Print
Jump to:  

email us