-
Notifications
You must be signed in to change notification settings - Fork 0
/
technical-docs.xml
590 lines (590 loc) · 36.4 KB
/
technical-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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="xslt/main/jats-html.xsl"?>
<!--<!DOCTYPE article
PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.0 20120330//EN"
"../../DTDs/jats-publishing-dtd-1.0/JATS-journalpublishing1.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>
<journal-meta>
<journal-id>N/A</journal-id>
<issn>N/A</issn>
</journal-meta>
<article-meta>
<title-group>
<article-title>NISO JATS 1.0 Preview Stylesheets: <break/>Technical
Documentation</article-title>
</title-group>
<contrib-group>
<contrib>
<collab>Mulberry Technologies, Inc.</collab>
</contrib>
</contrib-group>
<pub-date>
<year>2012</year>
</pub-date>
</article-meta>
</front>
<body>
<sec>
<title>Introduction</title>
<p>This document provides technical information regarding the HTML and PDF Preview stylesheets
for the NISO Journal Article Tag Suite Publishing 1.0 tag set. (See <ext-link
xlink:href="http://dtd.nlm.nih.gov/publishing/"
>http://dtd.nlm.nih.gov/publishing/</ext-link>.) It is intended for technical users, that
is, personnel responsible for installing, configuring, and maintaining or extending these
stylesheets. For information intended for general users regarding the scope and application of
these stylesheets, see the <italic>Users' Guide</italic> in this distribution. For
instructions on how to run these stylesheets on Journal Publishing content using a basic
configuration, see the <italic>Quick Start Guide</italic>.</p>
<sec>
<title>Copyright and disclaimer information for JATS preview software</title>
<p>The XSL stylesheets and other code (CSS, XProc, and Schematron) provided at the NCBITools/JATSPreviewStylesheets github repository (<ext-link xlink:href="https://github.com/NCBITools/JATSPreviewStylesheets">https://github.com/NCBITools/JATSPreviewStylesheets</ext-link>) is work is in the public domain and may be reproduced, published or
otherwise used without the permission of the National Library of Medicine (NLM).</p>
<p>We request only that the NLM is cited as the source of the work.</p>
<p>Although all reasonable efforts have been taken to ensure the accuracy and
reliability of the software and data, the NLM and the U.S. Government do
not and cannot warrant the performance or results that may be obtained by
using this software or data. The NLM and the U.S. Government disclaim all
warranties, express or implied, including warranties of performance,
merchantability or fitness for any particular purpose.</p>
</sec></sec>
<sec>
<title>General overview</title>
<p>The various tasks performed by stylesheets in this distribution have been distinguished so
they may be mixed and matched to meet specific local requirements, including:</p>
<list>
<list-item>
<p>Generating HTML, PDF, or XHTML output.</p>
</list-item>
<list-item>
<p>Autoformatting structured citation elements <monospace>(element-citation</monospace>)
according to different sets of guidelines (we include stylesheets supporting the
NLM/Pubmed citation style and an APA-like citation style).</p>
</list-item>
<list-item>
<p>Converting OASIS (CALS/Docbook) tables appearing in JATS documents into HTML (for
display or conversion to PDF).</p>
</list-item>
<list-item>
<p>Filtering content based on the values of <monospace>specific-use</monospace> attributes
assigned to elements in the source data.</p>
</list-item>
</list>
<p>These various operations are performed in stages as follows:</p>
<def-list>
<def-item>
<term>Preprocesses</term>
<def>
<p>Preprocesses are all designed to perform operations needed by some processes but not
others, so they can be excluded when not needed. Generally speaking it is possible to
run more than one preprocess, as long as they do not directly conflict with one
another. When they do, it can be expected that the first process in the chain to
handle a particular element or structure in the input will be the one to take
effect.</p>
<p>Some but not all variants of NISO JATS will use OASIS tables instead of HTML tables;
in support of these, a stylesheet to convert OASIS tables into HTML (which is handled
by the main preview stylesheets) is also provided as a pre-process. This is documented
further below.</p>
<p>All preprocessing stylesheets accept arbitrary (valid) JATS Publishing 1.0 XML and
emit the same format: they are "modified identity transformations", whose operations
are limited to a particular subset of elements related to their functional
requirements. (The OASIS tables stylesheet emits the subset of HTML tables used by
JATS and recognized by the main stylesheets. The citation preprocessors accept accept
arbitrary JATS input and produce JATS in "simple citation" form, on which see <xref
rid="simple-citation">below</xref>.)</p>
<p>Because some preprocesses perform operations that are not practically achieved in
modifiable, maintainable XSLT 1.0, they use XSLT 2.0 and require an XSLT 2.0
processor. Others will work in either an XSLT 1.0 or 2.0 processor.</p>
<p>Brief descriptions of each preprocess appear below. Additionally, all stylesheets in
this package are documented internally.</p>
</def>
</def-item>
<def-item>
<term>Main preview processes</term>
<def>
<p>There are two main preview stylesheets in this distribution.
<monospace>jats-html.xsl</monospace> formats JATS Publishing 1.0 in HTML for display
in web browsers.<fn>
<p>Unfortunately, due to tradeoffs forced by discrepancies in their modeling of
block vs inline elements in the Journal Publishing tag set and HTML, not all
results of the HTML preview stylesheet can be guaranteed to be valid HTML. But
none of the known issues have hindered correct rendering in browsers.</p>
</fn>
<monospace>jats-xslfo.xsl</monospace> converts JATS Publishing 1.0 XML into XSL
formatting objects, ready for rendering by an XSL formatting engine into PDF
output.</p>
<p>Both main preview stylesheets accept a filtered form of JATS Publishing 1.0, in which
structured citation elements have been replaced with formatted citations. The
assumption here is that many processes will need to include some form of citation
processing in order to format citations in an appropriate style. For purposes of this
documentation, this filtered form can be called "Simple citation" JATS Publishing 1.0
(it is specified in more detail below). Some projects may have citations that are
already formatted using <monospace>mixed-citation</monospace> elements, which provides
for inline punctuation and hence formatting within the source data. Since all the
citation preprocessors respect punctuation that is already in place, any of them may
be used as the preprocessor in such cases.</p>
<p>If input data should happen already to conform to the "Simple citation" format, a
citation preprocessor may be dispensed with altogether. Some projects may wish to do
this — "unbundling" the citation formatting to manage it up front or by different
means altogether — in order to be able to use a wider range of XSLT processors,
including XSLT processors in web browsers such as Internet Explorer, Firefox or
Safari, to render their previews directly. The main preview stylesheets are
implemented in XSLT 1.0 in order to enable this.</p>
</def>
</def-item>
<def-item>
<term>Post-process</term>
<def>
<p>Some JATS Publishing 1.0 data may include MathML, so the rendering of MathML may be
an issue. The PDF preview stylesheet simply passes MathML through to be rendered by
the formatter; many commercial FO engines now support MathML. On the HTML side,
however, things are more complex since MathML is not supported by generic web browsers
displaying HTML.</p>
<p>Some current browsers now support MathML display in XHTML output. For these purposes,
an HTML to XHTML converter has been provided as a post-process. More details are
provided below.</p>
</def>
</def-item>
</def-list>
<sec>
<title>Stylesheets in this package</title>
<p>While the preview stylesheets in this distribution are intended as fairly comprehensive
solutions, the supporting stylesheets may serve simply as demonstrations of how to achieve
common tasks. Projects should feel free to copy, modify or extend any of them in order to
support local requirements better.</p>
<table-wrap position="anchor">
<label>Summary of stylesheets, dependencies, inputs and outputs</label>
<table frame="hsides" rules="rows" width="100%">
<tr style="font-size:110%; background-color:gainsboro">
<th align="left">Stylesheet</th>
<th align="left">Purpose</th>
<th align="left">Requires</th>
<th align="left">Input format</th>
<th align="left">Output format</th>
</tr>
<tr>
<th colspan="5" align="left">Preprocessors</th>
</tr>
<tr>
<td><monospace>xslt/citations-prep/jats-PMCcit.xsl</monospace></td>
<td>Formats unpunctuated citations according to NLM/Pubmed guidelines</td>
<td>XSLT 1.0</td>
<td>JATS Publishing 1.0</td>
<td>"Simple citation" JATS Publishing 1.0</td>
</tr>
<tr>
<td><monospace>xslt/citations-prep/jats-APAcit.xsl</monospace></td>
<td>Formats unpunctuated citations according to APA guidelines</td>
<td>XSLT 2.0</td>
<td>JATS Publishing 1.0</td>
<td>"Simple citation" JATS Publishing 1.0</td>
</tr>
<tr>
<td><monospace>xslt/prep/jats-webfilter.xsl</monospace></td>
<td>Excludes content with <monospace>specific-use</monospace> = "print-only"</td>
<td>XSLT 1.0</td>
<td>JATS Publishing 1.0</td>
<td>JATS Publishing 1.0</td>
</tr>
<tr>
<td><monospace>xslt/prep/jats-printfilter.xsl</monospace></td>
<td>Excludes content with <monospace>specific-use</monospace> = "web-only"</td>
<td>XSLT 1.0</td>
<td>JATS Publishing 1.0</td>
<td>JATS Publishing 1.0</td>
</tr>
<tr>
<td><monospace>xslt/oasis-tables/oasis-exchange-html.xsl</monospace></td>
<td>Converts OASIS Open tables into HTML</td>
<td>XSLT 2.0</td>
<td>OASIS tables</td>
<td>HTML tables</td>
</tr>
<tr>
<td><monospace>xslt/oasis-exchange-support.xsl</monospace></td>
<td>Provides functionality in support of
<monospace>oasis-exchange-html.xsl</monospace> and
<monospace>oasis-table.sch</monospace> (Schematron)</td>
<td>XSLT 1.0</td>
<td>JATS Publishing 1.0</td>
<td>JATS Publishing 1.0</td>
</tr>
<tr>
<th colspan="5" align="left">Main JATS Publishing 1.0 Preview stylesheets</th>
</tr>
<tr>
<td><monospace>xslt/main/jats-html.xsl</monospace></td>
<td>Formats Journal Publishing data in HTML</td>
<td>XSLT 1.0</td>
<td>"Simple citation" JATS Publishing 1.0</td>
<td>HTML (or XML-wf HTML)</td>
</tr>
<tr>
<td><monospace>xslt/main/jats-xslfo.xsl</monospace></td>
<td>Formats Journal Publishing data as PDF</td>
<td>XSLT 1.0, XSL-FO formatter<xref rid="XSL-FOnote"/></td>
<td>"Simple citation" JATS Publishing 1.0</td>
<td>PDF</td>
</tr>
<tr>
<th colspan="5" align="left">Postprocessor</th>
</tr>
<tr>
<td><monospace>xslt/post/xhtml-ns.xsl</monospace></td>
<td>Converts HTML to XHTML (for support of W3C MathML)</td>
<td>XSLT 1.0</td>
<td>HTML</td>
<td>XHTML</td>
</tr>
<tr>
<th colspan="5" align="left">Saxon shell ("wrapper") stylesheets</th>
</tr>
<tr>
<td><monospace>shells/saxon/jats-APAcit-html.xsl</monospace></td>
<td>Formats Journal Publishing data in HTML with APA-like citations</td>
<td>XSLT 2.0/Saxon</td>
<td>JATS Publishing 1.0</td>
<td>HTML</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-html.xsl</monospace></td>
<td>Formats Journal Publishing data in HTML with NLM/Pubmed citations</td>
<td>XSLT 2.0/Saxon</td>
<td>JATS Publishing 1.0</td>
<td>HTML</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-web-html.xsl</monospace></td>
<td>Formats Journal Publishing data in HTML with NLM/Pubmed citations, excluding
"print-only" content</td>
<td>XSLT 2.0/Saxon</td>
<td>JATS Publishing 1.0</td>
<td>HTML</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-xhtml.xsl</monospace></td>
<td>Formats Journal Publishing data with NLM/Pubmed citations in XHTML (allows for
MathML)</td>
<td>XSLT 2.0/Saxon</td>
<td>JATS Publishing 1.0</td>
<td>XHTML</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-APAcit-xslfo.xsl</monospace></td>
<td>Formats Journal Publishing data as PDF with APA-like citations</td>
<td>XSLT 2.0/Saxon, XSL-FO formatter <xref rid="XSL-FOnote"/></td>
<td>JATS Publishing 1.0</td>
<td>PDF</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-xslfo.xsl</monospace></td>
<td>Formats Journal Publishing data as PDF with NLM/Pubmed citations</td>
<td>XSLT 2.0/Saxon, XSL-FO formatter <xref rid="XSL-FOnote"/></td>
<td>JATS Publishing 1.0</td>
<td>PDF</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-print-fo.xsl</monospace></td>
<td>Formats Journal Publishing data as PDF with NLM/Pubmed citations, excluding
"web-only" content</td>
<td>XSLT 2.0/Saxon, XSL-FO formatter <xref rid="XSL-FOnote"/></td>
<td>JATS Publishing 1.0</td>
<td>PDF</td>
</tr>
<tr>
<td><monospace>shells/saxon/jats-PMCcit-oasis-print-fo.xsl</monospace></td>
<td>Formats Journal Publishing data as PDF with NLM/Pubmed citations and OASIS tables,
excluding "web-only" content</td>
<td>XSLT 2.0/Saxon, XSL-FO formatter <xref rid="XSL-FOnote"/></td>
<td>JATS Publishing 1.0</td>
<td>PDF</td>
</tr>
<tr>
<th colspan="5" align="left">XProc pipelines</th>
</tr>
<tr>
<td colspan="5" align="left">These provide the same conversions under the same names
as the Saxon shells, except with a different suffix (<monospace>xpl</monospace> not
<monospace>xsl</monospace>) since they are XProc pipeline specifications not
(extended) XSLT 2.0 stylesheets. They are all located in the
<monospace>shells/xproc</monospace> subdirectory.</td>
</tr>
</table>
<table-wrap-foot>
<fn-group>
<fn id="XSL-FOnote">
<p>Tested with AntennaHouse 4.3 with MathML support.</p>
</fn>
</fn-group>
</table-wrap-foot>
</table-wrap>
</sec>
</sec>
<sec>
<title>Running the stylesheets</title>
<p>Stylesheets included in this distribution make it possible to run processing pipelines
easily. For various reasons, users and publishers may wish to modify these methods.</p>
<sec>
<title>Using the provided shell stylesheets and pipelines</title>
<p>The easiest way to apply either of the preview stylesheets is to use one of the shell
("wrapper") stylesheets or XProc pipelines. The shell stylesheets can be run with Saxon,
the XSLT 2.0 engine, and rely on Saxon-specific extensions to XSLT 2.0; the XProc
pipelines can be run with any conforming XProc engine that supports XSLT 2.0 stages (no
extensions are needed). Either process applies a set of transformations in sequence
quickly, with a minimum of memory or disk overhead. Each one calls one or the other main
preview stylesheet, with different pre- or postprocessors depending on its intended
application.</p>
<p>The Saxon shell stylesheets provided also depend on the module
<monospace>main/shell-utility.xsl</monospace> to function. This module must be in place,
and its location in relation to the stylesheets named in the shell must be stable, for
things to work.</p>
<p>Because running the XSL-FO Preview stylesheet also entails running an XSL-FO formatter,
there are slightly different considerations in setting things up for each type of
output:</p>
<sec>
<title>HTML preview pipeline</title>
<p>Either from the command line or using an XML editor or XML/XSLT IDE, invoke an XProc
processor with an XProc pipeline, or Saxon with a shell stylesheet, to apply it to a
Journal Publishing 3.0 file or to a subdirectory of such files. If a DTD is referenced
by the file, make sure it is available. Place the results in the location of your
choice. Copy the <monospace>jats-preview.css</monospace> file next to the HTML results.
You are done.</p>
</sec>
<sec>
<title>XSL-FO preview pipeline</title>
<p>Two alternatives are available:</p>
<list>
<list-item>
<p>Configure your XSL-FO engine to run a transformation using an XProc engine or
Saxon, and invoke the transformation from the formatter.</p>
</list-item>
<list-item>
<p>Run the transformation in the same way as when producing HTML, to generate an XML
XSL-FO file that can be processed by the XSL-FO formatting engine.</p>
</list-item>
</list>
<p>The tradeoff is that while the first method requires a (one-time) configuration, it is
easier for the user. It is a common feature of XSL-FO engines to allow configuring them
to use the XSLT transformation engine of your choice.<fn>
<p>The Journal Publishing 3.0 XSL-FO preview stylesheet was tested with the
AntennaHouse XSL formatter, version 4.3. Instructions for configuring AntennaHouse
to use an alternative XSLT processor can be found in their user documentation; the
settings to change are under the <bold>Format / Format Option Setting</bold> menu
option. A tip: test your invocation your processor from the command line first, so
you can paste accurate settings into the dialog box.</p>
</fn></p>
</sec>
</sec>
<sec>
<title>Extending the Saxon shell stylesheet or writing your own</title>
<p>The shell stylesheets included in this package all have the same logic. Stylesheets to be
called in and applied to the source data, in sequence, are named in a variable in the
stylesheet. Inserting or removing components is as easy as changing this variable.</p>
<p>For example, the stylesheet <monospace>jats-PMCcit-xhtml.xsl</monospace> has the variable
<monospace>$processes</monospace> declared as
follows:<preformat position="anchor"><xsl:variable name="processes">
<step>../../xslt/citations-prep/jats-PMCcit.xsl</step>
<step>../../xslt/preview/jats-html-preview.xsl</step>
<step>../../xslt/post/xhtml-ns.xsl</step>
</xsl:variable></preformat>Add
a step to this
declaration:<preformat position="anchor"><xsl:variable name="processes">
<bold><step>../../xslt/prep/jats-webfilter.xsl</step></bold>
<step>../../xslt/citations-prep/jats-PMCcit.xsl</step>
<step>../../xslt/main/jats-html-preview.xsl</step>
<step>../../xslt/post/xhtml-ns.xsl</step>
</xsl:variable></preformat>Now,
an additional preprocess <monospace>prep/jats-webfilter.xsl</monospace> is run before the
citation preprocessing step.</p>
<p>Of course, we recommend copying a shell with a new name and making changes there, in
order to preserve the integrity of files in the distribution.</p>
<p>All paths given are relative to the shell stylesheet's location in the subdirectory
structure.</p>
<p>Note that configuration of the output serialization using the
<monospace>xsl:output</monospace> instruction is designated by the shell stylesheet.
Accordingly, a shell stylesheet intended to generate plain HTML might have
<monospace>method="html"</monospace> indicated in its <monospace>xsl:output</monospace>,
while a shell stylesheet generating XHTML should have
<monospace>method="xhtml"</monospace>.</p>
</sec>
<sec>
<title>Extending an XProc pipeline or writing your own</title>
<p>Of course, the same possibilities are available when using XProc, with many more. For
example an XProc pipeline could included DTD or Schematron validation along with
processing of documents (or only of valid documents, if preferred), processing sets of
documents together, etc.</p>
<p>XProc is a W3C-standard XML process pipelining technology, documented on line.</p>
</sec>
<sec>
<title>Designing and running your own pipeline</title>
<p>If you don't want to use XProc or rely on the XSLT extensions supported by Saxon, you can
build your own pipelines to apply the stylesheets, using the framework of your choice.
Shell scripts, batch files, scripting languages, and build tools such as Unix
<monospace>make</monospace> or Apache Ant can all be used for this purpose. The
principle is simple: each step in the pipeline generates results that are taken as the
input for the next step in the pipeline. Serialization may follow each step (if each
pipeline reads its input from the file system) or may be performed only after the last
step (if steps are connected using event streams or if intermediate results are held in
memory).</p>
<p>Keep in mind that an XSLT engine will still be required to run the separate steps, and
that several of the stylesheets provided do require an XSLT 2.0 processor.</p>
</sec>
<sec>
<title>Running without a pipeline</title>
<p>The stylesheets can also be run individually, without any pipeline automation at all,
just by applying preprocessor stylesheets to the input, if needed, and then applying the
appropriate main preview stylesheet to the output from the preprocessors.</p>
<p>For input that contains no bibliographic citations, or in which all the bibliographic
citations are pre-formatted and conform to the "simple citation" format defined <xref
rid="simple-citation">below</xref>, no preprocessors are necessary and the main preview
stylesheet can be run standalone in any XSLT 1.0 or 2.0 processor (including client-side
web browsers or other XSLT-capable display engines). </p>
<p>Note, however, that most JATS input that contains any citations at all will benefit from
being passed through one of the citation preprocessors, even if all the citations in the
input are <monospace>mixed-citation</monospace> and have the appropriate punctuation: the
main preview stylesheets work best if the only elements within citations in the input are
presentation-oriented elements; the preprocessors strip out all other elements inside of
citations, and replace them with appropriate presentation-oriented markup. </p>
</sec>
</sec>
<sec>
<title>Tweaks and extensions to the main preview stylesheets</title>
<p>These stylesheets provide for basic formatting of Journal Publishing data for preview; they
are not designed to serve as production stylesheets. Their functionality can be extended or
modified, however.<fn>
<p>The overall architecture of this stylesheet suite, with coverage of approaches to
customizing it, was described in a paper at JATS-Con 2010. A written version is online
at <ext-link>http://www.ncbi.nlm.nih.gov/books/NBK47104/</ext-link>.</p>
</fn> It is recommended that modifications make use of the XSLT import mechanism: write your
modified templates in a separate stylesheet module that imports the main stylesheet module.
The modifications can then be maintained separately in one place.</p>
<sec>
<title>CSS stylesheet</title>
<p>HTML results are generated with a link to <monospace>jats-preview.css</monospace>, given
as a relative path that expects the named file to be in the same subdirectory as the HTML
result file (or the XML source file if it is processed directly in a browser).</p>
<p>This can be altered at runtime by overriding the value of the <monospace>css</monospace>
parameter supplied to the main HTML Preview stylesheet. This allows a CSS stylesheet with
another name to be used or a stylesheet to be located elsewhere. If an empty string is
provided, the HTML results will have no link to an external CSS.</p>
<p>Of course, altering <monospace>jats-preview.css</monospace> or providing your own CSS
stylesheet is an easy way to alter the look and feel of output without editing any XSLT.
Many of the basic settings in the HTML presentation, including fonts, rules, colors
(including the colors of warnings and generated text) may be customized in this way.</p>
</sec>
<sec>
<title>Enabling autonumbering in the XSLT</title>
<p>As described in the <italic>Users' Guide</italic>, the Preview stylesheet does not
generate labels with automatic numbering for elements in presentation, except the
<monospace>fn</monospace> and <monospace>ref</monospace> elements as described there.
However, the stylesheets are provided with variables that can be used as switches to turn
on autonumbering, along with templates that can be modified (or overridden, in a
customization layer) in order to control the formats of the numbers. See the stylesheets,
especially the templates in mode <monospace>label-text</monospace>.</p>
</sec>
</sec>
<sec>
<title>Support of OASIS tables</title>
<p>A conversion stylesheet is included in this distribution for converting OASIS Exchange XML
tables, as specified in <ext-link xlink:href="https://www.oasis-open.org/specs/tm9901.html"
>OASIS Technical Memorandum TR 9901:1999</ext-link>, into the subset of HTML tables used
by JATS. This is in order that JATS variants using OASIS tables may also use these preview
stylesheets; but the OASIS conversion logic will work on any data containing OASIS tables
(in the namespace
<monospace>http://docs.oasis-open.org/ns/oasis-exchange/table</monospace>), making them into
HTML equivalents (not namespace-qualified). As with other components of this distribution,
developers are free to extend and modify this stylesheet and to integrate it into their
systems.</p>
<p>This module is designed so it can be imported into another (XSLT 2.0) stylesheet, although
in this distribution it is presented as a separate pipeline step. (This is in order that the
main preview stylesheets may still use XSLT 1.0, for the broadest possible support.)
Developers familiar with the architecture of XSLT may wish to integrate it more tightly by
calling it into another stylesheet (using <monospace>xsl:import</monospace>) instead of
using it as a separate step.</p>
<p>In addition, this distribution also includes a Schematron schema for use with OASIS tables,
which must be checked against constraints over and above validity to a DTD or schema. This
Schematron will ensure that tables are "square" (rows and columns are all filled, allowing
for implied table cells, row and column spanning etc.), that attributes are given
consistently, and so forth. Since some analytic operations are provided using XSLT
stylesheet functions, this Schematron requires a processor that permits foreign elements (in
this case, XSLT elements) to be present.</p>
</sec>
<sec id="simple-citation">
<title>Specification of "simple citation" NISO JATS 1.0</title>
<p>Projects that wish to dispense with automated formatting of citations, to extend the
automated processing provided, or to develop their own citation formatting logic, will need
to know the subset of Journal Publishing 3.0 that can be reliably converted by the preview
stylesheets. This profile introduces additional constraints on elements related to
bibliographic citations: <monospace>element-citation</monospace>,
<monospace>nlm-citation</monospace>, <monospace>mixed-citation</monospace> and their
children (as well as the analogous <monospace>citation</monospace> element in NLM v2.3),
along with the related elements <monospace>product</monospace>,
<monospace>related-article</monospace> and <monospace>related-object</monospace>.</p>
<list>
<list-item>
<p><monospace>element-citation</monospace> and <monospace>nlm-citation</monospace> are not
recognized or processed specially. A preprocessor should convert them into
<monospace>mixed-citation</monospace>, providing their contents with punctuation in
the process. (This is what the packaged citation preprocessors do.) If these elements
appear, preview stylesheets will present them without formatting.</p>
</list-item>
<list-item>
<p>Along with literal text (including punctuation), the following elements are recognized
inside <monospace>mixed-citation</monospace>, <monospace>product</monospace>,
<monospace>related-article</monospace> and <monospace>related-object</monospace>:<disp-quote>
<p><monospace>bold</monospace>, <monospace>italic</monospace>,
<monospace>monospace</monospace>, <monospace>overline</monospace>,
<monospace>roman</monospace>, <monospace>sans-serif</monospace>,
<monospace>sc</monospace>, <monospace>strike</monospace>,
<monospace>underline</monospace>, <monospace>inline-graphic</monospace>,
<monospace>label</monospace>, <monospace>email</monospace>,
<monospace>ext-link</monospace>, <monospace>uri</monospace>,
<monospace>sub</monospace>, <monospace>sup</monospace>,
<monospace>styled-content</monospace></p>
</disp-quote></p>
</list-item>
<list-item>
<p>The following elements are permitted in citation elements in Journal Publishing 3.0,
but are <italic>excluded</italic> from the simple citation profile. A preprocessor
should strip them from content or convert them into presentation-oriented elements
(listed above), with appropriate punctuation, according to the rules of the chosen
citation format. If they appear, these element can be expected to be processed by a
preview stylesheet according to default rules, which generally means their content will
appear with no formatting consequences:<disp-quote>
<p><monospace>abbrev</monospace>, <monospace>alternatives</monospace>,
<monospace>annotation</monospace>, <monospace>article-title</monospace>,
<monospace>chapter-title</monospace>, <monospace>chem-struct</monospace>,
<monospace>collab</monospace>, <monospace>comment</monospace>,
<monospace>conf-date</monospace>, <monospace>conf-loc</monospace>,
<monospace>conf-name</monospace>, <monospace>conf-sponsor</monospace>,
<monospace>date</monospace>, <monospace>date-in-citation</monospace>,
<monospace>day</monospace>, <monospace>edition</monospace>,
<monospace>elocation-id</monospace>, <monospace>etal</monospace>,
<monospace>fpage</monospace>, <monospace>gov</monospace>,
<monospace>inline-formula</monospace>, <monospace>institution</monospace>,
<monospace>isbn</monospace>, <monospace>issn</monospace>,
<monospace>issue</monospace>, <monospace>issue-id</monospace>,
<monospace>issue-part</monospace>, <monospace>issue-title</monospace>,
<monospace>lpage</monospace>, <monospace>milestone-end</monospace>,
<monospace>milestone-start</monospace>, <monospace>month</monospace>,
<monospace>name</monospace>, <monospace>named-content</monospace>,
<monospace>object-id</monospace>, <monospace>page-range</monospace>,
<monospace>part-title</monospace>, <monospace>patent</monospace>,
<monospace>person-group</monospace>, <monospace>private-char</monospace>,
<monospace>pub-id</monospace>, <monospace>publisher-loc</monospace>,
<monospace>publisher-name</monospace>, <monospace>role</monospace>,
<monospace>season</monospace>, <monospace>series</monospace>,
<monospace>size</monospace>, <monospace>source</monospace>,
<monospace>std</monospace>, <monospace>string-name</monospace>,
<monospace>supplement</monospace>, <monospace>trans-source</monospace>,
<monospace>trans-title</monospace>, <monospace>volume</monospace>,
<monospace>volume-id</monospace>, <monospace>volume-series</monospace>,
<monospace>year</monospace></p>
</disp-quote></p>
</list-item>
</list>
</sec>
</body>
</article>