README.md

linter-autocomplete-jing

Autocomplete and on-the-fly validation of XML documents in Atom.

Supported schema types:

• Validation: RELAX NG (XML and compact syntax), Schematron (1.5, ISO), W3C Schema (XSD 1.0) and DTD
• Autocomplete: RELAX NG (XML and compact syntax), W3C Schema (XSD 1.0)

You can find a basic set of common XML schemata and corresponding rules for linter-autocomplete-jing in the xml-common-schemata package.

XML document processing is handled in Java using Jing, Xerces and Saxon HE. For the source code of the Java part see https://github.com/aerhard/xml-tools.

Installation

Select the package in Atom's Settings View (Ctrl-,) / Install Packages or run apm install linter-autocomplete-jing from the command line.

The package depends on a Java Runtime Environment (JRE) v1.7 or above. If running java -version on the command line returns an appropriate version number, you should be set. Otherwise, install a recent JRE and provide the path to the Java executable either in the PATH environment variable or in the linter-autocomplete-jing package settings in Atom.

Package Settings

Settings Form	Atom Config Property	Description
Java Executable Path	javaExecutablePath	The path to the Java executable (java).
JVM Arguments	jvmArguments	Space-separated list of arguments to get passed to the Java Virtual Machine on which the validation server is run.
Schema Cache Size	schemaCacheSize	The maximum number of schemata retained simultaneously in memory.
Display Schema Parser Warnings	displaySchemaWarnings	Whether or not to display warning messages from the schema parser.
XML Catalog	xmlCatalog	The path to the XML Catalog file to be used in validation.
DTD Validation	dtdValidation	Determines under which circumstances DTDs should be used in validation. Possible values: 'always', 'never' or 'only as fallback'. When 'only as fallback' is selected, documents get validated against DTDs only if no other schemata are available for validation.
XInclude Aware	xIncludeAware	Whether or not validation should resolve XIncludes in the instance document. XInclude-aware validation is currently not supported in DTD-based validation. If this option is set to 'true' and your documents contain or refer to DOCTYPE declarations, you can prevent DTD error messages by adjusting the DTD Validation option.
XInclude Fixup Base URIs	xIncludeFixupBaseUris	Whether or not xml:base attributes should be added / adjusted in documents included with XInclude statements.
XInclude Fixup Language	xIncludeFixupLanguage	Whether or not xml:lang attributes should be added / adjusted in documents included with XInclude statements.
Autocomplete Priority	autocompletePriority	The inclusion priority of the Autocomplete Plus provider. In order to exclude other autocomplete providers, the number must be larger than the other providers' priorities. Defaults to 1 (In order to suppresses the default tag snippets provided by the language-xml package, set autocomplete priority to 2.)
Autocomplete Scope	autocompleteScope	The schema types which should be used for autocomplete.
Wildcard Suggestions	wildcardSuggestions	Inclusion of wildcards in autocomplete suggestions. Possible values: 'all', 'localparts', 'none'.

(In order to edit the settings, press Ctrl-, or select "Packages" / "Settings View" / "Open" in the main menu. Then either navigate to the settings form ("Packages" tab, search for "linter-autocomplete-jing" and click the "Settings" button) or click the link to Atom's config file.

File types

Validation and autocomplete get activated when the current file's grammar scope includes an item starting with text.xml. The Atom core package language-xml (installed by default) assigns a large set of common XML file extensions to text.xml and text.xml.xsl. XML property lists (text.xml.plist) are supported by another core package, language-property-list.

If a file extension you're working with isn't included in language-xml or any grammar derived from text.xml you can either request adding the extension at https://github.com/atom/language-xml or create a local association in your config.cson:

1. Open config.cson by pressing Ctrl-Shift-P and then entering Open Your Config
2. Add or extend the customFileTypes property of core

The following example assigns the .tei, .mei and .odd extensions to text.xml:

  core:
    customFileTypes:
      "text.xml": [
        "tei"
        "mei"
        "odd"
      ]

A second way of supporting custom file extensions is creating a new grammar package based on text.xml and specifying the extensions in the grammar definition. An example can be found in the demo package.

Specifying Schemata

Schema References in Source Documents

You can specify schemata by providing a DOCTYPE declaration, XSI schema instance attributes or xml-model processing instructions; see https://github.com/aerhard/linter-autocomplete-jing/tree/master/spec/validation/xml for a collection of examples).
If your documents contain references to remote schemata, you can improve performance and reduce network traffic by using an XML catalog file to map remote resources to local files. Projects like the Text Encoding Initiative (TEI) provide packages which include catalog files that can be added to the linter settings.

Schema Rules

If you'd like to avoid providing schema hints in each individual source document you can specify 'validation rules' in Atom's config.cson or in a separate Atom package.

Below is an example of rules in config.cson. The first rule associates files ending with .rng with an RNG schema at /path/to/relaxng.rng, the second one associates the root element namespace urn:oasis:names:tc:entity:xmlns:xml:catalog with the RNC schema at /path/to/catalog.rnc:

"*":
  "linter-autocomplete-jing":
    rules: [
      {
        priority: 1
        test:
          pathRegex: "\\.rng$"
        outcome:
          schemaProps: [
            {
              lang: "rng"
              path: "/path/to/relaxng.rng"
            }
          ]
      }
      {
        priority: 1
        test:
          rootNs: "urn:oasis:names:tc:entity:xmlns:xml:catalog"
        outcome:
          schemaProps: [
            {
              lang: "rnc"
              path: "/path/to/catalog.rnc"
            }
          ]
      }
    ]

Each rule must have a test and an outcome property. test contains the criteria which need to be fulfilled for that rule to apply. outcome contains the schema / catalog information to be used when the rule is matched. When there are multiple rules, the outcome of the first matched rule gets applied (order is significant). The priority property of a rule is optional and defaults to 0. Rules with higher priority get evaluated first, rules with the same priority get evaluated in the order in which they are specified. Rules in config.cson always take precedence over rules from packages.

Possible properties of test:

• pathRegex: a regular expression string matching the full path of the current file
• rootNs: the namespace of the root element (string)
• rootLocalName: the localname of the root element (string)
• rootAttributes: the required attributes of the root element (object with attribute names as keys and expected attribute values as values)
• publicId: the Public ID specified in the DOCTYPE declaration

Possible properties of outcome:

• dtdValidation: determines under which circumstances DTDs should be used in validation. Possible values: 'always', 'never' or 'fallback'. When 'fallback' is selected, documents get validated against DTDs only if no other schemata are available for validation.
• xIncludeAware: whether or not validation should resolve XIncludes in the instance document (boolean)
• xIncludeFixupBaseUris: whether or not xml:base attributes should be added / adjusted in documents included with XInclude statements (boolean)
• xIncludeFixupLanguage: whether or not xml:lang attributes should be added / adjusted in documents included with XInclude statements (boolean)
• xmlCatalog: the path to the XML Catalog file to be used in validation
• schemaProps: the schemata to be used in validation (array of objects with the properties lang and path. path specifies the file path of the schema, lang the schema language which must be one of 'rng', 'rnc', 'sch.iso', 'sch.15', 'xsd' or 'none')

For an example of an Atom package containing a schema and schema association rules see demo package.

Commands

• linter-autocomplete-jing:clear-schema-cache: Removes all schema and catalog data from the in-memory cache so it will get read from disk in the next validation run.

Development

If you intend to adjust the TypeScript part of the package (without making changes to the Java server), first uninstall the version of linter-autocomplete-jing downloaded with Atom’s package manager (apm uninstall linter-autocomplete-jing) and clone the package respository from https://github.com/aerhard/linter-autocomplete-jing. From the root of the repository, first run apm install and npm install --only=dev to install all dependencies. Then run apm link to register the package in Atom (undo with apm unlink). The Typescript source code is in the src folder of the project. npm run build and npm run watch transpile the content of src to a single JavaScript file in dist which gets loaded by Atom. Press Ctrl-Alt-R in Atom to reload the updated module. Integration tests are located in the spec folder and can be run with npm run test. Unit tests are located in src (all files ending with .spec.ts) and get run with npm run jest.

In order to make adjustments to the TypeScript as well as as the Java parts, checkout https://github.com/aerhard/xml-tools and follow the instructions in the README file.