Further small but useful improvements and cleanup

src/schema-gen/InspectorXSLT/Makefile

@@ -40,7 +40,7 @@ unit-test: ## Run all unit tests
 
 
 .PHONY: smoke-test
-smoke-test: ## Run smoke test
+smoke-test: ## Run InspectorXSLT production smoke test
 	$(smoketest_script)
 
 
@@ -50,7 +50,7 @@ refresh-testing: ## Update InspectorXSLT and XSD for test metaschemas (doesn't r
 
 
 .PHONY: xspec
-xspec: ## Run all *.xspec in folder $(folder)
+xspec: ## Run all *.xspec in a designated folder, quietly - use folder=[folder]
 	LOGFILE="$(output_folder)/$(folder)-xspec-tests.log" $(xspec_script) \
 		"baseURI=file:$(module_path)/" \
 		"folder=$(folder)" \

src/schema-gen/InspectorXSLT/readme.md

@@ -19,6 +19,14 @@ The XSLT that is created this way can be used to test XML instances for errors i
 
 That is, it combines the effective functionality of XML schema and Schematron (XPath-based) validation.
 
+## Limitations
+
+Aiming at a complete and conformant implementation for XML of the [Metaschema](https://pages.nist.gov/metaschema) language version 1.0, there are a few known gaps, with a testing framework and protocols now being established both for filling those gaps and for demonstrating the tool's full functionality. Please use the processor with this in mind, that developers and sponsors need your feedback and contributions to enable us to complete the work.
+
+Currently we plan to support only XML-based formats as defined by Metaschema, not their semantically-equivalent JSON or YAML 'cousins'.
+
+Users of Metaschema-defined JSON can try reformatting their data as XML using automated means such as scripts produced by the  [Metaschema XSLT Converter Generators](../../converter-gen). Successful conversion will be valid on the other side. But failures will be indicated not typically be invalid results, and instead results missing those parts of the invalid that went unrecognized by the converter because they are invalid.
+
 ## Demo
 
 The [testing/current](testing/current) directory shows such an XSLT, which can be applied to an instance or set of instances (documents) to be tested against the rules defined by its metaschema - in this case the Computer Model metaschema example provided.

src/schema-gen/InspectorXSLT/testing/refresh-computer-inspector-saxon.sh

@@ -2,7 +2,8 @@
 
 # This script shows how to use Saxon with only a Maven dependency.
 # Unlike other scripts in this folder it does not rely on an external (bash scripting) dependency
-# You do need Maven installed..
+# Another difference is that it bypasses the XSLT-checking, so GIGO - this can be useful (for producing an XSLT for debugging)
+# Maven is required on your system PATH.
 
 # Fail early if an error occurs
 set -Eeuo pipefail
@@ -11,7 +12,7 @@ usage() {
     cat <<EOF
 Usage: $(basename "${BASH_SOURCE[0]}") [ADDITIONAL_ARGS]
 
-Refreshes current/computer_inspector.xsl
+Rewrites current/computer_metaschema-inspector.xsl, without testing (e.g., for testing)
 
 Additional arguments are provided to SaxonHE - see https://www.saxonica.com/documentation11/#!using-xsl/commandline
 EOF