Validation of DITA Map Linked Content?

[[email protected]]

Is it possible, from within XMetaL (Map editor, or other view) to check the validity of all the files referenced in a DITA Map before generating output (I don't mean just “Refresh References”)?

Thanks,

RP

Reply

[Derek Read]

No, such a feature does not exist. Is this a common issue for you?

I'm primarily interested in why you might have invalid documents on disk.

We are looking at adding a feature that will allow you to perform various actions on multiple files, either referenced from a DITA map or on specific folders, but this particular one (validation) is no currently on the list of actions.

Reply

[[email protected]]

It's not a common issue, but came up today when a map wouldn't convert to a PDF even tho it built a complete .fo file in the transform process but RenderX said the .fo wasn't valid, which in turn was due to an invalid XML file in the Map. With 100s of files in the Map, it would've been quicker to validate the files in the map as opposed to working backwards from the .fo file to figure out what the problem file was.

RP

Reply

[Derek Read]

OK, that sounds like a good use case. I will pass this on to development so they can consider it.

Thanks.

Reply

[MarcB]

Is there any news on this, Derek?
Can't find anything new in XMetaL 10.0.

I will add another use case:
DITA files generated by script (transformation from another XML dialect) or another tool (e.g., published output from AuthorIT), to be included in integrated DITA-based documentation deliveries.
Often this also results in nested DITA maps (maps and bookmaps).

I believe it would not be too difficult to write such a parser especially with XSLT 2.0 features, but it would be nice to have something within XMetaL.

Thanks and best regards,
Marc Beckers
Software AG

Reply

[Derek Read]

I'm not sure XSLT is a good idea for validation, or if it is I'm not sure it makes sense to try to build something from scratch that would use XSLT when there are alternatives.

Regardless, I think your best bet, if you are consistently receiving invalid XML from some source is to modify the tool creating that source so that it creates proper output. Doesn't it seem wrong to rely on a second tool to help fix up issues another tool is creating? If this happens once or twice for the odd file then sure, that makes sense, but if the issue is ongoing then I think it makes the most sense to address the issue at the source.

If these are DITA documents perhaps the easiest thing to do is to run them through the DITA OT. By default the DITA OT validates input documents (the ANT parameter named “validate” defaults to “true”). Just generate output then check for errors in the output log file. Of course this will not fix the errors, it will just identify them. You'd need to fix them separately, and ideally (if this is an ongoing problem) correct the tool that is introducing the errors.

Note that if you try to reference an invalid DITA document by adding a topicref to a DITA map in XMetaL Author Enterprise that will fail, so your maps will also need to have been generated by this other source, or your maps would need to have been created in XMetaL Author Enterprise when your topics were valid. If at some point after that the topic is modified to be invalid XMetaL Author Enterprise isn't going to catch that because the reference has already been made. Validating all the topics referenced in a map is considered redundant because the DITA OT already does that.

I'm attaching a screenshot of the kind of thing you can look for in the output log file. The referenced file noted in these errors begins as follows and contains an element named which is not allowed and also improperly nested:

[code]




 
…etc…[/code]

Reply

[Derek Read]

Here's another DITA OT validation error for another similar file where I've introduced a element, also into a DITA concept topic.
See attached image. Here's the relevant part of the error:
... c_Welcome_invalid.xml Line 7: The element "concept" must be terminated by the matching end-tag ""

Reply

[Derek Read]

If you are looking for a feature that would allow you to process multiple files there is the “Run Cross-File Operation” feature in the Tools menu. In theory you can create your own custom operation (follow one of the existing examples). This is not documented in any way but the 4 existing examples are here: AuthorXMDKMFOServiceservicecustomScripts

We have not documented this yet because I believe we'd like to rewrite it to be more user friendly for people wishing to create their own. Creating an operation is a bit tricky with the current design.

I don't believe this feature can be used to validate documents (in its current state) however. XMetaL Author Enterprise has a few APIs that work with its validation engine (including “IsValid” and a few others). But this feature is specifically coded to load documents into memory as well-formed in order to speed up processing. The main goal behind the feature was to provide a batch method for performing the types of operations that we have included as examples, and all of these assume your documents were created with XMetaL Author and so they should already be valid.

Reply

[Author]

Posts