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

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Fri May 10, 2019 7:24 pm

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Mon May 13, 2019 3:05 pm

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Mon May 13, 2019 3:48 pm

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
Posts: 57
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Tue May 14, 2019 2:12 am

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Tue May 14, 2019 7:21 am

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 Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Radu
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Tue May 14, 2019 7:29 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Wed May 22, 2019 5:19 pm

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
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Wed May 22, 2019 5:57 pm

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Thu May 23, 2019 12:24 pm

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Thu May 23, 2019 5:02 pm

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Fri May 24, 2019 10:31 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Tue May 28, 2019 11:15 pm

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Wed May 29, 2019 7:09 am

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
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

Graydon2014
Posts: 9
Joined: Tue May 20, 2014 6:55 pm

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

Post by Graydon2014 » Wed May 29, 2019 6:46 pm

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
Posts: 6512
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Thu May 30, 2019 7:07 am

Hi Graydon,

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

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

chrispitude
Posts: 57
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Thu Jun 20, 2019 4:02 am

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

Post Reply