forked from wendellpiez/JATSKit
-
Notifications
You must be signed in to change notification settings - Fork 2
/
jats-framework-docs.xml
255 lines (252 loc) · 15.1 KB
/
jats-framework-docs.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article
PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.0 20120330//EN"
"JATS-articleauthoring1.dtd">
<article dtd-version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:mml="http://www.w3.org/1998/Math/MathML"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<front>
<article-meta>
<title-group>
<article-title>An oXygen Framework for JATS 1.0 and 1.1</article-title>
<subtitle>With package building support for Atypon’s Literatum platform
and extensive content checking rules</subtitle>
</title-group>
<contrib-group>
<contrib corresp="yes">
<name>
<surname>Imsieke</surname>
<given-names>Gerrit</given-names>
</name>
<aff>le-tex publishing services,
<uri>http://www.le-tex.de/</uri></aff>
</contrib>
<contrib>
<name>
<surname>Piez</surname>
<given-names>Wendell</given-names>
</name>
<aff>Piez Consulting Services,
<uri>http://www.wendellpiez.org/</uri></aff>
</contrib>
</contrib-group>
<abstract>
<p>This is an adaptation of Wendell’s original oXygen XML Editor framework for JATS.
It provides additional Checks for compliance with the submission guidelines for
Atypon’s Literatum platform. In addition, it provides a transformation scenario that
generates JATS XML from legacy APA contentItem articles, and an XProc script to
create a Literatum submission Zip file from a file system directory of articles.</p>
</abstract>
</article-meta>
</front>
<body>
<p>JATS, the journal article tag suite, serves as a basis for Atypon’s Literatum content delivery platform. Articles may be
delivered according to version 1.0 or 1.1 of the JATS archiving (“green”) DTD.
Please consult Atypon’s Literatum Content Tagging Guide [<xref rid="bib-lctg" ref-type="bibr"/>].</p>
<p>A typical delivery to Literatum consists of all articles that belong to a given journal issue. In order to describe the
contents of an issue, Atypon has added a lightweight issue-xml DTD that utilizes JATS vocabulary where available. In
addition to blank templates for journal articles, this framework also contains a template for issue XML. Issue XML files
may be saved alongside the articles that form an issue. A transformation scenario 'build-issue' will then collect all
articles in that directory.</p>
<p>Please note that this framework was created in 2013 and has not been updated with respect to newer Atypon
packaging requirements.</p>
<p>There are Schematron checks for both article and issue XML that help content workers comply with Atypon’s requirements,
such as naming or tagging conventions.</p>
<sec>
<title>Preview stylesheets and transformations</title>
<p>Preview stylesheets capable of rendering Publishing (blue) and Authoring (orange) articles are included from
<ext-link>https://github.com/NCBITools/JATSPreviewStylesheets</ext-link>. They are designed for local customization
and extension, and include many options, as described in their documentation.</p>
<p>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.</p>
<sec>
<title>Transformations generating HTML</title>
<p>HTML files resulting from running these scenarios will point to a CSS file here (distributed with the
XSLT):<preformat>${frameworks}/jats/jats-preview-xslt/jats-preview.css</preformat></p>
</sec>
<sec>
<title>Transformations generating PDF</title>
<p>The Preview stylesheets also include XSL-FO stylesheets for generating PDF. These require a capable XSL-FO formatting
engine (they were tested with AntennaHouse). So they are left for local users to set up.</p>
</sec>
</sec>
<sec>
<title>Submission Package Builder</title>
<p>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.</p>
</sec>
<sec>
<title>Document templates</title>
<p>Document templates are provided only for the Archiving (green) document type, using the HTML table model.</p>
</sec>
<sec>
<title>Installating the Framework</title>
<p>In oXygen 16, go to “Help > Install new add-ons…” as depicted in <xref ref-type="fig" rid="fig-01-install"/>.</p>
<fig id="fig-01-install">
<label>Figure 1</label>
<caption>
<title>Menu item “Help > Install new add-ons…” in oXygen 16.1</title>
</caption>
<graphic xlink:href="img/01-install.jpg"/>
</fig>
<p>Enter the update URL <uri>https://hobots.hogrefe.com/oXygenJATSframework_Literatum/oXygenJATSframework_Literatum.xml</uri>.
The most recent version (not necessarily v0.2 as depicted in <xref ref-type="fig" rid="fig-02-install"/>) of the framework will
be offered for installation.</p>
<fig id="fig-02-install">
<label>Figure 2</label>
<caption>
<title>Entering the update URL in oXygen 16.1’s “Install Add-ons” dialog</title>
</caption>
<graphic xlink:href="img/02-install.jpg"/>
</fig>
<p>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.</p>
<p>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
<uri>http://www.fischer-imsieke.de/gerrit/oXygenJATSframework_Literatum.xml</uri>. This is an alternative location that
will provide the same package. Use it with oXygen versions 15 or 16.</p>
<fig id="fig-03-install">
<label>Figure 3</label>
<caption>
<title>Warning: Package is not digitally signed</title>
</caption>
<graphic xlink:href="img/03-install.jpg"/>
</fig>
<p>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”
(<xref ref-type="fig" rid="fig-03-install"/>)</p>
</sec>
<sec>
<title>Using the Framework</title>
<p>After restarting the application, there should be three new document templates in the “Literatum JATS” category when you
select “File > New…” from the menu (<xref ref-type="fig" rid="fig-04-install"/>).</p>
<fig id="fig-04-install">
<label>Figure 4</label>
<caption>
<title>New document templates: Issue XML, Literatum JATS article, Literatum JATS 1.1 article (added to the framework
2018-10-08) and submission manifest</title>
</caption>
<graphic xlink:href="img/04-install-new.jpg"/>
</fig>
<p>If you create a new article with the Literatum_JATS_article template, you will notice the <monospace><?xml-model
…?></monospace> processing instruction right below the XML declaration (<xref ref-type="fig"
rid="fig-05-article-template"/>). 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.</p>
<fig id="fig-05-article-template">
<label>Figure 5</label>
<caption>
<title>Literatum JATS article template</title>
</caption>
<graphic xlink:href="img/05-article-template.jpg"/>
</fig>
<p>You also need to fill in the issue template (<xref ref-type="fig" rid="fig-06-issue-template"/>) according to the
instructions and the Schematron messages.</p>
<fig id="fig-06-issue-template">
<label>Figure 6</label>
<caption>
<title>Issue XML template</title>
</caption>
<graphic xlink:href="img/06-issue-template.jpg"/>
</fig>
<p>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 <monospace>apf.2017.1000.issue-1</monospace> in <xref ref-type="fig" rid="fig-07-directory-layout"/>, not
the directory <monospace>issue-files</monospace> within that issue directory.
</p>
<fig id="fig-07-directory-layout">
<label>Figure 7</label>
<caption>
<title>Directory layout</title>
</caption>
<graphic xlink:href="img/07-directory-layout.jpg"/>
</fig>
<p>When you are done preparing the content, you may select the transformation scenario named “build issue” (<xref rid="fig-08-build-issue" ref-type="fig"/>).
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.</p>
<fig id="fig-08-build-issue">
<label>Figure 8</label>
<caption>
<title>Applying the “build issue” transformation</title>
</caption>
<graphic xlink:href="img/08-transform-manifest.jpg"/>
</fig>
<p>Please note: In the resulting zip file, graphic files will be put in a distinct directory,
<monospace>graphic</monospace>, 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.</p>
<p>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 <xref
ref-type="fig" rid="fig-08a-copy-xrpoc-scenario"></xref>.</p>
<fig id="fig-08a-copy-xrpoc-scenario">
<label>Figure 8a</label>
<caption>
<title>Modifying a copy of the “build issue” transformation scenario</title>
</caption>
<graphic xlink:href="img/08a-copy-xproc-scenario.jpg"/>
</fig>
<p>After the package building has been completed, your browser should display the resulting report, as depicted in <xref rid="fig-09-report" ref-type="fig"/>.
Even if you didn’t include the Schematron xml-model processing instruction of <xref ref-type="fig" rid="fig-05-article-template"/>,
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.</p>
<fig id="fig-09-report">
<label>Figure 9</label>
<caption>
<title>Package validation report</title>
</caption>
<graphic xlink:href="img/09-package-report.jpg"/>
</fig>
<p>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.</p>
</sec>
<sec>
<title>Extending the Framework</title>
<p>Local developers may wish to do any or all of the following, extending the customization that this Literatum JATS framework already contains:<list>
<list-item>
<p>Rewrite the parameter setting in the HTML Transformation Scenario to point to a local (customized) CSS.</p>
</list-item>
<list-item>
<p>Provide transformation scenarios for any of the JATS Preview transformations or production pipelines given in the
package, or for customized transformations.</p>
</list-item>
<list-item>
<p>Provide templates using the JATS DTDs supporting OASIS tables instead of or in addition to the templates
here.</p>
</list-item>
</list></p>
<p>In addition, there are many enhancements possible to this framework, including (but not limited to)<list>
<list-item>
<p>More and better CSS. In fact, the base JATSKit repository has developed quite a bit since it was forked.
It would be good if this framework incorporated all the changes, but this is not easy due to changes in the
file naming structure etc.</p>
</list-item>
<list-item>
<p>Custom actions, tools and buttons in oXygen for operations useful in writing and editing JATS documents, such as
graphics, list and table support.</p>
</list-item>
</list>If you make such extensions, please consider sharing them with the community!</p>
</sec>
</body>
<back>
<ref-list>
<ref id="bib-lctg">
<mixed-citation><institution>Atypon, Inc.</institution>: <source>Literatum Content Tagging Guide</source> <comment>[URL unknown]</comment></mixed-citation>
</ref>
</ref-list>
</back>
</article>