Add a document type for a custom RNG schema with a custom URN

[Graydon2014]

Hi --

The overall goal here is to get Author to recognize the document type so we can add some custom CSS extensions.

In oXygen 21, I've created a custom extension framework; there's a directory with custom DITA schemas (which are complete document types) and a catalog file, and a sibling directory of templates.

This part works; I can create a new DITA document based on the templates, and they validate correctly based on the extension framework's catalog associations to schemas in the extension framework.

What I'm not getting is a document type association; the Properties view shows a Document type value for a default DITA document created in the context of the extension framework, while a document create for one of the custom document types gets no Document type property at all.

If I go to Options->Preferences->Document Type Association, select the custom framework, hit Edit, and look at the "Associations" tab, it's not at all clear how I use a URN public ID to associate the custom documents with a document type. (I'm a little worried that there's detection of the OASIS standard URNs in the custom java class, but non-OASIS URNs are effectively invisible.)

What should I be doing (at the "URN goes here" level!) so the custom RNG schemas have a document type so Author knows how to style them?

Thanks!
Graydon

[Radu]

Hi Graydon,

We do not have a framework-specific association rule to state that it matches an xml document only if its xml-model processing instruction references a certain schema. I will add an internal issue to consider adding something like this.
Two possible workarounds:
1) If end users will only work with your custom framework configuration, in the Preferences->"Document Type Associations" page edit your framework customization and set its priority to "High" so that it will be the first framework which will be tested (and probably matched) when opening the XML document.
2) If you add/edit an association rule in the framework customization dialog, there is the possibility to use a custom Java API class to improve the detection:

https://www.oxygenxml.com/InstData/Edit ... tcher.html

so you could create a custom implementation of the "DocumentTypeAdvancedCustomRuleMatcher" interface (our Oxygen SDK contains all the necessary JAR libraries to compile your implementation), create a JAR library with your implementation, copy the JAR to the framework folder, add a reference to the JAR in the "Classpath" tab and then use the implementation from the JAR in the association rules.

One of the callback methods in the new API:

Code: Select all

public boolean matches(java.lang.String systemID,
                       java.lang.String rootNamespace,
                       java.lang.String rootLocalName,
                       java.lang.String doctypePublicID,
                       org.xml.sax.Attributes rootAttributes,
                       java.io.Reader contentReader)

sends you the entire "contentReader", a reader over the XML content which could be used by you to perform the detection yourself.

Regards,
Radu

[Graydon2014]

Thanks, Radu!

Association rules using xml-model would be extremely useful.

(No luck with setting the priority on the custom extension framework to "high"; no document type, and no CSS association.)

[chrispitude]

This is interesting; I didn't know you could provide a DITA schema using a custom framework. Does that relieve users from having to put it in the plugins/ folder of the DITA-OT installation inside the Oxygen XML directory?

[Radu]

Hi,

About this remark:

No luck with setting the priority on the custom extension framework to "high"; no document type, and no CSS association

This means that the association rules set on your custom framework (which by now should be the first one in the list) do not match at all the XML files you are opening. So you would need to find out why this is.

Regards,
Radu

[Radu]

About Chris' remark:

This is interesting; I didn't know you could provide a DITA schema using a custom framework. Does that relieve users from having to put it in the plugins/ folder of the DITA-OT installation inside the Oxygen XML directory?

An extension of the DITA framework can provide its own XML catalog which may resolve its DTD public IDs (or references to XML or RNG Schemas) to some custom locations.
This will make validation and editing inside Oxygen work but this will not make publishing work as the publishing is still done with the DITA OT which looks for XML catalog mappings in only one place, in its "catalog-dita.xml" XML catalog file.
So if you also want to make publishing work you need to install a DITA OT plugin with the specialization.

Regards,
Radu

[Graydon2014]

Two follow on questions.

Firstly, RNG doesn't have a concept of "fixed" attributes; it can use the annotation namespace to provide a default value. This makes me wonder if that's the reason a DITA document associated with a specialized DTD with fixed class attributes DOES NOT require the class attributes to be present in the document, but a DITA document associated with a specialized RNG DOES require the class attributes to be present in the document for oXygen to consider the document valid. (I know the association is correct because the correct class attribute values are there in the autocomplete when I go to add the class attributes.)

Secondly, there are four groups of document templates in the extension framework; RNG maps, RNG topics, DTD maps, and DTD topics.

When creating a new document, RNG maps and the DTD topics show in the "Choose file template" dialog with only the actual document templates showing. The DTD maps and the RNG topics show the document templates (which work) AND the properties files. This makes me wonder if I've set the category.properties file categoryPath property incorrectly. I've copied over these values from the default framework; if there's a list of supported values for categoryPath I have not been able to find it. Or, well, something else. This seems highly peculiar.

Thanks!

[Graydon2014]

When creating a new document, RNG maps and the DTD topics show in the "Choose file template" dialog with only the actual document templates showing. The DTD maps and the RNG topics show the document templates (which work) AND the properties files. This makes me wonder if I've set the category.properties file categoryPath property incorrectly. I've copied over these values from the default framework; if there's a list of supported values for categoryPath I have not been able to find it. Or, well, something else. This seems highly peculiar.


It turns out that oXygen picks up vim backup files ending with tilde, e.g. topic.properties~, and displays those in the pick list.

So I'm glad to have found out what's causing it and might suggest that it shouldn't happen.

[Radu]

Hi,

About your questions:

Firstly, RNG doesn't have a concept of "fixed" attributes; it can use the annotation namespace to provide a default value. This makes me wonder if that's the reason a DITA document associated with a specialized DTD with fixed class attributes DOES NOT require the class attributes to be present in the document, but a DITA document associated with a specialized RNG DOES require the class attributes to be present in the document for oXygen to consider the document valid.

In the Oxygen Preferences->"XML / XML Parser / RELAX NG" page there is a checkbox called "Add default attributes values". When checked (and it's checked by default) Oxygen will take into account default attribute values coming from XML documents which associated RNG schemas (and they are defined in the RNG in the way that you mentioned). So as long as the XML document as an xml-model processing instruction referring to the RNG schema, Oxygen should take the attribute defaults into account when deciding what framework to use (when the XML is opened) and then for editing and validation.
As an example in the "New file templates" list there is a "Task (Relax NG)" template. Oxygen opens it with the default DITA support and everything works fine.

It turns out that oXygen picks up vim backup files ending with tilde, e.g. topic.properties~, and displays those in the pick list.
So I'm glad to have found out what's causing it and might suggest that it shouldn't happen.

Different editing applications may have different ways to store backup files with various patterns added to the original file names. I will add an internal issue to maybe consider skipping to most common ones or maybe add a setting to define the patterns of the skipped files.

Regards,
Radu

[Graydon2014]

Hi Radu --

In the Oxygen Preferences->"XML / XML Parser / RELAX NG" page there is a checkbox called "Add default attributes values".

This was checked. It turns out that if the DITA class attribute value does not end with a space, the "add default attributes" mechanism fails and doesn't provide an error message indicating the problem, you just get told that your document is invalid because it doesn't have class attributes.

This was entirely my mistake, and adding spaces at the end of the class attributes in the RNG schemas fixed it. It would still be helpful to have a "I'm trying! but these aren't class attributes!" message of some kind when this error condition is encountered.

Thanks!
Graydon

[Radu]

Hi Graydon,

Indeed the specification mandates that the @class attribute should have a trailing space:

https://www.oxygenxml.com/dita/1.3/spec ... ibute.html

At least one trailing space character (" "). The trailing space ensures that string matches on the tokens can always include a leading and trailing space in order to reliably match full tokens.

I still cannot reproduce the problems you encountered when having that @class attribute not ending in a space, for example if I open a DITA topic looking like this:

Code: Select all

<?xml-model href="urn:oasis:names:tc:dita:rng:concept.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="urn:oasis:names:tc:dita:rng:concept.rng" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<concept id="concept_nqs_4jv_vhb" class="- topic/topic concept/concept">
    <title></title>
    <shortdesc></shortdesc>
    <conbody>
        <p></p>
    </conbody>
</concept>

I receive the following automatic validation error:

Invalid format for "class" attribute. At least one trailing space character (" ") should be present.

Regards,
Radu

[Graydon2014]

Hi Radu --

I still cannot reproduce the problems you encountered when having that @class attribute not ending in a space, for example if I open a DITA topic looking like this:

Some more context.

The RNG schemas being used are NOT the OASIS DITA schemas, but a constrained subset written from scratch. (RNG does many things well, but support constraints on DITA not so much.)

EVERY @class attribute defined in those schemas was formatted incorrectly (I got a regular expression wrong when constructing the RNG schemas) so that each class attribute was defined so that it had an initial space and did not have a final space. (So @class=" + topic/topic", etc.)

The documents I saw the initial issue were created from really minimal template files, and once I manually added a class attribute to any element, I would start seeing the "this is not a good class attribute value" error about that specific attribute. Before that, I didn't get an error about the class attribute value being improper, I got an error that there were no class attribute values. (Presumably because none of them were syntactically correct!)

As I said, definitely my mistake. And hopefully no one else will ever do this, but if they do, they might find the error message confusing, too.

Thanks!
Graydon

[Radu]

Hi Graydon,

And hopefully no one else will ever do this, but if they do, they might find the error message confusing, too.

I would also like to improve things on our side but for that I would need a way to reproduce the original problem. If you can share your RNG customization schemas with us (the ones having the problem) via email (support@oxygenxml.com) I could try to look into this further..

Regards,
Radu

[Graydon2014]

Hi Radu --

Between my initial report and now, I've upgraded from oXygen XML Editor for Linux 21 to oXygen XML Editor for Linux 21.1, and I can no longer replicate the issue.

I've bundled up the git repository for the extension framework in question and sent it to the email address provided.

Thank you!
Graydon

[Radu]

Hi Graydon,

Thanks, we'll keep in touch via email then.

Regards,
Radu

[chrispitude]

Hi Graydon,

You might want to take a look at my DITA plugin creator to see if it could make specializations easier for you:

https://github.com/chrispy-snps/DITA-plugin-utilities