Adopt convention for new XQuery modules

[joewiz]

As @tuurma proposed in #102:

... we may want to rework the naming at some point, perhaps already for the 9 release if, as it seems to me now, it may include further breaking changes.

Building on my proposal there, here is a new draft for consideration:

As of (insert date), new XQuery modules contributed to the TEI Publisher repository should follow the following convention for assigning file extensions and namespace prefixes and URIs.

File extensions: For file extensions, use the .xq file extension for main modules and .xqm for library modules.

Namespaces: For namespaces library modules should use a namespace prefix that either matches the filename or is a logical abbreviation/truncation thereof; and the namespace URI should be derived from the namespace prefix, prepended with http://teipublisher.com/ns/.

For example, a new library module handling the API for annotation registers could be called registers.xqm, with a namespace prefix of registers and a namespace URI of http://teipublisher.com/ns/registers.

In order to preserve backwards compatibility, existing code that does not conform to this convention should not be changed purely for consistency's sake.

Of course, the proposal could be adjusted to more closely adhere to current practices. The purpose is to adopt a convention, to help guide developers and users.

[tuurma]

Thanks @joewiz, perfect timing posting this issue.

I would add to the draft also a namespace convention for TEI Publisher based apps, to include apps or data and the custom app name after the /ns/ part. This way we'll be able to avoid any potential naming collisions between Publisher modules and custom application modules.

This way a TP-based app for the Lelewel correspondence could use a namespace like http://teipublisher.com/ns/apps/lelewel, its data package: http://teipublisher.com/ns/data/lelewel-data. A custom module for registers could be http://teipublisher.com/ns/apps/lelewel/registers.

[joewiz]

That's a nice convention and structure. I notice many of the library modules that support TEI Publisher's OpenAPI endpoints in tei-publisher-app's modules/lib/api directory have api in their namespaces. For example, http://teipublisher.com/api/annotations. I wonder if this is worth taking forward too - for modules that are related to the OpenAPI facility?

[tuurma]

Good point about the api modules, though in my mind the demarkation line between API modules and other modules is not very clear as more and more functionality is routed via the API and less and less through exist templating. I am in a middle of work on registers handling and refactoring large parts of the annotations that overlap with registers and there it's not easy to judge what should really go where. From my perspective the line between the Publisher modules (which should be normally left untouched by users) and custom ones is something that should be very clear and perhaps reflected in the namespace conventions but I would very much welcome others' opinions.