# TF JATS 1.0 to JATS 1.2 Converter

This converter has been created to upgrade files in TF JATS 1.0 format to JATS 1.2 format.

**This is a work in progress. Feedback is appreciated.**

The only requirement is to have a 64-bit version of Java 8 or greater installed and available in the PATH environment variable.

## Usage

To run the conversion:

1. Place one or more TF JATS 1.0 zip files in the folder `files\in`. The TF JATS files should be zipped and named as `*_J.zip` following the TF JATS naming convention.
2. Run `ConvertFiles.cmd`
3. JATS 1.2 files are output to the folder `files\out`

## Developing

To develop on this project:

* Run `BaseX.cmd` to open BaseX, and then open and run `src\xquery\main.xq`
* Open the project file `tfjats1.0-to-jats1.2.xpr` in oXyten XML Editor

This project uses Gradle to automatically run the latest versions (at this time) of BaseX and Saxon. While developing this project, oXygen XML Editor is used for writing XSLT and BaseX GUI is used for writing XQuery.

## The Conversion Process

This section is a somewhat detailed walk through of the code that converts files from TF JATS 1.0 format to JATS 1.2 format.

### bin/ConvertFiles.cmd

This Windows Batch file provides a simple file-based user interface running the converter. For easy usability, any file or folder that is dragged and dropped onto ConvertFiles.cmd is taken as the first parameter and passed to the converter program. The second parameter is a path to a folder for where to place the converted files. Both parameters are optional so that the default 'files/in' and 'files/out' folders are used if no parameter are provided. This Windows Batch file launches the Gradle task "convert"

https://gitlab.com/tfjats/jats1.2/tfjats-to-jats1.2-converter/-/blob/master/bin/ConvertFiles.cmd#L6

### build.gradle

BaseX runs in a Java environment, so we are using Gradle to ensure the correct dependencies are present and launch BaseX. By using Gradle, the only dependency that the user has to worry about is to have Java installed. Gradle provides several benefits which include ensuring correct dependencies are present (i.e. specific versions of BaseX and Saxon), and reducing the Java startup time.

Task "convert" is entry point to run the conversion script. This task is called by ConvertFiles.cmd. The convert task launches BaseX to run convert.xq

https://gitlab.com/tfjats/jats1.2/tfjats-to-jats1.2-converter/-/blob/master/build.gradle#L33

Side note: task "gui" opens the BaseX graphical IDE for development.

### src/convert/convert.xq

convert.xq is the XQuery entry point for the conversion. The first few lines set configuration options, and then the final lines pass the parameters to the module that actually handles the conversion.

The configuration options that are used are documented at these links:

* https://docs.basex.org/wiki/Options#CATFILE
* https://docs.basex.org/wiki/Options#INTPARSE
* https://docs.basex.org/wiki/Options#DTD
* https://docs.basex.org/wiki/Options#CHOP

### src/convert/convert.xqm

The convert.xqm XQuery module contains functions that perform the conversion. The process flow is essentially this:

1. Check the provided folders to find TF JATS zip files
2. Open a TF JATS zip file
3. manipulate contents of the zip file
4. for each Article XML that is present run the article-xml.xsl XSLT transformation
5. if an Issue XML is present run the issue-xml.xsl XSLT transformation
6. Write the new JATS 1.2 zip file

```mermaid
graph TD
  a([Start])-->
  b[For each TF JATS file in the 'in' folder] -->
  c[Open a TF JATS zip file] -->
  d[Manipulate contents of the zip file, e.g. rename or remove certain files ] -->
  e[For each Article XML that is present run the article-xml.xsl XSLT transformation] -->
  f[If an Issue XML is present run the issue-xml.xsl XSLT transformation] -->
  g[Write the new JATS 1.2 zip file] -->
  z([End])
  e-.->e
  z-.->b
```

The convert.xqm module uses BaseX functions for files, zip files, and XSLT that are documented here:

* https://docs.basex.org/wiki/Archive_Module
* https://docs.basex.org/wiki/File_Module
* https://docs.basex.org/wiki/XSLT_Module


### src/convert/xslt/article-xml.xsl

This XSLT transformation converts article XML from TF JATS 1.0 format to JATS 1.2 format. The JATS 1.2 XML that is produced is consistent with our validation rules and tagging guidelines, although this is somewhat dependent upon the quality of the original TF JATS file. This XSLT runs a series of transformation steps in a pipeline, which allows each 

### src/convert/xslt/issue-xml.xsl

This XSLT transformation converts issue XML from TF JATS 1.0 format to the Atypon Issue XML 1.1 format that we are using with JATS 1.2.

### Regression Tests

Each of the XSLT files has a corresponding XSpec. Documentation for XSpec is at https://github.com/xspec/xspec/wiki

The convert.xqm module includes XQuery Unit Tests for several of the functions. Documentation for XQuery Unit Tests is at https://docs.basex.org/wiki/Unit_Module

The folder src/convert/test contains several example input files and corresponding expected output files that are used for regression tests.
