Reorganize as standalone XSLT app

Organize as standalone application. Update documentation.

Author: wafschneider

.gitignore

@@ -1,5 +1,5 @@
-xsl/bibframe2marc.xsl
-xsl/rules.xml
-xsl/test/xspec/*
-xsl/rules/test/xspec/*
-xsl/rules/test/tests/xspec/*
+bibframe2marc.xsl
+rules.xml
+test/xspec/*
+rules/test/xspec/*
+rules/test/tests/xspec/*

.travis.yml

@@ -17,4 +17,4 @@ env:
     - XSPEC=/tmp/xspec/bin/xspec.sh
     - SAXON_CP=/usr/share/java/Saxon-HE.jar
 
-script: "cd xsl && make test XSPEC=$XSPEC"
+script: "make test XSPEC=$XSPEC"

xsl/Makefile Makefile

@@ -1,11 +1,13 @@
-.PHONY : test_compile test_rules test check clean distclean
+.PHONY : all test_compile test_rules test check clean distclean
 
 XSLTPROC = xsltproc
 XSPEC = xspec.sh
 
 bibframe2marc.xsl : rules.xml
 	$(XSLTPROC) src/compile.xsl rules.xml > bibframe2marc.xsl
 
+all : bibframe2marc.xsl test
+
 rules.xml : $(shell find rules)
 	./buildrules.sh
 

README.md

@@ -1,45 +1,70 @@
-# bibframe2marc
+# bibframe2marc-xsl
 
-Conversion from [BIBFRAME 2.0](http://www.loc.gov/bibframe/) to [MARC21](http://www.loc.gov/marc/).
+XSLT 1.0 conversion from RDF/XML [BIBFRAME 2.0](http://www.loc.gov/bibframe/) to [MARCXML](http://www.loc.gov/marcxml/).
 
-## Background: What goes into a MARC record
+## Introduction
 
-MARC21 bibliographic records can be constructed from an RDF graph with the following characteristics:
+_bibframe2marc-xsl_ consists of an [XSLT 1.0 stylesheet](src/compile.xsl) that takes a set of [XML rules](rules) and compiles them into another stylesheet (bibframe2marc.xsl). The conversion stylesheet takes an RDF/XML document representing a single BIBFRAME 2.0 description and converts it to a MARCXML document. The bibframe2marc.xsl stylesheet can be used as part of a conversion pipeline, as for example with the [Biblio::BF2MARC](https://github.com/lcnetdev/Biblio-BF2MARC) perl library.
 
-* One or more `bf:Instance` subjects with one or more `bf:instanceOf` predicates with a `bf:Work` object.
-  * The `bf:instanceOf` predicate can also be calculated as the inverse of a `bf:hasInstance` predicate of a `bf:Work` subject.
-  * Each `bf:Instance` to `bf:Work` relationship can generate a new MARC record.
-    * A single `bf:Work` can be related to multiple `bf:Instance` nodes. The combination of the predicates of the `bf:Work` and each of the `bf:Instance` nodes can be used to construct multiple unique MARC21 bibliographic records.
-      * Series and linking relationships (e.g. `bf:otherPhysicalFormat`, `bf:reproductionOf`) can be used to infer whether or not a unique MARC21 bibliographic record should be constructed.
-    * A single `bf:Instance` can be related to multiple `bf:Work` nodes, but in general this _should not_ result in the construction of multiple unique MARC21 bibliographic records.
-      * Series and linking relationships should be used to infer which `bf:Work` node should be used in the construction of the record.
-      * If a "primary" `bf:Work` node can not be inferred, multiple records will be constructed.
+## Dependencies
 
-An RDF graph with these characteristics is referred to as a BIBFRAME "description" for simplicity's sake.
+### Build dependencies
 
-This converter takes BIBFRAME descriptions and transforms them into MARC21 records.
+* [libxslt](http://xmlsoft.org/XSLT) -- specifically `xsltproc` -- is used by the root level `Makefile` to construct the `bibframe2marc.xsl` conversion stylesheet from the rules in the [rules](rules) subdirectory. Any XSLT 1.0 processor should be able to build the conversion stylesheet.
 
-## Notes on design
+* [XSpec](https://github.com/xspec/xspec) is the test framework for both the rules compiler and the conversion spreadsheet. It is used by the root level `Makefile` for the `test` targets.
 
-### Conversion wrapper
+* A Java JRE and the Saxon XSLT and XQuery processor are required by XSpec. For more information, see the installation pages on the [XSpec wiki](https://github.com/xspec/xspec/wiki).
 
-* The wrapper script takes an RDF graph of BIBFRAME descriptions and attempts to coerce it into a set of RDF/XML documents with 2 nodes:
-  * `<bf:Instance>`
-  * `<bf:Work>`
-* These nodes refer to each other through the `bf:instanceOf` and `bf:hasInstance` predicates.
-* Objects are dereferenced, so that all the required data is in the RDF/XML documents
-* The wrapper script passes the RDF/XML documents to an XSLT stylesheet for transformation to MARCXML (one at a time).
-* The wrapper script returns a MARC21 collection of bibliographic records in MARCXML.
+## Usage
 
-### XSLT conversion
+### Building
 
-* The XSLT conversion consists of a rules file (in a custom XML format), a stylesheet to transform the rules file into an XSLT stylesheet for use in the wrapper script, and a set of [Xspec](https://github.com/xspec) tests to describe and validate the conversion.
+`make` in the root level of the working directory will create the `bibframe2marc.xsl` conversion stylesheet from the rules in the `rules` subdirectory.
+
+### Using the generated conversion stylesheet (bibframe2marc.xsl)
+
+The `bibframe2marc.xsl` conversion stylesheet is an XSLT 1.0 application that converts a striped RDF/XML document containing a single BIBFRAME 2.0 "description" (defined as an RDF graph composed of two top level nodes that refer to each other, one `bf:Instance` node and one `bf:Work` node) into a MARCXML document. It can be invoked as a standalone application using an XSLT 1.0 processor such as `xsltproc`, or it can be embedded in another application using a library such as `libxslt` for processing, as with the [Biblio::BF2MARC](https://github.com/lcnetdev/Biblio-BF2MARC) perl library.
+
+For more information about what consitutes a BIBFRAME description, see the [design notes](doc/design.md).
+
+The converions stylesheet takes the following parameters:
+
+* `pRecordId` -- an internal system record ID for use (for example) in a MARC 001 control field. If `pRecordId` is not provided, the conversion will use the `generate-id()` function to generate a record ID.
+
+* `pGenerationTimestamp` -- a timestamp for the conversion. If it is not provided, and if the `date:date-time()` function is available, it will be created from the value of `date:date-time()`.
+
+### Using the compiler stylesheet (src/compile.xsl)
+
+The conversion stylesheet is generated from the rules in the `rules` subdirectory by the compiler stylesheet `src/compile.xsl`. You can adapt the sample conversion provided to your own needs, or create your own conversion rules. For more information, see the [conversion rules documentation](doc/rules.md).
+
+To build a conversion stylesheet from a rules file, you can just run the compiler stylesheet with an XSLT 1.0 processor. For example, using `xsltproc`:
+
+```
+xsltproc src/compile.xsl rules.xml > bibframe2marc.xsl
+```
+
+### Tests
+
+The compiler stylesheet has XSpec tests written for it that can be run with `make test_compile` (assuming that XSpec is installed and configured). The tests are in the `tests` subdirectory.
+
+In addition, the rules in the `rules` subdirectory can be tested using XSpec with `make test_rules`. Rules tests are in the `rules/tests` subdirectory.
+
+The `test` target of the Makefile runs both `test_compile` and `test_rules`.
+
+## TODO
+
+* A formal XML schema for the conversion rules still needs to be written
 
 ## Known issues
 
-* The rules compiler in `xsl/src/compile.xsl` uses the `xsl:namespace-alias` element of XSLT to allow for generating a conversion stylesheet. The behavior of this element differs depending on your XSLT processor. libxslt (xsltproc) uses the same namespace prefix in the source stylesheet as the namespace prefix in the output stylesheet, switching the namespace underneath. The Saxon XSLT processor switches out both the namespace prefix and the namespace itself. This results in slightly different output stylesheets -- but the actual BIBFRAME to MARC transformation is exactly the same. `compile.xsl` has been written to work most smoothly with `xsltproc`.
+* The rules compiler uses the `xsl:namespace-alias` element of XSLT to allow for generating a conversion stylesheet. The behavior of this element differs depending on your XSLT processor. libxslt (xsltproc) uses the same namespace prefix in the source stylesheet as the namespace prefix in the output stylesheet, switching the namespace underneath. The Saxon XSLT processor switches out both the namespace prefix and the namespace itself. This results in slightly different output stylesheets -- but the actual BIBFRAME to MARC transformation is exactly the same. `compile.xsl` has been written to work most smoothly with `xsltproc`.
 
 ## See also
 
+* [Issue tracker](https://github.com/lcnetdev/bibframe2marc-xsl/issues) on GitHub
+* [Conversion rules documentation](doc/rules.md)
+* [Design notes](doc/design.md)
+* [Biblio::BF2MARC](https://github.com/lcnetdev/Biblio-BF2MARC) -- a perl library that uses _bibframe2marc-xsl_ for BIBFRAME to MARC conversion
 * The [Bibliographic Framework Initiative](http://www.loc.gov/bibframe/) at the Library of Congress
-* The MARC21 to BIBFRAME conversion tool ([marc2bibframe2](https://github.com/lcnetdev/marc2bibframe2))
+* The MARC to BIBFRAME conversion tool ([marc2bibframe2](https://github.com/lcnetdev/marc2bibframe2))

xsl/buildrules.sh buildrules.sh

@@ -0,0 +1,34 @@
+# bibframe2marc-xsl design notes
+
+_bibframe2marc-xsl_ is designed to be part of a conversion pipeline for converting BIBFRAME RDF descriptions to MARC records. By limiting the scope of the conversion to striped RDF/XML to MARCXML, the main intellectual work of specifying the conversion can be separated from all the mechanics of RDF dereferencing and inference and MARC format conversion, leaving those tasks to a wrapper application.
+
+The schema for constructing conversion rules (see [rules.md](rules.md)) is designed to allow for specifying a conversion based on XPath matching of the RDF/XML document.
+
+## Background: What goes into a MARC record
+
+MARC21 bibliographic records can be constructed from an RDF graph with the following characteristics:
+
+* One or more `bf:Instance` subjects with one or more `bf:instanceOf` predicates with a `bf:Work` object.
+  * The `bf:instanceOf` predicate can also be calculated as the inverse of a `bf:hasInstance` predicate of a `bf:Work` subject.
+  * Each `bf:Instance` to `bf:Work` relationship can generate a new MARC record.
+    * A single `bf:Work` can be related to multiple `bf:Instance` nodes. The combination of the predicates of the `bf:Work` and each of the `bf:Instance` nodes can be used to construct multiple unique MARC21 bibliographic records.
+      * Series and linking relationships (e.g. `bf:otherPhysicalFormat`, `bf:reproductionOf`) can be used to infer whether or not a unique MARC21 bibliographic record should be constructed.
+    * A single `bf:Instance` can be related to multiple `bf:Work` nodes, but in general this _should not_ result in the construction of multiple unique MARC21 bibliographic records.
+      * Series and linking relationships should be used to infer which `bf:Work` node should be used in the construction of the record.
+      * If a "primary" `bf:Work` node can not be inferred, multiple records will be constructed.
+
+An RDF graph with these characteristics is referred to as a BIBFRAME "description" for simplicity's sake.
+
+This converter takes BIBFRAME descriptions and transforms them into MARC21 records.
+
+## Conversion wrapper
+
+A sample application that uses _bibframe2marc-xsl_ is included with the [Biblio::BF2MARC](https://github.com/lcnetdev/Biblio-BF2MARC) perl module.
+
+* The wrapper script takes an RDF graph of BIBFRAME descriptions and attempts to coerce it into a set of RDF/XML documents with 2 nodes:
+  * `<bf:Instance>`
+  * `<bf:Work>`
+* These nodes refer to each other through the `bf:instanceOf` and `bf:hasInstance` predicates.
+* Objects are dereferenced, so that all the required data is in the RDF/XML documents
+* The wrapper script passes the RDF/XML documents to an XSLT stylesheet for transformation to MARCXML (one at a time).
+* The wrapper script returns a MARC21 collection of bibliographic records in MARCXML.