Merge pull request #109 from PHPCSStandards/feature/various-minor-touchups

GH Actions/XSD: various minor touchups

Author: jrfnl

.github/workflows/cs.yml

@@ -50,34 +50,36 @@ jobs:
       - name: Install Composer dependencies
         uses: "ramsey/composer-install@v2"
 
+      # @link http://xmlsoft.org/xmllint.html
       - name: Install xmllint
         run: |
           sudo apt-get update
           sudo apt-get install --no-install-recommends -y libxml2-utils
 
+      - name: Download the XSD schema
+        run: curl http://www.w3.org/2001/XMLSchema.xsd --output XMLSchema.xsd
+
       # Show XML violations inline in the file diff.
       # @link https://github.com/marketplace/actions/xmllint-problem-matcher
       - uses: korelstar/xmllint-problem-matcher@v1
 
-      # Validate the Docs XSD file.
-      # @link http://xmlsoft.org/xmllint.html
+      # Validate the XSD and XML files against schema.
       - name: Validate Docs XSD against schema
-        run: xmllint --noout --schema http://www.w3.org/2001/XMLSchema.xsd DocsXsd/phpcsdocs.xsd
+        run: xmllint --noout --schema XMLSchema.xsd DocsXsd/phpcsdocs.xsd
 
-      # Validate the XML file.
-      # @link http://xmlsoft.org/xmllint.html
-      - name: Validate ruleset against schema
+      - name: Validate PHPCSDebug ruleset against schema
         run: xmllint --noout --schema vendor/squizlabs/php_codesniffer/phpcs.xsd PHPCSDebug/ruleset.xml
 
-      # Check the code-style consistency of the XML file.
-      - name: Check XML code style
-        run: diff -B ./PHPCSDebug/ruleset.xml <(xmllint --format "./PHPCSDebug/ruleset.xml")
-
-      # Validate the Docs XML file(s).
-      # @link http://xmlsoft.org/xmllint.html
       - name: Validate docs against schema
         run: xmllint --noout --schema DocsXsd/phpcsdocs.xsd ./PHPCSDebug/Docs/*/*Standard.xml
 
+      # Check code-style consistency of the XSD and XML files.
+      - name: Check XSD code style
+        run: diff -B ./DocsXsd/phpcsdocs.xsd <(xmllint --format "./DocsXsd/phpcsdocs.xsd")
+
+      - name: Check Ruleset XML code style
+        run: diff -B ./PHPCSDebug/ruleset.xml <(xmllint --format "./PHPCSDebug/ruleset.xml")
+
       # Check the code-style consistency of the PHP files.
       - name: Check PHP code style
         continue-on-error: true

PHPCSDebug/Docs/Debug/TokenListStandard.xml

@@ -1,4 +1,8 @@
-<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd" title="Token List">
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Token List"
+    >
     <standard>
     <![CDATA[
     Lists how PHPCS tokenizes code.

README.md

@@ -199,17 +199,17 @@ In order to use it, you'll need to add the schema related attributes to the `doc
 
 ```xml
 <documentation
-    title="Name of the sniff"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Name of the sniff"
 >
 ```
 
 If your IDE or editor supports automatic validation of XML files, you will be notified if your documentation XML file has the correct number of elements, correct type and number of certain attributes, and title length among other things.
 
 #### Validating your docs against the XSD
 
-You can validate your PHPCS XML documentation against the XSD file using [xmllint](https://gnome.pages.gitlab.gnome.org/libxml2/xmllint.html). This validation can be run locally if you have xmllint installed, as well as in CI (continuous integration).
+You can validate your PHPCS XML documentation against the XSD file using [xmllint](http://xmlsoft.org/xmllint.html). This validation can be run locally if you have xmllint installed, as well as in CI (continuous integration).
 
 An example of a workflow job for GitHub Actions CI looks like this:
 
@@ -232,7 +232,7 @@ jobs:
         run: xmllint --noout --schema vendor/phpcsstandards/phpcsdevtools/DocsXsd/phpcsdocs.xsd ./YourRuleset/Docs/**/*Standard.xml
 ```
 
-You'd need to replace the `YourRuleset` with the name of your ruleset of course.
+:point_right: You'll need to replace the `YourRuleset` within the command with the name of your ruleset (of course).
 
 Contributing
 -------