Further fixup to readmes

README.md

@@ -56,19 +56,23 @@ The best way to ensure long-term access to the code base is to clone or fork the
 
 ## Installation and operation
 
-To operate in trial, test or 'bare-bones' mode, scripts are offered to perform operations with no installation except Maven (with JDK as required) and `bash` as a command line environment.
-
-For more regular use or for easier integration (in some contexts), the same functionalities are provided through a `make` interface.
-
-The utilities themselves are designed for integration in a range of environments, and core functionalities are implemented in XSLT 3, which is supported across platforms including Java, Node.js and C. Please deconstruct and reverse engineer. (Consider proposing improvements as [contributions](CONTRIBUTING.md).)
+These utilities are designed for integration in a range of environments, and core functionalities are implemented in XSLT 3, which is supported across platforms including Java, Node.js and C. Please deconstruct and reverse engineer. (Consider proposing improvements as [contributions](CONTRIBUTING.md).)
 
 The software is designed to be used in a range of ways:
 
 - Directly, in development of metaschemas and Metaschema-based software and tools
 - Within Metaschema-based builds, including under CI/CD, to generate artifacts or productions from metaschema source under controlled conditions
 
+The following generalized services are provided by the tools in this repository, separately or in combination
+
+- XSD and JSON schema generation - [`src/schema-gen` folder](src/schema-gen)
+- Converter XSLTs for metaschema-supported data - [`src/converter-gen` folder](src/converter-gen)
+- Metaschema documentation production - [`src/document` folder](src/document).
+
 ### Using `make` utility
 
+Currently we are supporting "smoke testing" and regression testing via `make`. See more details in [src/README.md](src/README.md).
+
 **Work in progress. Please work with us.**
 
 [`make`](https://www.gnu.org/software/make/) is helpful for providing a clean and versatile interface on the command line, with features supporting build management and process dispatching (parallelization). `make` comes pre-installed in many Linux distributions.
@@ -85,27 +89,17 @@ Run directly from script for more transparency, and see the next section for mor
 
 ### Directly from script
 
-The following generalized services are provided by the tools in this repository, separately or in combination
+The `make` support calls scripts that can also be used directly for a more dynamic and versatile interface, for example for developers of new Metaschema instances who wish to generate artifacts or documentation for their metaschemas.
 
-- XSD and JSON schema generation - [`src/schema-gen` folder](src/schema-gen)
-- Converter XSLTs for metaschema-supported data - [`src/converter-gen` folder](src/converter-gen)
-- Metaschema documentation production - [`src/document` folder](src/document).
-
-Recognize the scripts in any of these folders by their `.sh` file suffix. The scripts follow a naming convention, with an initial segment identifying the primary executable invoked by the script (usually `mvn` for Maven); a final segment `xpl` or `xsl` indicating XPoc or XSLT entries, and intermediate segments indicating what the script produces.
-
-For example, `mvn-xsd-schema-xsl.sh` can be run to produce an XSD schema from a metaschema, using an XSLT-based process (i.e., Saxon with an appropriate XSLT transformation), run under Maven.
+[bin/metaschema-xslt](bin/metaschema-xslt) is a top-level `bash` script that dispatches to lower-level scripts for the processes. With the `bin` directory on your path invoke it directly for more help:
 
-Each script also requires arguments, typically the path to the metaschema source (input) file along with a name or keyword directing where to write results. Invoke the script without arguments to get help on its syntax requirements.
-
-Scripts and stylesheets are also documented in place using readmes and in line. Since XSLTs can call, import, include or read XSLTs from elsewhere in the distribution, and sometimes do, keep the modules together: each folder on its own is *not* self-contained.
-
-A good place to start for further research is the `src` directory with [its `readme.md`](src/README.md).
-
-For testing, all XSpec scenarios (`*.xspec`) can be run in place to generate local test reports.
+``
+> bin/metaschema-xslt -h
+```
 
-Users are also expected to call resources in this repository from their own scripts. Do this either by cloning, copying and modifying scripts here; by writing your own scripts or shells; or by adapting code into the XML/XSLT processing framework or stack of your choice.
+#### Dedicated scripts
 
-A convention is used indicating that an XProc (`*.xpl` file) or XSLT (`*.xsl`) intended to be invoked directly (that is, not only to be used as a module or component) is given a name entirely or partly in `ALL-CAPITALS`. For example, `src/schema-gen/METASCHEMA-ALL-SCHEMAS.xpl` is such an XProc pipeline (a step definition intended to be used directly). The XSLTs that observe this convention are, additionally, higher-order transformations by virtue of using the `transform()` function; for all other resources the convention `lower-case-hyphenated` is followed.
+See more details in the [src/README](src/README.md). Using the scripts directly provides more fine-grained access to the logic (for example, if only a single kind of schema output is wanted), while not always offering the same efficiencies.
 
 ### Dependencies
 

src/README.md

@@ -6,21 +6,47 @@ Typically any of these operations will combine several lower-level operations in
 
 ## To run
 
-See each subdirectory README for more instructions, and see the top-level [README](../README.md) for general description of the entry points available, including not only the scripts in each folder but also a global `make` configuration available to any client.
+Also see the [site README](../README.md) for background information.
 
-### `make` quick setup
+### `bash` scripts
 
-This distribution includes [a `make` configuration (script)](bin/metaschema-xslt) enabling access to its runtimes with a simple command line interface. It is not intended as the only means to invoke these processes, but it can be convenient.
+A bash script located in this distribution provides a single unified interface to functionalities provided by this library. Add [../bin](../bin) to your path, or invoke the script directly for help:
 
-Confirm you have [`make`](https://www.gnu.org/software/make/), or install it. Add the [bin](../bin)`../bin` directory in this repository (distribution) to your system path.
+```
+> path/to/bin/metaschema-xslt -h
+```
+
+The help message includes a list of the supported subcommands, indicating which processes are to be run on given inputs with a particular configuration. (If provided with no arguments, the script returns an error `Error: SUBCOMMAND not specified` along with the same help.) Typically scripts use Maven and rely on it for dependency management.
+
+See each subdirectory README for more instructions.
+
+#### Dedicated scripts
+
+Within any of the subdirectories in `src`, recognize the scripts by their `.sh` file suffix. The scripts follow a naming convention, with an initial segment identifying the primary executable invoked by the script (usually `mvn` for Maven); a final segment `xpl` or `xsl` indicating XPoc or XSLT entries, and intermediate segments indicating what the script produces.
+
+For example, `mvn-xsd-schema-xsl.sh` can be run to produce an XSD schema from a metaschema, using an XSLT-based process (i.e., Saxon with an appropriate XSLT transformation), run under Maven.
+
+Each script also requires arguments, typically the path to the metaschema source (input) file along with a name or keyword directing where to write results. Invoke the script without arguments to get help on its syntax requirements.
+
+Scripts and stylesheets are also documented in place using readmes and in line. Since XSLTs can call, import, include or read XSLTs from elsewhere in the distribution, and sometimes do, keep the modules together: each folder on its own is *not* self-contained.
+
+A good place to start for further research is the `src` directory with [its `readme.md`](src/README.md).
+
+Users are also expected to call resources in this repository from their own scripts. Do this either by cloning, copying and modifying scripts here; by writing your own scripts or shells; or by adapting code into the XML/XSLT processing framework or stack of your choice.
+
+A convention is used indicating that an XProc (`*.xpl` file) or XSLT (`*.xsl`) intended to be invoked directly (that is, not only to be used as a module or component) is given a name entirely or partly in `ALL-CAPITALS`. For example, `src/schema-gen/METASCHEMA-ALL-SCHEMAS.xpl` is such an XProc pipeline (a step definition intended to be used directly). The XSLTs that observe this convention are, additionally, higher-order transformations by virtue of using the `transform()` function; for all other resources the convention `lower-case-hyphenated` is followed.
+
+### `make` support
+
+Additionally, some subdirectories include `make` configurations. These are used for testing including regression testing, but may also be used to support processing.
 
-From a command line, test `make`:
+To use `make`, confirm you have [`make`](https://www.gnu.org/software/make/), or install it. In any directory with a Makefile, including this one, test it:
 
 ```
-> path/to/metaschema-xslt/bin/metaschema-xslt
+> src/schema-gen make
 ```
 
-On the console the system will report `Error: SUBCOMMAND not specified`, followed by a list of subcommands you can give.
+The system returns a list of available (configured) targets, typically running tests.
 
 ## Subdirectories