-
Notifications
You must be signed in to change notification settings - Fork 34
/
userguide.xml
837 lines (837 loc) · 56.9 KB
/
userguide.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
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
<?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>Users' Guide for the NISO JATS 1.0 Preview Stylesheets</article-title>
<alt-title alt-title-type="running-head">NISO JATS 1.0 Preview Stylesheets: Users'
Guide</alt-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>The NISO JATS 1.0 Preview Stylesheets package includes stylesheets that produce formatted
previews of documents encoded in XML using the NISO JATS (Journal Article Tag Suite)
vocabulary. Previews in both HTML and PDF format (via XSL-FO) are supported. Most generic
Journal Publishing structures are supported, subject to the assumptions and limitations
described in this document.</p>
<p>The primary purpose of the stylesheets is to support version 1.0 of the Publishing ("blue")
tag set of NISO JATS, but they will also work on data valid to the related tag sets JATS 1.0
Authoring ("orange") and NLM Journal Publishing ("blue") or Authoring ("orange") versions
2.3 and 3.0.</p>
<p>The documentation included in this package, namely this <italic>Users' Guide</italic>, the
<italic>Quick Start Guide</italic>, and the <italic>Technical Documentation</italic>, can
serve as examples of the tagging style supported; they are all encoded in NISO JATS
Publishing XML, with HTML and PDF presentation versions generated using the preview
stylesheets.</p>
<p>Assuming the user already has valid JATS (Publishing) 1.0 data, the most important
consideration regarding application of these stylesheets regards the format of bibliographic
citation information in the input and the bibliographic format desired for those citations
in the output. Citations tagged using <monospace>mixed-citation</monospace> and provided
with appropriate punctuation in the input (called here "formatted citations") are handled
correctly by the stylesheets in this package. Citations tagged without punctuation, using
<monospace>element-citation</monospace> ("unformatted citations") can also be handled:
this distribution includes stylesheets which format such citations in the user's choice of
two formats: NLM/Pubmed, and APA.</p>
<p>In addition, this package also demonstrates how pre- and post-processing steps connected
together in pipelines may achieve other processing goals, both preview and production. These
include processing OASIS (CALS) tables and handling tagging intended to optimize outputs for
different media (such as web and print).</p>
<p>For a more precise description of the technical dependencies of these stylesheets, along
with documentation of alternative ways to deploy and apply them and of how to extend and
modify them, users should consult the <italic>Technical Documentation</italic>. That
document also includes a fuller specification of the formatted and unformatted citation
formats supported by this package.</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>Getting started</title>
<p>To select which stylesheet to use, you will first need to determine the following:<list
list-type="order">
<list-item>
<p>If you have unformatted citations in your input, do you want the output to be in
NLM/Pubmed format or APA format? (These are the only formats these stylesheets can
produce from unformatted citations in the input.)</p>
<p>If all the citations in the input are formatted, you can use either the NLM/Pubmed or
the APA stylesheets and pipelines mentioned below.</p>
<p>If you have no citations or if your citations contain only simple inline tagging with punctuation,<fn>
<p>As described in the <italic>Technical Documentation</italic> under "Simple
citation" format.</p>
</fn> you can forego citation formatting altogether.</p>
</list-item>
<list-item>
<p>Do you want HTML (with CSS), or PDF?</p>
</list-item>
<list-item>
<p>Which of the following methods do you prefer to use for processing the input? <list>
<list-item>
<p>An XProc (XML Pipelining) processor such as XML Calabash?</p>
<p>If using XProc, you will select a pipeline specification from the
<monospace>shells/xproc</monospace> subdirectory.</p>
</list-item>
<list-item>
<p>A copy of Saxon that supports the necessary extension functions?<fn
id="saxon-versions">
<p>Since version 9.2, the open-source version of Saxon (Saxon HE) does not
support the needed extension function, so you will need Saxon PE or EE.
Before version 9.2, the extension functions required by the Saxon shell
stylesheets was available in versions of Saxon back to 8.9.</p>
</fn></p>
<p>If using Saxon, you will select a shell stylesheet from the
<monospace>shells/saxon</monospace> subdirectory.</p>
</list-item>
<list-item>
<p>A different XSLT processor?</p>
<p>Only the Saxon pipelines require Saxon; the stylesheets themselves will work in
any conformant XSLT processor. Many of the stylesheets are in XSLT 1.0 and will
work in a 1.0 processor (or 2.0) processor; some require XSLT 2.0.<fn>
<p>Consult the <italic>Technical Documentation</italic> for details on which
stylesheets require XSLT 2.0. (Apart from the Saxon shell stylesheets, most
do not.)</p>
</fn> You can run pipelines either "by hand" (run several stylesheets each on
the results of the previous one) or using a custom-built pipelining method
(shell or batch script, Java Ant, <monospace>make</monospace>, etc.). If you
don't need to run a pipeline, you can also run XSLT 1.0 stylesheets (such as the
HTML Preview stylesheet) in a web browser that supports XSLT 1.0.</p>
</list-item>
</list></p>
</list-item>
<list-item>
<p>To make HTML:</p>
<list>
<list-item>
<p>If NLM/Pubmed style should be used to render unformatted citations in the input,
you will use <monospace>shells/xproc/jats-PMCcit-html.xpl</monospace> or
<monospace>shells/saxon/jats-PMCcit-html.xsl</monospace>.</p>
<p>If you are running without Saxon or XProc, you will first apply
<monospace>xslt/citations-prep/jats-PMCcit.xsl</monospace> to your input, and
then apply <monospace>xslt/main/jats-html.xsl</monospace> to the output of the
first transformation. </p>
</list-item>
<list-item>
<p>If APA style should be used for unformatted citations in the input, you will use
<monospace>shells/xproc/jats-APAcit-html.xpl</monospace> or
<monospace>shells/saxon/jats-APAcit-html.xsl</monospace>. Since the APA citation
style transformation requires XSLT 2.0, you will need an XSLT 2.0 processor to run
it without Saxon or XProc. </p>
</list-item>
<list-item>
<p>If all citations in the input are formatted, you can use either the NLM/Pubmed or
the APA pipeline; if they use only simple inline tagging, you can use
<monospace>xslt/main/jats-html.xsl</monospace> without pipelining.<fn
id="simple-citation">
<p>See the <italic>Technical Documentation</italic> on these stylesheets'
specification of a "Simple Citation" format for more information on what
tagging in citations will be handled by default, without customization.</p>
</fn></p>
</list-item>
</list>
</list-item>
<list-item>
<p>To make PDF:</p>
<list>
<list-item>
<p>To generate NLM/Pubmed style citations from unformatted citations in the input,
XProc users will use
<monospace>shells/xproc/jats-PMCcit-xslfo.xpl</monospace>.</p>
<p>Saxon users will use
<monospace>shells/saxon/jats-PMCcit-xslfo.xsl</monospace>.</p>
<p>XSLT 1.0 users will use
<monospace>xslt/citations-prep/jats-PMCcit.xsl</monospace> followed by
<monospace>xslt/main/jats-xslfo.xsl</monospace>. </p>
</list-item>
<list-item>
<p>To generate APA-style citations from unformatted citations in the input, XProc
users will use <monospace>shells/xproc/jats-APAcit-xslfo.xpl</monospace>.</p>
<p>Saxon users will use
<monospace>shells/saxon/jats-APAcit-xslfo.xsl</monospace>.</p>
<p>XSLT 2.0 users will use
<monospace>xslt/citations-prep/jats-APAcit.xsl</monospace> followed by
<monospace>xslt/main/jats-xslfo.xsl</monospace>. </p>
<p>XSLT 1.0 users cannot produce APA-style citations automatically, since the first
of these stylesheets relies on XSLT 2.0. </p>
</list-item>
<list-item>
<p>If all citations in the input are formatted, either of the the NLM or the APA
pipelines can be used, or <monospace>xslt/main/jats-xslfo.xsl</monospace> alone
can be used if they are formatted with simple inline tagging.<xref
rid="simple-citation"/></p>
</list-item>
</list>
</list-item>
</list>Then:<list list-type="order">
<list-item>
<p>Apply the stylesheet(s) or pipeline to a valid Journal Publishing 3.0 document, or a
subdirectory of such documents, using the tool of your choice.</p>
<p>When you run your pipeline, messages may be echoed to your console reporting on
progress. Do not be concerned by warning messages stating that you are running an XSLT
1.0 stylesheet with a 2.0 processor. These stylesheets will run in XSLT "backward
compatibility mode", and have been designed to work properly with either 1.0 or 2.0
processors.</p>
</list-item>
<list-item>
<p>When the result format is HTML, copy <monospace>jats-preview.css</monospace> to the
file system next to the result file(s).</p>
</list-item>
<list-item>
<p>When the result format is XSL-FO, run the result file in an XSL-FO formatter,
according to its instructions.</p>
<p>Many XSL-FO formatters allow running an XSLT transformation directly to apply a
stylesheet to a document. If you wish to do this and you are using one of the shell
stylesheets provided, see to it that your formatter invokes the correct processor
(such as Saxon or an XProc engine) as its XSLT component.</p>
</list-item>
</list></p>
</sec>
<sec>
<title>Advanced options</title>
<p>In addition to the straightforward application of formatting to Journal Publishing content
using either of the supported bibliographic citation styles, this suite of stylesheets
supports a number of advanced options. While these can be used "out of the box", they are
also included as demonstrations of how processes may be further tailored and customized to
meet local requirements.</p>
<p>In order to learn more, see the section on <xref rid="special-purpose">Special-purpose
stylesheets</xref> below, along with the <italic>Technical Documentation</italic>.</p>
</sec>
<sec id="citations-sec">
<title>Assumptions made by the preview processing</title>
<p>These stylesheets are designed to handle a broad range of inputs, generally requiring only
that input data be XML valid to the NLM/NCBI Journal Publishing 3.0 DTD. Inevitably,
however, there are limitations in their handling of of variant patterns of tagging and of
structures that are valid but unlikely and/or poorly controlled by a schema.</p>
<p>Caution: while these stylesheets do their best to handle "normal" input, <italic>they
should not be taken as an indicator of a norm</italic>. "Variant" here does not
necessarily mean "incorrect", and where local practice has evolved to meet particular local
processing requirements, these stylesheets may <italic>and should</italic> be altered or
extended to accommodate local practice and requirements.</p>
<p>The remainder of this section outlines the main limitations of the stylesheets and the
major assumptions they make about their input, grouping the entries into sections on <xref
rid="limits">known limitations</xref>; <xref rid="autonumbering">autonumbering, labels,
and cross-references</xref>; and <xref rid="citations">citations</xref>.</p>
<sec id="limits">
<title>Known limitations of these stylesheets</title>
<p>Users should keep in mind that any and all of these behaviors and limitations (as well as
those not described) can be addressed directly in customizations of these stylesheets;
they are not inherent in XSLT (although sometimes the target format, HTML or XSL-FO,
presents challenges), but only a result of the design requirement that the Preview
stylesheets address the broadest possible set of "reasonable" approaches to tagging NISO
JATS, without privileging any in particular.</p>
<sec>
<title>Running page headers</title>
<p>The PDF preview stylesheet generates running headers using the main article title
(<monospace>article-title</monospace> inside
<monospace>article-meta/title-group</monospace>). If the main article title is too
long, an alternative title can be provided for the page header; if available, an
<monospace>alt-title</monospace> with <monospace>alt-title-type</monospace> of
'running-head' will be used.</p>
</sec>
<sec>
<title>Super- and subscripting limitations</title>
<p>On <monospace>sub</monospace> and <monospace>sup</monospace> elements the
<monospace>arrange</monospace> attribute is not supported in either preview. All
instances will be treated as <monospace>arrange='stagger'</monospace>.</p>
</sec>
<sec>
<title>Addresses</title>
<p>The document model allows addresses (the <monospace>address</monospace> element) both
as structured elements and within inline content such as paragraphs.</p>
<p>Address elements inside <monospace>aff</monospace> (affiliation) are always formatted
in line.</p>
<p>If the address contains no <monospace>address-line</monospace> elements
<italic>and</italic> it appears in paragraph content (that is, directly within
<monospace>p</monospace>, <monospace>license-p</monospace>,
<monospace>collab</monospace>, <monospace>named-content</monospace> and
<monospace>styled-content</monospace> elements), then it is formatted in line. </p>
<p>Otherwise, the address is formatted as blocks broken into separate lines, one for each
element in the address.</p>
</sec>
<sec>
<title>Sub-articles</title>
<p>The HTML preview stylesheet includes code for handling sub-articles, including the
elements <monospace>sub-article</monospace> and <monospace>response</monospace>. Because
the Journal Publishing tag set allows a wide range of ways to deploy and manage such
content, particularly with respect to metadata and ancillary materials such as
references and footnotes, these features have not been fully tested. If you have
<monospace>sub-article</monospace> or <monospace>response</monospace> content,
extending one or both stylesheets in view of your particular tagging patterns and
requirements will probably be necessary.</p>
</sec>
<sec>
<title>Section metadata</title>
<p>The same thing is true of section-level metadata (<monospace>sec-meta</monospace>),
particularly with respect to the <monospace>contrib-group</monospace> element inside
<monospace>sec-meta</monospace>. </p>
<p>Also, within <monospace>sec-meta</monospace> in the PDF preview, only simple keywords
(<monospace>kwd</monospace>) within <monospace>kwd-group</monospace> will be rendered;
<monospace>compound-kwd</monospace> is ignored by these stylesheets.</p>
<p>Test the stylesheets against your content and be prepared to amend the stylesheets, if
necessary.</p>
</sec>
<sec>
<title>Special characters</title>
<p>These stylesheets do not support the <monospace>private-char</monospace>,
<monospace>glyph-data</monospace>, or <monospace>glyph-ref</monospace> elements.</p>
</sec>
<sec>
<title>Graphics</title>
<p>Graphics are not resized in the HTML preview, but displayed at native resolution; this
may result in disproportionately large images when the images have been made large to
give them higher resolution. In the PDF preview, images will be scaled down (as
necessary) to fit in available space.</p>
<p>In the HTML preview, graphics are expected to be located as given in the source data
relative to the HTML <italic>result</italic> file. So, if source data has a graphic with
<monospace>xlink:href='snapshots/babypic.jpg'</monospace>, the result file will link
to 'snapshots/babypic.jpg'. If graphic files are maintained relative to the source data,
they should either be copied to the same location relative to the result, or else an
absolute path to the graphic should be given as the value, or (most simply) the HTML
result file should be placed next to the XML source file, in order to ensure that
graphics will be visible in the browser.</p>
<p>In the PDF preview, a runtime parameter, <monospace>base-dir</monospace>, must be given
to identify the directory relative to which graphics are located. If the XSL process is
initiated using one of the provided XSLT 2.0 shell stylesheets, this parameter will be
provided automatically as the base directory of the source file, so graphics should be
located relative to the source data. If no parameter is given, then either graphics must
be designated with absolute path names, or else they must be located relative to the
<italic>stylesheet</italic>.</p>
<p>Alternative text provided as <monospace>alt-text</monospace> on graphics is not
rendered in the PDF preview.</p>
</sec>
<sec>
<title>Styled content and the HTML <monospace>style</monospace> attribute</title>
<p>The Journal Publishing document model makes provision for styling content directly by
using CSS styles, either associated with table elements (HTML table elements in this
model) or as the value given the <monospace>style</monospace> attribute of the
<monospace>styled-content</monospace> inline element.</p>
<p>When this appears, the HTML preview stylesheet will simply pass the values through.
Results will depend on the level of CSS conformance in the browser and in the CSS values
passed through to the output.</p>
<p>In the PDF preview, <monospace>width</monospace> and
<monospace>vertical-align</monospace> values associated with tables are mapped to
formatting in the result. On any element with the <monospace>style</monospace>
attribute, values of the following properties are mapped: <monospace>color</monospace>;
<monospace>background-color</monospace>; <monospace>font-size</monospace>;
<monospace>font-weight</monospace>; <monospace>font-style</monospace>;
<monospace>font-family</monospace>; <monospace>text-decoration</monospace>. Note that
incorrect CSS values may result in errors when XSL-FO stylesheet results are
formatted.</p>
<p>Note in particular that CSS properties related to borders are not supported in the PDF
preview. For table cell borders, some bordering behavior can be specified using
attributes on the <monospace>table</monospace> element.</p>
</sec>
<sec>
<title>Floating objects and the <monospace>position</monospace> attribute</title>
<!--* MSM thinks the following paragraph needs revision.
* But he can't revise it, because he doesn't think he
* understands it. (That's why he thinks it needs revision.)
*-->
<p>In the parlance of document markup, "floating" can refer to two distinct things. If a
rendering application is trusted, at runtime, to determine (and presumably optimize) the
precise position on the page of an object, this object is said to "float". A figure, for
example, may be allowed to float, while a graphic appearing in a paragraph is not (it is
anchored to its place in the flow of text); similarly a boxed text may be allowed to
float, or it may be anchored, depending on whether its exact placement on the page is
important to its meaning. But the term is also used to refer to objects (such as figures
and tables) that are encoded in the source data -- but not necessarily rendered -- apart
from the flow of the text, typically by gathering them into a group at the end of the
document. Such "floating" objects may be displayed there, or moved by the application to
fixed (anchored) positions, or allowed to "float" in the first sense.</p>
<p>The first feature in JATS tagging is controlled through the use of
<monospace>position</monospace> attributes on objects that may be placed in this way
by the formatter. These elements include <monospace>boxed-text</monospace>,
<monospace>chem-struct-wrap</monospace>, <monospace>fig</monospace>,
<monospace>fig-group</monospace>, <monospace>graphic</monospace>,
<monospace>media</monospace>, <monospace>preformat</monospace>,
<monospace>supplementary-material</monospace>, <monospace>table-wrap</monospace>,
<monospace>table-wrap-group</monospace>. The second feature is supported by means of
the <monospace>floats-group</monospace> element, where such objects may be gathered.</p>
<p>Note that <monospace>position='float'</monospace> may be assigned to any of these
objects irrespective of whether it is gathered into <monospace>floats-group</monospace>.
Similarly, it is possible (although not ordinary) for an object to be placed inside
<monospace>floats-group</monospace>, and not in the body of the document, without
assigning it <monospace>position='float'</monospace>.</p>
<p>Note also that by default, on all these objects, <monospace>position</monospace> is
assigned a value of 'float' by the Journal Publishing DTD. If the attribute is not set
in the data, the formatting stylesheets assume the value 'float', both out of respect
for the semantics specified by the formal document model, and in order to prevent
different formatting when the DTD is used from when it is not.</p>
<p>Any object assigned <monospace>position='float'</monospace> will be allowed to float on
the page. Exceptions to this rule include the following:<list>
<list-item>
<p>No object, even one set to float, will float if it appears inside another object
set to float. Note again that objects are set to float implicitly, unless position
is set to 'anchor' or 'margin'.</p>
</list-item>
<list-item>
<p><monospace>graphic</monospace> and <monospace>media</monospace> will not float
when they appear inside any of the other elements that could float, even if they
don't in fact float. (For example: a <monospace>graphic</monospace> inside a
<monospace>fig</monospace> will not float, even if its
<monospace>position</monospace> is set to float and even if the
<monospace>fig</monospace> does not float.)</p>
</list-item>
<list-item>
<p><monospace>fig</monospace> will not float inside <monospace>fig-group</monospace>
(though the <monospace>fig-group</monospace> may float).</p>
</list-item>
<list-item>
<p><monospace>table-wrap</monospace> will not float inside
<monospace>table-wrap-group</monospace> (though the group as a whole may
float).</p>
</list-item>
<list-item>
<p><monospace>preformat</monospace> will not float inside
<monospace>bio</monospace>, <monospace>boxed-text</monospace>,
<monospace>chem-struct</monospace>, <monospace>chem-struct-wrap</monospace>,
<monospace>disp-formula</monospace>, <monospace>disp-quote</monospace>,
<monospace>fig</monospace>, <monospace>glossary</monospace>,
<monospace>supplementary-material</monospace>,
<monospace>disp-formula</monospace>, or <monospace>table-wrap</monospace>. Note,
however, that like other floatable objects, <monospace>preformat</monospace> will
ordinarily float unless its position says not to!</p>
</list-item>
</list></p>
<p>Also, the value 'margin' is not supported; objects with
<monospace>position='margin'</monospace> will act as if they have
<monospace>position='anchor'</monospace>.</p>
<p>In the HTML preview, floating an object will not move it on the page; it will only
allow text to flow around it.</p>
<p>In the PDF preview, objects with <monospace>position='float'</monospace> will be
positioned on the page by the formatting engine, typically at the top of the same page
where the object would appear if its <monospace>position</monospace> were 'anchor'. The
exact placement will depend on the formatting engine.</p>
<p>Note that when a float group is large (e.g. a table with footnotes provided both in
table form and as a graphic), it may not all fit on a single page.</p>
<p>Where floating is not wanted, the easiest solution is to set
<monospace>position</monospace> to 'anchor' on the element.</p>
</sec>
<sec>
<title>Gathering objects in <monospace>floats-group</monospace></title>
<p>Just like objects elsewhere, the placement of objects tagged inside
<monospace>floats-group</monospace> is determined by their
<monospace>position</monospace> attribute. The difference is that when assigned
<monospace>position='float'</monospace> (and remember this is the value by default),
in the PDF preview the object is formatted near its first cross-reference. Otherwise,
and when no such cross-reference appears in the document, it is formatted at the end of
the document.</p>
<p>The HTML preview stylesheet displays all objects inside
<monospace>floats-group</monospace> at the end of the document. (In this case,
however, cross-references are also hyperlinked.)</p>
<p>When articles should be formatted with a "Figures" or "Tables" section at the end, an
<monospace>app</monospace> or <monospace>sec</monospace> should be used for this
purpose, and the objects anchored in place. The preview stylesheets assume that
<monospace>floats-group</monospace> is specifically for collecting objects that are
intended to be formatted elsewhere.</p>
</sec>
<sec>
<title>Correct numbering of floating objects</title>
<p>As described below, the preview stylesheets do not provide automated numbering for
floating objects (distinguished, as a class, from footnotes, which may also "float"). In
systems where the stylesheet is extended to provide autonumbering, rules will need to be
formulated and followed to govern where floating objects are encoded, whether and where
they are cross-referenced, and the relation between settings of
<monospace>position</monospace> and appearance (and order) inside
<monospace>floats-group</monospace>, with appropriate enforcement of these
constraints. Otherwise it can be expected that their numbers will not always be properly
sequenced.</p>
</sec>
<sec>
<title>Setting <monospace>orientation</monospace></title>
<p>A number of objects also have an <monospace>orientation</monospace> attribute, which is
intended to allow specifying that they should be rotated in display, by setting its
value to 'landscape'.</p>
<p>The HTML preview stylesheet does not support orientation. The PDF stylesheet does
rotate the object; however, it assigns (somewhat arbitrarily) a width (i.e., a
<italic>vertical</italic> spacing for an object formatted in landscape) of 6 inches
for tables and 4 inches for other objects. While this will almost never be optimal, it
is the best that can be accomplished without particular formatting specifications for
each object, and it is enough to show that the orientation is set. Users may wish to
adjust the stylesheet to meet local needs for positioning and sizing tables and
figures.</p>
</sec>
<sec>
<title>Sizing tables</title>
<p>In HTML, tables are sized dynamically or according to attributes given on the table
element.</p>
<p>In the PDF preview, by default, tables are formatted at column width. If the
<monospace>width</monospace> attribute on a table is set to "100%" and
<monospace>orientation</monospace> is "portrait" (the default), the entire
<monospace>table-group</monospace> it appears in will be formatted at page width.</p>
</sec>
<sec>
<title>Footnotes</title>
<p>The Journal Publishing model supports either of two general approaches to encoding
footnotes in valid data. The <monospace>fn</monospace> element may be used in line where
a reference to a footnote (generally the first or only reference) should appear, with
the footnote content moved in rendering (typically to the bottom of the page). Or
footnotes may be encoded together in a structured grouping, the
<monospace>fn-group</monospace> element, and footnote references in the text are
encoded with <monospace>xref</monospace> elements, like any other cross-reference. The
latter style of encoding is said in the Journal Publishing documentation to be
appropriate for "end notes" as opposed to footnotes as such.
<monospace>fn-group</monospace> is permitted in a number of places, including within
the article back matter and in several other locations where footnotes are commonly
grouped in journal articles.</p>
<p>These stylesheets will support either approach to encoding footnotes. In the HTML
preview output, all footnotes encoded inline are grouped together in a section called
"Notes" appearing at the end of the document. In the PDF, footnotes encoded inline are
formatted at the foot of the page. In both cases, footnotes grouped in
<monospace>fn-group</monospace> or in <monospace>author-notes</monospace> appear
collected together where the <monospace>fn-group</monospace> or
<monospace>author-notes</monospace> appears. This will usually be inside the back
matter, but it can also occur in other places such as in the front matter,
<monospace>boxed-text</monospace> or <monospace>table-wrap-foot</monospace>.</p>
<p>Note that the two approaches (loose <monospace>fn</monospace> elements and
<monospace>fn</monospace> within <monospace>fn-group</monospace>) may be combined, but
this is inadvisable unless footnotes are numbered in the data, since it may result in
two distinct sets of footnote numbering. It is best to encode footnotes all one way or
all the other. Generally, if you use <monospace>fn</monospace> elements within mixed
content, do not also use <monospace>fn-group</monospace>. If you use
<monospace>fn-group</monospace>, use it for all footnotes and use
<monospace>xref</monospace> to provide references to them.</p>
<p>Additionally, in the PDF preview, errors will result if inline footnotes appear inside
floating objects (such as boxed text or figures). This is because the XSL-FO formatter
cannot position both a footnote and a floating object together (since when a footnote is
moved to appear on the same page as a float, the page layout determining where the float
can be placed may also be thrown off). This restriction means, in effect, that if you
have footnotes in your floating objects, you must locate the footnotes inside an
<monospace>fn-group</monospace>, and reference them with <monospace>xref</monospace>,
rather than using <monospace>fn</monospace> elements inline.</p>
<p>For discussion of footnote numbering, see <xref rid="autonumbering">below</xref>.</p>
</sec>
</sec>
<sec id="autonumbering">
<title>Autonumbering, labels, and cross-references</title>
<p>Except for two element types, <monospace>ref</monospace> (reference) and
<monospace>fn</monospace> (footnote), these preview stylesheets do not generate numbered
labels automatically.<fn>
<p>For projects that wish to exploit the potentials of automated processes for
systematic numbering, the stylesheet does contain code that can be configured to
generate labels, including autonumbering. See the <italic>Technical
Documentation</italic> for more information.</p>
</fn> If figures, tables and similar structures such as statements, supplementary
material, etc. are to be labelled, they must be labelled in the data. Labels provided in
the data (<monospace>label</monospace> elements) are displayed with the elements they
label; the same label content also appears in cross-references that point to those
elements when a cross-reference element (<monospace>xref</monospace> element) is given as
empty. (When an <monospace>xref</monospace> element has text content, it is used as the
text of the cross-reference, irrespective of whether a label appears with its target.)</p>
<p>This approach is meant to be as transparent and easy to understand as possible: rather
than assume any autolabeling method and format, it assumes that when labels are wanted on
content, they will be provided explicitly in the source data, and that when a
cross-reference is made to an object, it will either have content of its own (which can
serve as anchoring text), or its target will have an explicit label that can be used
unaltered as the text in the cross-reference.</p>
<p>There are two exceptions to this principle: numbering is provided for footnotes
(<monospace>fn</monospace> elements) and for references (<monospace>ref</monospace>
elements) when they do not have explicit labels, as these elements' primary purpose is
their systematic cross-referencing, and in most instances they will not function without
labels. In both cases, explicit labels (<monospace>label</monospace> elements or, in the
case of footnotes, <monospace>symbol</monospace> attributes) will override autogenerated
labels, allowing for projects to control these values in their data when necessary.</p>
<p>In all cases, to ensure legible and transparent output, warning messages may be generated
for unlabelled elements where labels are needed (due to an empty cross-reference pointing
to the element). This is described further below.</p>
<p>When generated for footnotes and references, automated numbers are assigned based on the
order of their appearance in the document, not of first references to them. (Nor are
<monospace>ref</monospace> elements sorted to reflect their order of first reference.)
Accordingly, in the PDF output, since footnotes are placed based on the location of the
<monospace>fn</monospace> element in the document, a cross-reference can be made to a
footnote that will appear on a different page. This also means that if footnote A appears
before footnote B in the document, a reference to footnote B will appear out of sequence
if it appears before footnote A does. The easiest ways to avoid both these problems are
(a) to use footnotes as endnotes (group them in <monospace>fn-group</monospace> in the
back matter) and confirm that they are placed in order of first reference; or (b) use
inline footnotes consistently (resulting in actual footnotes in the PDF) and make sure
that in every case, an <monospace>fn</monospace> element appears <italic>before</italic>
any other (second or subsequent) reference to the same footnote.</p>
<p>These stylesheets do not accommodate a practice of redundant tagging, whereby a footnote
encoded inline is also provided with an <monospace>xref</monospace> (cross-reference)
element to that footnote. If an <monospace>fn</monospace> element is used in line, a
reference will appear for it. Cross-references to footnotes should be used only for end
notes (<monospace>fn</monospace> elements in <monospace>fn-group</monospace>) or in cases
where more than one reference is made to a single footnote.</p>
<sec>
<title>Summary of best practice respecting cross-references and labels</title>
<p>In working with these stylesheets, the simplest approach to using labels and ensuring
that cross-references are clear is to follow an "all or nothing" rule:<list>
<list-item>
<p>As described above, <italic>either</italic> all footnotes
(<monospace>fn</monospace> elements) should be enclosed in
<monospace>fn-group</monospace> elements (effectively, to present as endnotes),
in order of first reference, <italic>or else</italic> all footnotes should be
placed inline at their point of first reference.</p>
<p>Avoid using (empty) <monospace>xref</monospace> elements to refer to footnotes
that have not yet appeared, unless the footnote is inside
<monospace>fn-group</monospace>, as this will result in numbering out of
sequence.</p>
<p>Of course, such forward references are not a problem and need not be avoided if
footnotes are labelled in the source data, or if <monospace>xref</monospace>
elements have data content; in that case, of course, it is an editorial task to
maintain correct referencing and numbering.</p>
</list-item>
<list-item>
<p><italic>Either</italic> label all footnotes explicitly in the source data (using
<monospace>label</monospace> elements or <monospace>symbol</monospace>
attributes), <italic>or else</italic> let the system number all of them.</p>
</list-item>
<list-item>
<p>Similarly, <italic>either</italic> no reference elements
(<monospace>ref</monospace>), whether they are cross-referenced or not, should
be given <monospace>label</monospace> elements, <italic>or else</italic> all of
them should.</p>
</list-item>
<list-item>
<p><italic>Either</italic> every object type (such as figures or tables) that is
cross-referenced should be given <monospace>label</monospace> elements
consistently and throughout, <italic>or else</italic> cross-references
(<monospace>xref</monospace> elements) should never be empty.</p>
</list-item>
</list></p>
<p>As described in the <italic>Technical Documentation</italic>, the stylesheet logic
regarding generating labels and/or automatic numbering can be modified in the
stylesheets.</p>
</sec>
<sec>
<title>Warning messages for missing labels</title>
<p>The logic outlined above is fairly simple (apart from the complications of footnotes
and references), but an error condition may still arise (even in a valid document) if an
object has no <monospace>label</monospace> element, and a cross-reference
(<monospace>xref</monospace>) pointing to it has no content of its own. When this
happens, a warning message will be generated in place of a label, both with the object
and wherever it is cross-referenced. A summary view of all such warning messages is also
provided in a special section entitled <bold>Process Warnings</bold> at the end of the
document.</p>
<p>This error can be corrected (1) by providing the targeted object with a
<monospace>label</monospace> element (or alternatively, for a footnote, a
<monospace>symbol</monospace> attribute), (2) by providing its cross-reference(s) with
content, or (3) by doing both.</p>
<p>When there are no such errors, the <bold>Process Warnings</bold> section does not
appear.</p>
</sec>
<sec>
<title>Other limitations on <monospace>xref</monospace> elements</title>
<p>The current implementation of the preview stylesheets does not support cross-references
to more than one target using a single <monospace>xref</monospace> element. Although
according to the DTD, an <monospace>IDREFS</monospace> value is allowed on
<monospace>xref/@rid</monospace>, only a single <monospace>IDREF</monospace> will
work.</p>
<p>In other
words,<preformat position="anchor"><xref rid="fig1">See Figure 1</xref></preformat>will
generate a cross-reference in the output,
but<preformat position="anchor"><xref rid="fig1 fig2">See Figures 1 and 2</xref></preformat>will
not work correctly (it will attempt to link to an object identified as "fig1 fig2").</p>
</sec>
</sec>
<sec id="citations">
<title id="Moreonthebibliographicformats">Citations</title>
<p>Journal Publishing XML may tag bibliographic citations in any of several ways. One of
those ways uses the <monospace>element-citation</monospace> element, which assumes that
rendering of citations, including punctuation, is provided by a stylesheet. Stylesheets in
this package are capable of rendering <monospace>element-citation</monospace> into two
different bibliographic formats.<fn>
<p>Note that even in the best of cases, it is not possible to automate the formatting of
arbitrary bibliographic citations completely and systematically. Testing shows that
while these stylesheets will handle the majority of common cases properly, adjustments
often have to be made. When this occurs with the provided stylesheets, users have the
same options as they have when they need an output format that has not been
implemented: either extend the stylesheet to produce the desired output, or else fall
back on manual formatting using <monospace>mixed-citation</monospace>.</p>
</fn></p>
<list>
<list-item>
<p><bold>NLM/Pubmed format</bold>. The stylesheet provided here is a modified version of
a transformation used internally at NCBI.</p>
</list-item>
<list-item>
<p><bold>APA-like format</bold>. A stylesheet for generating common citation styles
conforming to APA guidelines is also provided. We call this format "APA-like" in order
to stress that results may not correspond precisely either to local rules regarding
details of APA format or in some cases to APA's own guidelines.</p>
</list-item>
</list>
<p>If your citations follow neither practice, or when your citations do not format properly
due to special cases, you have two alternatives:</p>
<list>
<list-item>
<p>Instead of <monospace>element-citation</monospace> in bibliographies or reference
lists, use <monospace>mixed-citation</monospace> with explicit formatting. This
element allows citations to be formatted and punctuated directly in the XML data.
Neither preprocessing stylesheet will override any punctuation within
<monospace>mixed-citation</monospace> elements.</p>
<p>Even if all citations are given as punctuated <monospace>mixed-citation</monospace>
elements, however, it is still necessary to run one or another citations preprocessor.
This is because they may still contain elements with formatting consequences, which
the preview stylesheets have no rules to handle. The only citations that are safe to
run through the preview stylesheets without any preprocessing whatsoever conform to a
profile of <monospace>mixed-citation</monospace> that includes only elements whose
formatting consequences are inherent in their semantics,<fn>
<p>I.e., elements such as <monospace>italic</monospace> and
<monospace>sup</monospace> (superscript).</p>
</fn> and will not vary from one citation formatting style to another. See the
<italic>Technical Documentation</italic> on the "Simple citation" element profile
for more details.</p>
</list-item>
<list-item>
<p>Extend or modify one of the provided citation processors, or develop your own
citation preprocessor implementing your own rules for formatting citations.</p>
</list-item>
</list>
<p>If you have no citations, you can run the stylesheets for either format.</p>
</sec>
</sec>
<sec id="special-purpose">
<title>Special-purpose transformations</title>
<p>There are four types of resources included in this package:<list>
<list-item>
<p>The main preview stylesheets (found in the <monospace>main</monospace>
subdirectory);</p>
</list-item>
<list-item>
<p>Various ancillary stylesheets for pre- or post-processing data in support of special
operations (in the <monospace>prep</monospace>, <monospace>citations-prep</monospace>,
<monospace>oasis-tables</monospace> and <monospace>post</monospace>
subdirectories);</p>
</list-item>
<list-item>
<p>XProc pipelines that implement more comprehensive transformations by connecting two
or more of these stylesheets in sequence. These can efficiently execute a sequence of
transformations without writing interim results to the file system.</p>
</list-item>
<list-item>
<p>"Shell" or "wrapper" stylesheets used to the same effect, by relying on extended
functionality in the Saxon processor (for those who have a recent version of
Saxon<xref rid="saxon-versions"/> and do not wish to use XProc).</p>
</list-item>
</list>Users wanting a simple approach can acquire an XProc processor, or a recent version
of Saxon, identify the pipeline or shell stylesheet that performs the necessary tasks, and
apply it to their data.</p>
<p>All of the stylesheets can also be run on their own, and several of them work also in XSLT
1.0 engines. Due to limitations of the main preview stylesheets, especially limitations in
their handling of citations (which cannot be handled generically), this is recommended only
when citation formatting is otherwise accounted for.</p>
<p>Publishers and content creators are free to experiment. The structure of this distribution
is intended to provide for extensions, in the form either of new processing steps (such as a
preprocessor for a new citation format) or modifications to existing steps. Or projects may
wish to "unbundle" the processes and apply the stylesheets by different means altogether.
The <italic>Technical Documentation</italic> describes these alternatives in more
detail.</p>
<p>Top-level pipelines included in this package are as follows (each available in two forms,
XProc and extended XSLT 2.0):<def-list>
<def-item>
<term>
<monospace>jats-PMCcit-html</monospace>
</term>
<def>
<p>Generates HTML results with formatting of NLM/Pubmed citations supported.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-APAcit-html</monospace>
</term>
<def>
<p>Generates HTML results with formatting of APA citations supported.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-PMCcit-xslfo</monospace>
</term>
<def>
<p>Generates XSL-FO results for PDF production, with formatting of NLM/Pubmed
citations supported.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-APAcit-xslfo</monospace>
</term>
<def>
<p>GeneratesXSL-FO results for PDF production, with formatting of APA citations
supported.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-PMCcit-web-html</monospace>
</term>
<def>
<p>This works like <monospace>jats-PMCcit-html.xsl</monospace> except it includes a
preprocess that removes all elements marked with a
<monospace>specific-use</monospace> attribute whose value is "print-only". This
stylesheet works by invoking an additional preprocessing step,
<monospace>prep/jats-webfilter.xsl</monospace>. It may be useful mainly as a
demonstration, illustrating how processes can be customized to meet local
requirements as described in the <italic>Technical Documentation</italic>.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-PMCcit-xhtml</monospace>
</term>
<def>
<p>This also works like <monospace>jats-PMCcit-html.xsl</monospace>, except it
includes a postprocess that converts the HTML results into XHTML, resulting in XHTML
results that can be correctly rendered by MathML-capable browsers. The postprocessor
called by this stylesheet, <monospace>xhtml-ns.xsl</monospace>, can be applied as
the final step in any pipeline that must generate XHTML, as also described in the
<italic>Technical Documentation</italic>.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-PMCcit-print-fo</monospace>
</term>
<def>
<p>This shell is the complement of <monospace>jats-PMCcit-web-html.xsl</monospace>. It
formats citations in NLM/Pubmed citation format, removes all elements marked with a
<monospace>specific-use</monospace> attribute whose value is "web-only", and then
transforms the document to XSL-FO results, ready for formatting as PDF by an XSL
formatter.</p>
</def>
</def-item>
<def-item>
<term>
<monospace>jats-oasis-PMCcit-fo</monospace>
</term>
<def>
<p>This shell excludes elements with a <monospace>specific-use</monospace> attribute
of "web-only", processes OASIS tables, formats citations in NLM/Pubmed citation
format, and transforms the document to XSL-FO results for conversion to PDF.</p>
</def>
</def-item>
</def-list></p>
</sec>
</body>
</article>