An oXygen Framework for JATS 1.0 and 1.1

Preview stylesheets and transformations

Preview stylesheets capable of rendering Publishing (blue) and Authoring (orange) articles are included from https://github.com/NCBITools/JATSPreviewStylesheets. They are designed for local customization and extension, and include many options, as described in their documentation.

Please note that the documents that may be created and checked with this Literatum framework are essentially Archiving (green) JATS documents. Archiving is the richest of all JATS frameworks. Some elements may not be rendered properly.

${frameworks}/jats/jats-preview-xslt/jats-preview.css

Submission Package Builder

There is an XProc transformation scenario 'build-issue' that operates on an issue-xml file, collects all JATS articles in the same directory and assembles them to a Literatum submission Zip file. This is currently a prototype and needs further development.

Document templates

Document templates are provided only for the Archiving (green) document type, using the HTML table model.

Installating the Framework

In oXygen 16, go to “Help > Install new add-ons…” as depicted in Figure 1.

Figure 1

Menu item “Help > Install new add-ons…” in oXygen 16.1

Enter the update URL https://hobots.hogrefe.com/oXygenJATSframework_Literatum/oXygenJATSframework_Literatum.xml. The most recent version (not necessarily v0.2 as depicted in Figure 2) of the framework will be offered for installation.

Figure 2

Entering the update URL in oXygen 16.1’s “Install Add-ons” dialog

Please note that oXygen version prior to 15.0 are currently not supported. If there is demand, we might be looking into supporting 14.x versions.

It seems as if oXygen versions prior to 17.0 won’t communicate with hobots.hogrefe.com over HTTPS any more. This is probably caused by a new HTTPS certificate on the server that is not approved by any of the certificate authorities listed with the Java version that shipped with older oXygen versions. As a workaround, you could in principle try to run your old oXygen version on a more recent Java version. Or you can instruct oXygen to install the package from another location. In order to avoid HTTPS issues altogether, we decided to provide the package on an HTTP server that Gerrit operates privately. The Add-on URL is http://www.fischer-imsieke.de/gerrit/oXygenJATSframework_Literatum.xml. This is an alternative location that will provide the same package. Use it with oXygen versions 15 or 16.

Figure 3

Warning: Package is not digitally signed

The package is not digitally signed. We might sign it at a later stage. If you trust the people who control the server providing the download link, chances are high that the package hasn’t been tampered with. So press “Continue anyway” (Figure 3)

Using the Framework

After restarting the application, there should be three new document templates in the “Literatum JATS” category when you select “File > New…” from the menu (Figure 4).

Figure 4

New document templates: Issue XML, Literatum JATS article, Literatum JATS 1.1 article (added to the framework 2018-10-08) and submission manifest

If you create a new article with the Literatum_JATS_article template, you will notice the <?xml-model …?> processing instruction right below the XML declaration (Figure 5). This will force the Schematron to be applied. However, this should not be necessary any more because proper document associations seem to be in place & take care of automatic validation. Press Shift-Ctrl-v or the validation button to get a list of validation messages. If you see the messages doubled, remove the xml-model line. Please note that the article template does not pass all Schematron tests. It need to be completed according to the validation messages.

Figure 5

Literatum JATS article template

You also need to fill in the issue template (Figure 6) according to the instructions and the Schematron messages.

Figure 6

Issue XML template

Create the issue workspace in an arbitrary directory. Name the directories within the workspace according to the publisher’s and Atypon’s specifications. The name of the issue directory must match what comes after the slash in the manifest’s group-doi attribute. Place manifest.xml alongside the issue directory. By “issue directory” we mean apf.2017.1000.issue-1 in Figure 7, not the directory issue-files within that issue directory.

Figure 7

Directory layout

When you are done preparing the content, you may select the transformation scenario named “build issue” (Figure 8). It will run for several seconds, depending on the size of your issue directory. It will perform DTD and Schematron validations of all contained XML files. In addition, it will check the directory structure, compliance with the naming conventions, and the presence of referenced files, such as graphics.

Figure 8

Applying the “build issue” transformation

Please note: In the resulting zip file, graphic files will be put in a distinct directory, graphic, for each article. When editing and correcting the articles in the issue directory, however, all images are in the same directory as the XML file. This is ok. Even if you happen to know Atypon’s submission guidelines, don’t try to anticipate the future directory layout of the zip file. The buid script will take care of moving the graphic files to their final destination. This deferred approach allows you to enjoy properly linked images while editing the article.

This package has been configured to run with XML Calabash that has been shipped with oXygen 16. In a more recent version of oXygen, they renamed the “Calabash XProc” processor. It is now (version 20.1) available as “Add-on for Calabash XProc Engine”. If you are using a recent oXygen version, you need to edit the transformation scenario (oXygen asks you if you want to create a copy since it is read-only) and select the Calabash Add-on as XProc processor, as depicted in Figure 8a.

Figure 8a

Modifying a copy of the “build issue” transformation scenario

After the package building has been completed, your browser should display the resulting report, as depicted in Figure 9. Even if you didn’t include the Schematron xml-model processing instruction of Figure 5, all the Schematron checks will be performed on the contained articles. In order to deal with the issues in a more friendly environment, you should insert the xml-model processing instruction into your article (copy it from a newly created article) and act on the messages in oXygen.

Figure 9

Package validation report

We cannot guarantee that the messages make sense in each and every case. Please ask your contacts at the publisher for assistance, or provide them with your valuable feedback.

Extending the Framework

Local developers may wish to do any or all of the following, extending the customization that this Literatum JATS framework already contains:

In addition, there are many enhancements possible to this framework, including (but not limited to)