Parameter Entity Support

[scotth]

Does XMetaL Author 6.0.1.030 support parameter entities? The external entities dialog will not allow me to include a percent in the Name box. Also, when I manually enter an external entity in plain text view, and try to switch back to normal view, I receive an error similar to this:

The XML Schema “foo.xsd” could not be loaded.
Declaration has an invalid name.
At line(1), column(3).

Removing the parameter entity declaration and reference results in me being able to switch to normal view again. Below is an example of my entity declaration and reference.

%foo;

I am trying to include an external file into my XML document that contains multiple entity definitions, so I would also welcome other options for achieving this goal.

Reply

[Derek Read]

Yes using parameter entities in an internal subset is supported (as well as using them in a DTD of course). However, the External Entities dialog does not create parameter entities, it creates “file entity references” (aka: “external entity” references). If you use this dialog you will end up with something like this in your internal subset:

If you must insert a parameter entity I think you would need to do so in Plain Text view or prior to opening the document (perhaps as part of a template or similar) or using script (which can be used to modify documents before open, or perhaps to create a template on the fly, etc). Alternatively, you could declare the entity in the DTD itself. I think we have always considered this to be a “developer oriented” step in any configuration process and so have chosen not to expose anything for this for “authors” in the product's UI.

Perhaps you could elaborate on what you would use such a feature for so we can consider whether it would make sense for us to expose something that would be generally useful to users of the software.

I am attaching three sample files that show that (once in the document) the product deals with parameter entities as expected.
1. foo.ent contains declarations for three text entities.
2. journalist_dtd_test.xml uses the sample journalist.dtd and references foo.ent as a parameter entity in its own internal subset.
3. journalist_xsd_test.xml uses the sample journalist.xsd and references foo.ent as a parameter entity in its own internal subset.

With either of those XML documents open if you open the Insert > Entity Reference dialog it will list the three text entities declared inside foo.ent and allow you to insert them. The behavior is essentially the same as if you had declared these entities in the DTD itself (which of course for Schema is not possible).

The usage of entities in an internal subset together with a DTD is clearly defined and XMetaL Author follows that model.

Although the W3C has not officially defined how parameter entities are to be used in conjunction with a W3C Schema instance XMetaL supports them in an internal subset, as is similar to usage with a DTD (as demonstrated in journalist_xsd_test.xml). I believe this is similar to how other XML parsers support entities with W3C Schema, if they support them at all. The W3C's “XML Schema Part 0: Primer” has an appendix called [url=http://www.w3.org/TR/xmlschema-0/#usingEntities]Using Entities[/url] which vaguely hints at declaration of entities (in general, not specifically parameter entities) in instance documents.

Further information on entities in genera, including details on the user interface, is described in these XMetaL Author help topics:
 Appendix A: XML Basics > DTDs and Schemas > Entities
 Authoring structured content > Working with entities (and subtopics)

Reply

[scotth]

Thanks, Derek. The example is quite helpful. This is probably not a big deal for me, but I noticed that the Entities options under the Tools menu disappear after inserting the parameter entity. Is this by design?

Reply

[scotth]

There's one more related issue that I am seeing. When I insert the parameter entity declaration, I can't seem to get my .xac file to work for me anymore. I get an error stating that the “Declaration has an invalid name.” If I remove the parameter entity declaration, I no longer get the error. Likewise, if I use a separate file deployment (.css, .tbr, .ctm, etc…) with the document including the parameter entity declaration, I no longer get the error.

Reply

[Derek Read]

XAC files are tested to include the compiled version of the DTD or XSD, which is the RLX or RLD file (or for SGML there is the RLS file). These compiled versions include the information from the main schema file together with any files they reference (and possibly also other information including an ATT file, calalogs, SGML declarations file, and some other metadata). They are basically a snapshot snapshot (cache) of what XMetaL would have built in memory if all of this stuff was available to it (as separate files). It is possible to include a DTD or XSD inside the XAC instead of the compiled version but XMetaL Developer does not do that by default and we do not extensively test this from version to version.

The easiest way to support what you are doing is to deploy using the separate files method (and make sure you do not also include the XAC as it will be read first and the other files ignored).

Reply

[Author]

Posts