diff --git a/docs/Features.md b/docs/Features.md index f59a0534..3780e6cf 100644 --- a/docs/Features.md +++ b/docs/Features.md @@ -9,4 +9,5 @@ - [XInclude features](Features/XIncludeFeatures.md#xinclude-features) - [XML Catalog features](Features/XMLCatalogFeatures.md#xml-catalog-features) - [XML References features](Features/XMLReferencesFeatures.md#xml-references-features) -- [XML Colors features](Features/XMLColorsFeatures.md#xml-colors-features) \ No newline at end of file +- [XML Colors features](Features/XMLColorsFeatures.md#xml-colors-features) +- [Semantic Highlighting](Features/SemanticHighlighting.md#semantic-highlighting) \ No newline at end of file diff --git a/docs/Features/SemanticHighlighting.md b/docs/Features/SemanticHighlighting.md new file mode 100644 index 00000000..39a0af90 --- /dev/null +++ b/docs/Features/SemanticHighlighting.md @@ -0,0 +1,203 @@ +# Semantic Highlighting + +When an XML file is associated with a grammar (XSD, RelaxNG, or DTD), [vscode-xml](https://github.com/redhat-developer/vscode-xml) can visually distinguish **required** elements and attributes through semantic highlighting. This makes it easy to see at a glance which parts of the XML structure are mandatory according to the grammar. + +## Setting + +Semantic highlighting is enabled by default. You can enable/disable it with the `xml.semanticTokens.enabled` setting: + +```json +"xml.semanticTokens.enabled": true +``` + +## XSD + +### Given XSD + +Given the following `team.xsd` schema which declares a `team` element with a required `name` attribute and required `member` child element: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + +``` + +In this schema: + + * `member` element is **required** (`minOccurs` defaults to `1`), while `description` is optional (`minOccurs="0"`). + * `name` attribute is **required** (`use="required"`), while `region` is optional. + * `id` attribute is **required** (`use="required"`), while `role` is optional. + +### Given XML + +Given the following `team.xml` file associated with the XSD: + +```xml + + + + alice@example.com + +1234567890 + + The platform team. + +``` + +### Required elements and attributes + +With semantic highlighting, required elements (`member`, `email`) are visually distinguished from optional elements (`description`, `phone`), and required attributes (`name`, `id`) are visually distinguished from optional attributes (`region`, `role`): + +![Semantic Highlighting XSD](../images/Features/SemanticHighlightingXSD.png) + +## RelaxNG + +### Given RelaxNG + +Given the following `team.rng` RelaxNG schema: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +In this schema: + + * `member` element is **required** (inside `oneOrMore`), while `description` is optional. + * `name` and `id` attributes are **required** (not wrapped in `optional`), while `region` and `role` are optional. + +### Given XML + +Given the following `team.xml` file associated with the RelaxNG schema: + +```xml + + + + + alice@example.com + +1234567890 + + The platform team. + +``` + +### Required elements and attributes + +![Semantic Highlighting RelaxNG](../images/Features/SemanticHighlightingRelaxNG.png) + +## DTD + +### Given DTD + +Given the following `team.dtd`: + +```dtd + + + + + + + + + +``` + +In this DTD: + + * `member` element is **required** (`member+`), while `description` is optional (`description?`). + * `name` and `id` attributes are **required** (`#REQUIRED`), while `region` and `role` are optional (`#IMPLIED`). + +### Given XML + +Given the following `team.xml` file associated with the DTD: + +```xml + + + + + alice@example.com + +1234567890 + + The platform team. + +``` + +### Required elements and attributes + +![Semantic Highlighting DTD](../images/Features/SemanticHighlightingDTD.png) diff --git a/docs/README.md b/docs/README.md index 0dd7e770..3a4dd2cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ Welcome to the [vscode-xml](https://github.com/redhat-developer/vscode-xml) docu * [Symbols](Symbols.md#symbols): More info on the available settings for the document symbols (outline). * [Troubleshooting](Troubleshooting.md#troubleshooting): Info on troubleshooting and fixes to issues. * [Features](Features.md#features): Notable info and demos on features available to use. + * [Semantic Highlighting](Features/SemanticHighlighting.md#semantic-highlighting): Highlights required elements and attributes when XML is bound to a grammar (XSD, RelaxNG, DTD). * [Proxy](Proxy.md#proxy): Instructions for setting up vscode-xml to work behind a proxy. * [Binding With Grammar](BindingWithGrammar.md#binding-with-grammar): Extension feature to bind an XML document to a grammar/schema file. * Generation: [XML from Grammar](GenerateXMLFromGrammar.md) | [Grammar from XML](GenerateGrammarFromXML.md) — generate in both directions (XSD, DTD, RelaxNG, RNC). diff --git a/docs/images/Features/SemanticHighlightingDTD.png b/docs/images/Features/SemanticHighlightingDTD.png new file mode 100644 index 00000000..635e76a2 Binary files /dev/null and b/docs/images/Features/SemanticHighlightingDTD.png differ diff --git a/docs/images/Features/SemanticHighlightingRelaxNG.png b/docs/images/Features/SemanticHighlightingRelaxNG.png new file mode 100644 index 00000000..a8d20adb Binary files /dev/null and b/docs/images/Features/SemanticHighlightingRelaxNG.png differ diff --git a/docs/images/Features/SemanticHighlightingXSD.png b/docs/images/Features/SemanticHighlightingXSD.png new file mode 100644 index 00000000..a95d83ac Binary files /dev/null and b/docs/images/Features/SemanticHighlightingXSD.png differ diff --git a/package.json b/package.json index 7028e3a0..b0193872 100644 --- a/package.json +++ b/package.json @@ -709,6 +709,11 @@ "default": false, "markdownDescription": "Enable/disable XML CodeLens. Default is `false`. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22CodeLens%22%2C%22section%22%3A%22Code%20Lens%22%7D%5D) for information about CodeLens features" }, + "xml.semanticTokens.enabled": { + "type": "boolean", + "default": true, + "markdownDescription": "Enable/disable XML Semantic Highlighting. Default is `true`. When enabled and an XML file is associated with a grammar (XSD, RelaxNG, or DTD), required elements and attributes are visually highlighted. See [here](command:xml.open.docs?%5B%7B%22page%22%3A%22Features%2FSemanticHighlighting%22%2C%22section%22%3A%22Semantic%20Highlighting%22%7D%5D) for more information." + }, "xml.preferences.quoteStyle": { "type": "string", "enum": [