RelaxNG support documentation

Signed-off-by: azerr <azerr@redhat.com>

Author: angelozerr

README.md

@@ -19,6 +19,7 @@ This VS Code extension provides support for creating and editing XML documents,
 | ------------------ | ------------------------------------------- |
 | enabled by default | requires additional configuration to enable |
 
+  * [RelaxNG (experimental) support](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Features/RelaxNGFeatures#relaxng-features) (since v0.22.0)
   * Syntax error reporting
   * General code completion
   * [Auto-close tags](https://github.com/redhat-developer/vscode-xml/blob/main/docs/Features/XMLFeatures.md#xml-tag-auto-close)

docs/Features.md

@@ -2,6 +2,7 @@
 
 [vscode-xml](https://github.com/redhat-developer/vscode-xml) has a number of notable features available for XML, XSD and DTD support.
 
-- [XML Features](Features/XMLFeatures.md#xml-features)
-- [XSD Features](Features/XSDFeatures.md#xsd-features)
-- [DTD Features](Features/DTDFeatures.md#dtd-features)
+- [XML features](Features/XMLFeatures.md#xml-features)
+- [XSD features](Features/XSDFeatures.md#xsd-features)
+- [DTD features](Features/DTDFeatures.md#dtd-features)
+- [RelaxNG features](Features/RelaxNGFeatures.md#relaxng-features)

docs/Features/RelaxNGFeatures.md

@@ -0,0 +1,134 @@
+# RelaxNG features
+
+[vscode-xml](https://github.com/redhat-developer/vscode-xml) provides validation, completion, hover in XML file based on [RelaxNG schemas](https://relaxng.org/) since `0.22.0`:
+
+![RelaxNG support](../images/RelaxNG/RelaxNGSupport.gif)
+
+It supports both:
+
+ * [RelaxNG XML syntax (*.rng files)](https://relaxng.org/tutorial-20011203.html).
+ * [RelaxNG Compact syntax (*.rnc files)](https://relaxng.org/compact-tutorial-20030326.html).
+
+![XML Validated with RelaxNG](../images/RelaxNG/XMLValidatedWithRelaxNG.png)
+
+You can associate your XML file with `RelaxNG grammar` (`file` or `URL`) using :
+
+ * an `xml-model` processing instruction
+
+```xml
+<?xml-model href="addressBook.rng" type="application/xml"?>
+<addressBook>   
+  ...
+</addressBook> 
+```
+
+ * an `XML catalog` using the same method as [XSD](Validation#XML-catalog-with-XSD)
+ * a `file association` using the same method as [XSD](Validation#XML-file-association-with-xsd)
+
+## RelaxNG grammar
+
+[vscode-xml](https://github.com/redhat-developer/vscode-xml) provides support for `RelaxNG grammars`:
+
+ * for [RelaxNG XML syntax (*.rng files)](https://relaxng.org/tutorial-20011203.html), it provides the same support as XSD/DTD grammars (completion, hover, validation, etc).
+ 
+![RelaxNG XML Syntax Overview](../images/RelaxNG/RelaxNGXMLSyntaxOverview.png)
+  
+ * for [RelaxNG Compact syntax (*.rnc files)](https://relaxng.org/compact-tutorial-20030326.html) it provides only syntax coloration.
+ 
+![RelaxNG Compact Syntax Overview](../images/RelaxNG/RelaxNGCompactSyntaxOverview.png)
+
+# Validation
+
+XML validation based on RelaxNG (rng, rnc) is supported:
+
+![RelaxNG Validation](../images/RelaxNG/RelaxNGValidation.png)
+
+# Completion
+
+XML completion based on RelaxNG (rng, rnc) is supported. The completion for rng can show the documentation:
+
+![RelaxNG Completion And Documentation](../images/RelaxNG/RelaxNGCompletionAndDocumentation.png)
+
+# Hover
+
+Hover based on RelaxNG rng can show the documentation:
+
+![RelaxNG Hover And Documentation](../images/RelaxNG/RelaxNGHoverAndDocumentation.png)
+
+# Go to Type Definition
+
+From the XML document you can go to the type definition to navigate to the element/attribute declaration for both `rnc` and `rng`.
+
+To do this, select an XML element/attribute and use the contextual menu `Go to Type Definition`: 
+
+![Go to Type Definition Menu](../images/RelaxNG/GoToTypeDefinitionMenu.png)
+
+When you click on this menu item, VS Code will open the `rng` or `rnc` grammar file and place the cursor on the proper `element/attribute` declaration:
+
+![Go to Type Definition result](../images/RelaxNG/GoToTypeDefinitionResult.png)
+
+# How to start?
+
+## Using snippets
+
+You can use snippets to quickly create:
+
+ * an XML file associated with a RelaxNG grammar
+ * a RelaxNG XML file
+ 
+Here's a demo:
+
+![RelaxNG snippets support](../images/RelaxNG/RelaxNGSnippetsSupport.gif)
+
+## Creating XML, rng, rnc files
+
+You can create a RelaxNG grammar that uses the XML syntax by making a file with the extension `.rng`. 
+For instance, here is a file `addressBook.rng` that defines a RelaxNG grammar:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<grammar xmlns="http://relaxng.org/ns/structure/1.0">
+    <start>
+        <element name="addressBook">
+            <zeroOrMore>
+                <element name="card">
+                    <ref name="cardContent"/>
+                </element>
+            </zeroOrMore>
+        </element>
+    </start>
+    <define name="cardContent">
+        <element name="name">
+            <text/>
+        </element>
+        <element name="email">
+            <text/>
+        </element>
+    </define>
+</grammar>
+```
+
+You can create a RelaxNG grammar that uses the [compact syntax](https://relaxng.org/compact-tutorial-20030326.html) by making a file with the extension `.rnc`. 
+For instance, here is a file `addressBook.rnc` that defines the same RelaxNG grammar as `addressBook.rng`:
+
+```rnc
+element addressBook {
+  element card {
+    element name { text },
+    element email { text }
+  }*
+} 
+```
+
+The following file, `addressBook.xml`, references `addressBook.rng` using the `xml-model` processing instruction. 
+[vscode-xml](https://github.com/redhat-developer/vscode-xml) will provide the features based on the grammar shown in [the demo at the beginning of this page](#relaxng-support) when you open `addressBook.xml`.
+
+```xml
+<?xml-model href="addressBook.rng" type="application/xml"?>
+<addressBook>   
+  <card>
+    <name></name>
+    <email></email>
+  </card>
+</addressBook> 
+```

docs/README.md

@@ -4,7 +4,7 @@ Welcome to the [vscode-xml](https://github.com/redhat-developer/vscode-xml) docu
 
 ## User Guide
 
-  * [XML Validation](Validation.md#xml-validation): How to validate XML with a grammar (XSD/DTD)?
+  * [XML Validation](Validation.md#xml-validation): How to validate XML with a grammar (XSD/DTD/RelaxNG)?
   * [Preferences](Preferences.md#preferences): More info on available [vscode-xml](https://github.com/redhat-developer/vscode-xml) preferences.
   * [Formatting](Formatting.md#formatting): More info on the available formatting preferences.
   * [XML Commands](Commands.md#commands): More info on the available XML vscode commands.

docs/Validation.md

@@ -399,6 +399,10 @@ If one of the variables for an association can't be expanded (eg. because vscode
 the association is ignored.
 This feature is specific to the VSCode client.
 
+## Validation with RelaxNG grammar
+
+See [RelaxNG features](Features/RelaxNGFeatures#relaxng-features)
+
 # Other Validation Settings
 
 ## Disallow Doc Type Declarations