While not all submissions or contributions will always follow all house rules, any violations can be regarded as fair game for correction.
Developers should always observe and follow the rules. Assessors can expect them to be followed, and make judgements accordingly.
For this site, not all rules are enumerated here. To the extent that aligning rules, rule sets and applications is a problem in scope for these projects, they may also have their own ways of addressing them - so consult project readmes and docs.
Anyone working with XML should know and become familiar with the concept that a rules set — whether in the form of a schema, a transformation or query, or other means of interrogationg and filtering — can readily be applied, both in principle and in practice, to an XML document. And any document can be evaluated to any rules set. While the significance of the result of such an exam will vary by the case, the capability of automating and thereby easily replicating and verifying results of such evaluations by means of an open process, is one whose full implications have not yet been explored.
We aim to do that here. Enforcement with a light touch does not mean no enforcement.
See the readme.md, although this should be self-explanatory.
Schematron for checking XProc pipelines is here: testing/xproc3-house-rules.sch.
Please check the testing folder also for Schematrons for other formats including XSpec. Its readme provides more details.
Schematron tests can be applied either interactively, or in CI/CD. Check CI/CD settings.
Additionally, individual projects may provide additional Schematrons enforcing rules and regularities that are considered preconditions for processing there.
PRs supporting any Schematrons are welcome when due diligence has been performed.
Check the .gitignore file for file names to avoid, including especially XSpec result and report formats (HTML and XML), which are generated by automated checks and should not ordinarily be committed to the repository.
Project folders may also have their own .gitignore. Commonly, files downloaded into a project lib may be expected to be excluded, for user curation and maintenance.
-
*.xplis reserved for XProc 3.0 -
*.xprocis available for XProc 1.0
XProc pipelines that function standalone in this repository - with no special runtime arguments - are named with ALL CAPITALS, for example the smoke testing pipeline, POWER-UP.xpl. These can be run by simply calling the pipeline to be executed by the XProc processor.
XProc pipelines with lower-case names are either subpipelines, or meant to be configured at runtime, or both. Use such pipelines either by providing the extra arguments at runtime; using scripts that do so; or writing 'wrapper' pipelines (which may be self-contained and named in all-upper-case).
In XProc, a configuration may include any of:
- Bindings for input ports (named per pipeline)
- Settings for runtime parameters or options (ditto)
- Bindings (directives) for output ports (ditto)
Learn more by researching XProc, looking at examples and trying things out.
For their data sources, XProc pipelines can either read from the Internet (when connected and authorized), from the local file system under user permissions (more commonly), or from inputs provided at runtime using ports on the pipeline(s) invoked.
Likewise, when run they can either write outputs (into the local file system), or expose results on output ports, or both.
Because an XProc does not expose documents on its ports does not mean it does not read and write to the file system, thereby producing 'side effects', by design. Any pipeline or step might do either or both.
A well-designed pipeline will alert its user as to these activities, effects and state changes, using comments in the code, runtime messaging, and logs as appropriate.
It also follows the 'rule of least power' and helps the user to do so. More power is not more good