forked from OASIS-XDI-Technical-Committee/xdi-spec-docbook
/
oasis-specification-0.6-wd04.xml
1068 lines (916 loc) · 61.2 KB
/
oasis-specification-0.6-wd04.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
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
For use when a committee document points at the OASIS web site for publishing:
<?xml-stylesheet type="text/xsl"
href="http://docs.oasis-open.org/templates/DocBook/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
For use when a committee document points to an embedded runtime installation:
<?xml-stylesheet type="text/xsl"
href="htmlruntime/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"htmlruntime/spec-0.6/docbook/docbookx.dtd"
For use when a committee document is published in a local environment only
(note the instructions for local publishing require adjusting the stylesheet
and DocBook directories in these declarations):
<?xml-stylesheet type="text/xsl"
href="file:///c:/oasis/spec-0.6/stylesheets/oasis-specification-html-offline.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///c:/oasis/spec-0.6/docbook/docbookx.dtd"
-->
<?xml-stylesheet type="text/xsl"
href="http://docs.oasis-open.org/templates/DocBook/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!--the document properties-->
<!ENTITY name "oasis-specification">
<!ENTITY pversion "0.5">
<!ENTITY version "0.6">
<!ENTITY stage "wd04">
<!ENTITY standard "Working Draft 04">
<!ENTITY this-loc "http://docs.oasis-open.org/templates/DocBook/spec-&version;">
<!ENTITY previous-loc "http://docs.oasis-open.org/templates/DocBook/spec-&pversion;">
<!ENTITY latest-loc "http://docs.oasis-open.org/templates/DocBook/oasis-specification">
<!ENTITY pubdate "14 June 2012">
<!ENTITY title "OASIS Specification Publishing in DocBook XML Version &version;">
]>
<article status="&standard;">
<articleinfo>
<title>&title;</title>
<releaseinfo role="cvs">
$Id: oasis-specification-0.6-wd04.xml,v 1.2 2012/06/14 01:57:23 admin Exp $
</releaseinfo>
<productname>&name;</productname>
<productnumber>&version;-&stage;</productnumber>
<releaseinfo role="track">Non-standards Track Work Product</releaseinfo>
<releaseinfo role="OASIS-specification-this-authoritative">&this-loc;/&name;-&version;-&stage;.html</releaseinfo>
<releaseinfo role="OASIS-specification-this">&this-loc;/&name;-&version;-&stage;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-this">&this-loc;/&name;-&version;-&stage;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-previous-authoritative">&previous-loc;/&name;-&pversion;.html</releaseinfo>
<releaseinfo role="OASIS-specification-previous">&previous-loc;/&name;-&pversion;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-previous">&previous-loc;/&name;-&pversion;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-latest-authoritative">&latest-loc;/&name;.html</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/&name;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/&name;.xml</releaseinfo>
<releaseinfo role="committee"><ulink url="http://www.oasis-open.org/">OASIS TC Administration</ulink></releaseinfo>
<authorgroup>
<editor>
<firstname>G. Ken</firstname><surname>Holman</surname>
<affiliation>
<orgname>Associate member</orgname>
</affiliation>
<email>gkholman@CraneSoftwrights.com</email>
</editor>
</authorgroup>
<pubdate>&pubdate;</pubdate>
<copyright><year>2012</year>
<holder>OASIS Open, Inc. All Rights Reserved.</holder></copyright>
<legalnotice role="additional"><title>Additional artifacts</title>
<para>This prose specification is one component of a Work Product which also includes:</para>
<itemizedlist spacing="compact">
<listitem><para>
publishing materials: <ulink url="&this-loc;/&name;-&version;-&stage;.zip">&this-loc;/&name;-&version;-&stage;.zip</ulink></para>
</listitem>
</itemizedlist>
</legalnotice>
<legalnotice role="related"><title>Related work</title>
<para>This methodology supersedes guidelines for the DocBook XML-based authoring and publishing of OASIS specifications described in <ulink url="http://docs.oasis-open.org/templates/DocBook/spec-0.5/oasis-specification-0.5.html">http://docs.oasis-open.org/templates/DocBook/spec-0.5/oasis-specification.html</ulink>.</para>
</legalnotice>
<abstract><title>Abstract</title>
<para>This working draft describes an environment for writing and publishing an OASIS specification using DocBook XML. It is an internal OASIS support document and not the basis of an OASIS specification in and of itself.</para>
</abstract>
<legalnotice role="status"><title>Status</title>
<para>This is a work in progress contributed to the OASIS TC administration
and does not at this time represent
the consensus of any particular OASIS Technical Committee. There are no plans to make this a formal Committee Specification as it is merely an internal document made available to committee members to support the publishing process.</para>
</legalnotice>
<legalnotice role="citation"><title>Citation format</title>
<para>When referencing this specification the following citation format should be used:</para>
<bibliolist>
<bibliomixed>
<abbrev>OASIS-DOCBOOK-TEMPLATE-V0.6</abbrev>
<title>OASIS DocBook Template V0.6. </title>
<date>&pubdate;. </date>
<releaseinfo>OASIS &standard;. </releaseinfo>
<citetitle><ulink url="&latest-loc;/&name;.html">&latest-loc;/&name;.html</ulink>.</citetitle>
</bibliomixed>
</bibliolist>
</legalnotice>
<legalnotice role="notices"><title>Notices</title>
<para>Copyright © OASIS® Open 2012. All Rights Reserved.
</para>
<para>All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at <ulink url="http://www.oasis-open.org/who/intellectualproperty.php">http://www.oasis-open.org/who/intellectualproperty.php</ulink>.</para>
<para>This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.</para>
<para>The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.</para>
<para>This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</para>
<para>OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.</para>
<para>OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.</para>
<para>OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.</para>
<para>The name "OASIS" is a trademark of <ulink url="http://www.oasis-open.org">OASIS</ulink>, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see <ulink url="http://www.oasis-open.org/who/trademark.php">http://www.oasis-open.org/who/trademark.php</ulink> for above guidance.</para>
</legalnotice>
</articleinfo>
<section id="s.intro">
<title>Introduction</title>
<para>
This document details an environment <xref linkend="spec-ZIP"/> and methodology for writing an OASIS specification document using XML markup, and publishing the resulting document to HTML and printed results conforming to OASIS layout conventions.</para>
<para>
While this has been prepared before, a new version of this environment and methodology is required to accommodate the latest conventions adopted by the OASIS TC Administration.</para>
<para>
The stylesheets for this version of this environment will remain static while the prose methodology documents and samples may be revised from time to time. Should it be necessary to revise the stylesheets, this version of the environment will left unchanged on the OASIS web site and a new version of the stylesheets and prose documents will be started. Check the persistent location noted above for any revisions to this environment.</para>
<para>
These stylesheets use XSLT <xref linkend="xslt"/> as the transformation expression language to produce the final HTML result. XSLT is also used to produce the intermediate XSL-FO <xref linkend="xsl-fo"/> pagination semantics, which in turn are available to be processed to produce printable results.</para>
<section><title>Terminology</title>
<section>
<title>
Key words</title>
<para>The key words <glossterm>must</glossterm>, <glossterm>must
not</glossterm>, <glossterm>required</glossterm>,
<glossterm>shall</glossterm>, <glossterm>shall not</glossterm>,
<glossterm>should</glossterm>, <glossterm>should not</glossterm>,
<glossterm>recommended</glossterm>, <glossterm>may</glossterm>, and
<glossterm>optional</glossterm> are to be
interpreted as described in <xref linkend="rfc2119"/>. Note that for
reasons of style, these words are not capitalized in this
document.</para>
</section>
</section>
<section>
<title>Normative References</title>
<bibliolist>
<bibliomixed id="docbook">
<abbrev>DocBook</abbrev>OASIS Committee Draft 4.4 <title><ulink url="http://www.docbook.org/specs/cd-docbook-docbook-4.4.pdf">The DocBook 4.4 Document type</ulink></title>, OASIS January 27, 2005,
<citetitle><ulink url="http://www.docbook.org/specs/cd-docbook-docbook-4.4.html">OASIS DocBook 4.4 Document Type 27 Jan 2005 HTML</ulink>,
</citetitle>,
<citetitle><ulink url="http://www.docbook.org/xml/4.4/docbook-xml-4.4.zip">DocBook 4.4 XML DTD</ulink>,
</citetitle>,
<citetitle><ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl-doc/1.69.1/">DocBook Stylesheets Version 1.69.1</ulink></citetitle>. </bibliomixed>
<bibliomixed id="spec-ZIP">
<abbrev>Spec-&version;-ZIP</abbrev>
<title>&title;. ZIP package. </title>
<date>&pubdate;. </date>
<citetitle><ulink url="&this-loc;/&name;-&version;-&stage;.zip">&this-loc;/&name;-&version;-&stage;.zip</ulink></citetitle>
</bibliomixed>
<bibliomixed id="rfc2119">
<abbrev>RFC 2119</abbrev>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>,
<date>March 1997. </date>
<author><firstname>S. </firstname><surname>Bradner</surname></author>.
<releaseinfo>IETF (Internet Engineering Task Force) RFC 2119, </releaseinfo>
<citetitle><ulink url="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</ulink></citetitle>
</bibliomixed>
<bibliomixed id="xml-assoc">
<abbrev>xml-assoc</abbrev>
<title>Associating Style Sheets with XML documents Version 1.0. </title>
<date>29 June 1999. </date>
<author><firstname>James </firstname><surname>Clark</surname></author>.
<releaseinfo>W3C Recommendation. </releaseinfo>
<citetitle><ulink url="http://www.w3.org/1999/06/REC-xml-stylesheet-19990629">http://www.w3.org/1999/06/REC-xml-stylesheet-19990629</ulink></citetitle>
</bibliomixed>
<bibliomixed id="xsl-fo">
<abbrev>XSL-FO</abbrev>
<title>Extensible Stylesheet Language (XSL) Version 1.1. </title>
<date> 5 December 2006. </date>
<author><firstname>Anders </firstname><surname>Berglund</surname></author>.
<releaseinfo>W3C Recommendation. </releaseinfo>
<citetitle><ulink url="http://www.w3.org/TR/2001/REC-xsl-20011015/">http://www.w3.org/TR/2001/REC-xsl-20011015/</ulink></citetitle>
</bibliomixed>
<bibliomixed id="xslt">
<abbrev>XSLT</abbrev>
<title>XSL Transformations (XSLT) Version 1.0. </title>
<date>16 November 1999. </date>
<author><firstname>James </firstname><surname>Clark</surname></author>.
<releaseinfo>W3C Recommendation. </releaseinfo>
<citetitle><ulink url="http://www.w3.org/TR/1999/REC-xslt-19991116"></ulink></citetitle>
</bibliomixed>
</bibliolist>
</section>
<section>
<title>Non-Normative References</title>
<bibliolist>
<bibliomixed id="ant"><abbrev>ant</abbrev>Apache Software Foundation
<title><ulink url="http://ant.apache.org">Ant Java-based Build Tool</ulink></title>
(Another Neat Tool).</bibliomixed>
<bibliomixed id="fop"><abbrev>FOP</abbrev>Apache Software Foundation
<title><ulink url="http://xmlgraphics.apache.org/fop">Formatting Objects Processor</ulink></title>.</bibliomixed>
<bibliomixed id="ibex-ss"><abbrev>Ibex Signature Edition</abbrev> Visual Programming Limited. <title><ulink url="http://www.xmlpdf.com/ibex-downloads-signed.html">Ibex XSL-FO Processor</ulink></title>.</bibliomixed>
<bibliomixed id="saxon"><abbrev>Saxon</abbrev>Michael Kay <title><ulink url="http://saxon.sourceforge.net/saxon6.5.5/index.html">Saxon 6.5.5 XSLT 1.0 Processor</ulink></title>.</bibliomixed>
<bibliomixed id="xjparse"><abbrev>xjparse</abbrev>Norm Walsh <title><ulink url="http://nwalsh.com/java/xjparse">xjparse XML validation invocation</ulink></title>.</bibliomixed>
</bibliolist>
</section>
</section>
<section>
<title>Installation and use</title>
<para>These stylesheets are zipped <xref linkend="spec-ZIP"/> in a turnkey
environment ready to unpack for offline use. The environment is used to
validate DocBook XML, render HTML and create XSL-FO suitable for
processing with an XSL-FO engine (which is not included). Of course one
is not obliged to use the processors referenced as one can use any XML
DTD validation tool and any XSLT processor.</para>
<para>The package can be downloaded from <ulink
url="&this-loc;/&name;-&version;-&stage;.zip"
>&this-loc;/&name;-&version;-&stage;.zip</ulink> and is expected to be
unzipped into a local directory for offline use. The examples in this
documentation assume the package is unzipped in a Windows environment
into the <literal>c:\</literal> directory, and in a Linux environment in
one's home directory. For example purposes, it is assumed that the ZIP
file contents (all files starting with <literal>spec-0.6/</literal>) are
installed in the <literal>c:\oasis\spec-0.6\</literal> directory or
<literal>~/oasis/spec-0.6/</literal>.</para>
<para>See <xref linkend="orch"/> for details on a set of invocations for validating OASIS specification documents and producing an HTML rendering suitable for web browsers and an XSL-FO result suitable for an XSL-FO engine. Neither a browser nor an XSL-FO engine are themselves included in the package.</para>
<section>
<title>Package contents</title>
<para>The significant directories of the package are as follows, shown for a
Windows environment but identical in a Linux environment:</para>
<programlisting>c:\oasis\ <emphasis>- base directory for complete installation</emphasis>
\spec-0.6 <emphasis>- base directory for rendering</emphasis>
\spec-0.6\css <emphasis>- HTML appearance</emphasis>
\spec-0.6\stylesheets <emphasis>- HTML and XSL-FO production stylesheets</emphasis>
\spec-0.6\template <emphasis>- example specification in XML</emphasis>
\spec-0.6\docbook <emphasis>- base directory for DocBook DTD</emphasis>
\spec-0.6\docbook\xsl <emphasis>- base directory for stylesheet library</emphasis>
\spec-0.6\docbook\xsl\fo <emphasis>- base directory for XSL-FO library</emphasis>
\spec-0.6\docbook\xsl\html <emphasis>- base directory for HTML library</emphasis>
\spec-0.6\htmlruntime <emphasis>- embedded installation in a distribution</emphasis>
</programlisting>
<para>The DocBook DTD components in the <literal>docbook/</literal> directory were obtained from <ulink url="http://www.docbook.org/xml/4.4/docbook-xml-4.4.zip">http://www.docbook.org/xml/4.4/docbook-xml-4.4.zip</ulink>.</para>
<para>The DocBook XSL components in the <literal>docbook/xsl/</literal> directory were obtained from <ulink url="http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.69.1.zip">http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.69.1.zip</ulink>, where the base directory of the unzipped package is renamed "<literal>xsl/</literal>". This allows one to obtain another release of the DocBook stylesheets, unzip them into a directory, rename the base directory and replace the <literal>xsl/</literal> installation directory. The <literal>xsl/fo/</literal> and <literal>xsl/html/</literal> directories should be in place when the unpacking, renaming and replacing is completed. Note that three installation files <literal>install.sh</literal>, <literal>.CatalogManager.properties.example</literal>, and <literal>.urilist</literal> have been removed from the 1.69.1 directories per the instructions in the <literal>INSTALL</literal> file, as two of them violate OASIS file naming guidelines.</para>
<section>
<title>Runtime package contents</title>
<para>The <literal>htmlruntime/</literal> directory is a suitable subset of
the other directories for use when distributing the HTML subset of
this publishing environment embedded in your specification
distribution for runtime rendering of XML documents in HTML. The
directory name "<literal>htmlruntime</literal>" can be renamed as
desired to be anything at all. The XML of the specification uses
stylesheet association (see <xref linkend="sassoc"/>) to point to the
HTML stylesheet in the runtime package directory distributed with the
XML.</para>
<para>An example of the use of this runtime configuration is in <ulink
url="http://docs.oasis-open.org/ubl/prd2-UBL-2.1/"
>http://docs.oasis-open.org/ubl/prd2-UBL-2.1/</ulink> where the
file <literal>UBL-2.1.xml</literal> includes a stylesheet association
directive to engage the HTML stylesheets in the
"<literal>db/</literal>" directory (having renamed it from
"<literal>htmlruntime/</literal>").</para>
</section>
</section>
<section>
<title>Engaging the DocBook DTD</title>
<para>The DocBook Document Type Definition (DTD) expresses the
constraints of using elements and attributes, but not necessarily the
conventions imposed by the OASIS TC Administration. Just having your
specification validate with the DTD does not guarantee that you've used
the correct or appropriate DocBook constructs to produce the required
output. This package includes <xref linkend="proforma"/> illustrating
the conventional use of the DocBook constructs.</para>
<para>To assert in the online OASIS environment that your XML document satisfies the constraints of DocBook, point to the posted copy of the DTD:</para>
<programlisting><![CDATA[<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"]]></programlisting>
<para>To assert in an embedded environment that your XML document satisfies the constraints of DocBook, point to the embedded copy of the DTD:</para>
<programlisting><![CDATA[<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"htmlruntime/spec-0.6/docbook/docbookx.dtd"]]></programlisting>
<para>To assert in an offline local environment that your XML document satisfies the constraints of DocBook, point to the installation copy of the DTD:</para>
<programlisting><![CDATA[<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///c:/oasis/spec-0.6/docbook/docbookx.dtd"]]></programlisting>
<para>Validating the XML document using the embedded DTD reference will report
any DocBook constraint violations in your XML.</para>
</section>
<section>
<title>The OASIS specification HTML stylesheets</title>
<para>There are two stylesheets you must choose from in order to create
one of two versions of the rendering based on how that rendering will
be used.</para>
<para>Use this stylesheet during development and local review to create a
test instance (this will use local CSS stylesheets and the local base
URI):</para>
<programlisting>c:\oasis\spec-0.6\stylesheets\oasis-specification-html-offline.xsl
</programlisting>
<para>Use this stylesheet in the offline environment to create the final online
version to send to OASIS TC Administration (this will use embedded
references to online CSS stylesheets and the online base URI in
accordance with OASIS TC Administration requirements):</para>
<programlisting>c:\oasis\spec-0.6\stylesheets\oasis-specification-html.xsl
</programlisting>
<para>When the distribution includes the embedded rendering environment,
the same online stylesheet is referenced with a relative URI (note the
use of forward slashes rather than backslashes); of course the path
will need to be adjusted based on your choice of where the stylesheets
are embedded in your distribution:</para>
<programlisting>htmlruntime/spec-0.6/stylesheets/oasis-specification-html.xsl
</programlisting>
<para>In each case the resulting file should be suitable for viewing in a web browser.</para>
</section>
<section>
<title>The OASIS specification XSL-FO stylesheet</title>
<para>To convert a DocBook instance following the conventions used in this specification into an instance of XSL-FO assuming A4 page dimensions or US-letter page dimensions, use one of these stylesheets:</para>
<programlisting>c:\oasis\spec-0.6\stylesheets\oasis-specification-fo-a4.xsl
c:\oasis\spec-0.6\stylesheets\oasis-specification-fo-us.xsl
</programlisting>
<para>The resulting file should be suitable for an XSL-FO engine to render into a printed format such as a PDF file.</para>
<note>
<para>Some XSL-FO engines will automatically translate relative URI strings in links to absolute URI strings as part of the formatting process. This will leave absolute references to your local file system in the generated PDF, rather than the desired relative URI strings needed. Usually the resulting PDF, when not encrypted or locked, can be hacked to manually translate the absolute URI strings to the required relative URI strings.</para>
</note>
</section>
<section id="invokeparam">
<title>Stylesheet invocation parameters</title>
<para>There are four typical invocation parameters with defaults:</para>
<itemizedlist>
<listitem><para><literal>automatic-output-filename=<userinput>yes-or-no</userinput></literal></para>
<itemizedlist>
<listitem><para>when set to "<literal>no</literal>" (the default) the stylesheet
processor invocation output target is not ignored</para>
</listitem>
<listitem><para>when set to "<literal>yes</literal>" the stylesheets will ignore the invocation output target and will automatically produce the output file named using the content of two child elements of <literal><article-info></literal> as follows:</para>
<blockquote><para><literal><productname>-<productnumber></literal></para>
</blockquote>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>oasis-base=<userinput>yes-or-no</userinput></literal>
(HTML only)</para>
<itemizedlist>
<listitem>
<para>when set to "<literal>no</literal>" (the default) there is no addition of
a <literal><base></literal> metadata element in the HTML
result</para>
</listitem>
<listitem>
<para>when set to "<literal>yes</literal>" the stylesheets will
create an HTML <literal><base></literal> metadata element
extracting the URI from the first
<literal><articleinfo><release-info></literal> element
where the <literal>role=</literal> attribute contains the
reserved partial string
"<literal>OASIS-specification-this</literal>" and the URI
contains the string "<literal>.htm</literal>"</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>html.stylesheet=<userinput>URI-string-to-OASIS-CSS-file</userinput></literal>
(HTML only)</para>
<itemizedlist>
<listitem>
<para>use this to inject a relative URI or other URI to your
placement of the OASIS CSS file usually found in the publishing
environment at "<literal>css/oasis-spec.css</literal>"</para>
</listitem>
<listitem>
<para>when not specified the URI that is used is hardwired to
either your local publishing environment (when using the
offline HTML stylesheet) or hardwired to the OASIS server
publishing environment (when using the online HTML
stylesheet)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>oasis.logo=<userinput>URI-string-to-OASIS-logo-jpg</userinput></literal>
(HTML only)</para>
<itemizedlist>
<listitem>
<para>use this to inject a relative URI or other URI to your
placement of the OASIS logo file usually found in the
publishing environment base directory at
"<literal>OASISLogo.jpg</literal>"</para>
</listitem>
<listitem>
<para>when not specified the URI that is used is hardwired to
either your local publishing environment (when using the
offline HTML stylesheet) or hardwired to the OASIS server
publishing environment (when using the online HTML
stylesheet)</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>
Authoring in XML</title>
<para>
An important objective of using XML markup when writing content is to separate what you are writing from how it is formatted and presented. Moreover, describing the individual components of your writing uniquely can allow machine processing of your content. Such machine processing can identify constructs and process them individually as required for the processed result.</para>
<para>
The vocabulary of XML markup is the level of granularity used to identify constituent information items, and the collection of element and attribute labels applied to the granules.</para>
<para>
Applying styling to documents is an example of machine processing. The processed result is a formatted representation of your document. When many authors use the same vocabulary, or a given author creates many documents with the same vocabulary, a single set of processes will produce consistently formatted results across the document set.</para>
<para>
This process is analogous to using styles found in most desktop publishing applications, however by removing from the author the ability to inject arbitrary formatting of information items in their content, two benefits are realized: (a) the author no longer needs to think about formatting, only about appropriately labeling the information items in the content; and (b) authors cannot inadvertently format components of a document with incorrect or inconsistent results.</para>
<para>
Many writers do, however, prefer the use of their favorite desktop publishing applications and OASIS has posted at <ulink url="http://docs.oasis-open.org/templates/">http://docs.oasis-open.org/templates/</ulink> a number of templates for widely-adopted word processing programs to be used in the creation of OASIS specifications. Users must be diligent in the use of styles in order to ensure their work conforms to the presentation conventions requested of OASIS. There is an obligation incumbent on the writer to verify their work has not violated the requested conventions, and there are no automated tools with which to validate the constraints have been respected.</para>
<para> When creating OASIS specifications using XML the burden of formatting is
placed on the stylesheets, not on the writer. The obligation of the
writer is only to be conformant to the DocBook document model for which
the included stylesheets have been designed, and there are automated
validation tools with which the writer can validate the constraints have
not been respected. The writer is also obligated to follow conventions
that reflect the requirements of the OASIS TC Administration for
specification documents, though these are not validated by the DocBook
document models. The conventions are, however, reflected in a template
included in this package.</para>
<para>
Any resulting violations to the formatting conventions can usually be ascribed to the stylesheets and, when repaired, the authored content usually does not need to change (barring any need to distinguish in the XML an ambiguity that is then being distinguished in the stylesheets).</para>
<section>
<title>
DocBook vocabulary</title>
<para> This environment and methodology is based on using the
<sgmltag><article></sgmltag> document type of the DocBook 4.4
<xref linkend="docbook"/> vocabulary for authoring the content in XML
markup. These explanatory documents do not attempt to teach the DocBook
vocabulary, as there are many online and printed references and manuals
on the use of DocBook.</para>
<para>
Note that there is a layer of additional constraints imposed on top of the DocBook metadata constructs in order to appropriately identify the constituent metadata components of the OASIS requirements for specifications. No validation constraints for this additional metadata layer are included in this environment, so it is the responsibility of the writer to visually confirm these needs have been satisfied in the rendered results. Missing components are typically the result of the writer not having correctly used the metadata indicators within the standard DocBook constructs.</para>
<para> The additional constraints are illustrated and documented in <xref
linkend="proforma"/> and included with these materials.</para>
</section>
<section id="augmentations">
<title>DocBook augmentations for OASIS specifications</title>
<para>These OASIS specification stylesheets recognize the following additional facilities or interpretations when using the DocBook vocabulary:</para>
<itemizedlist>
<listitem><para><literal><articleinfo><productname></literal> (see <xref linkend="invokeparam"/>)</para>
</listitem>
<listitem><para><literal><articleinfo><productnumber></literal> (see <xref linkend="invokeparam"/>)</para>
</listitem>
<listitem><para><literal><articleinfo><releaseinfo role="OASIS-specification-this"></literal><emphasis><literal>{uri}</literal></emphasis></para>
<itemizedlist>
<listitem><para>reserved role identifying a URI belonging under the "This Version" heading</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><releaseinfo role="OASIS-specification-previous"></literal><emphasis><literal>{uri}</literal></emphasis></para>
<itemizedlist>
<listitem><para>reserved role identifying a URI belonging under the "Previous Version" heading</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><releaseinfo role="OASIS-specification-latest"></literal><emphasis><literal>{uri}</literal></emphasis></para>
<itemizedlist>
<listitem><para>reserved role identifying a URI belonging under the "Latest Version" heading</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>release information role suffix "<literal>-draft</literal>"</para>
<itemizedlist>
<listitem><para>the "<emphasis><literal>{uri}</literal></emphasis>" content is not interpreted as a URI but only simply as DocBook content</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>release information role suffix "<literal>-authoritative</literal>"</para>
<itemizedlist>
<listitem><para>the entry is suffixed with the string "(Authoritative)" as is required by OASIS conventions for one of the renditions</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><releaseinfo role="committee"></literal><emphasis><literal>{text}</literal></emphasis></para>
<itemizedlist>
<listitem><para>identifying the technical committee section</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><legalnotice role="related"></literal><emphasis><literal>{content}</literal></emphasis></para>
<itemizedlist>
<listitem><para>identifying the related work section</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><legalnotice role="namespaces"></literal><emphasis><literal>{content}</literal></emphasis></para>
<itemizedlist>
<listitem><para>identifying the namespaces section</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><legalnotice role="status"></literal><emphasis><literal>{content}</literal></emphasis></para>
<itemizedlist>
<listitem><para>identifying the status section</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><articleinfo><legalnotice role="notices"></literal><emphasis><literal>{content}</literal></emphasis></para>
<itemizedlist>
<listitem><para>identifying the notices section</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><phrase role="keyword"></literal><emphasis><literal>{text}</literal></emphasis></phrase></para>
<itemizedlist>
<listitem><para>uppercase the text assuming the text is in English</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><table role="font-size-XX"></literal></para>
<itemizedlist>
<listitem>
<para>use a text font of XX for the content of cells in a table, as in <literal><table role="font-size-90%"></literal>:</para>
<table role="font-size-90%">
<title>Table with font size of 90%</title>
<tgroup cols="2">
<tbody>
<row>
<entry>row 1, column 1</entry>
<entry>row 1, column 2</entry>
</row>
<row>
<entry>row 2, column 1</entry>
<entry>row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</table>
<para>or as in <literal><table role="font-size-50%"></literal>:</para>
<table role="font-size-50%">
<title>Table with font size of 50%</title>
<tgroup cols="2">
<tbody>
<row>
<entry>row 1, column 1</entry>
<entry>row 1, column 2</entry>
</row>
<row>
<entry>row 2, column 1</entry>
<entry>row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</table>
<para>... rather than using the body font size:</para>
<table>
<title>Table with no use of font size role attribute</title>
<tgroup cols="2">
<tbody>
<row>
<entry>row 1, column 1</entry>
<entry>row 1, column 2</entry>
</row>
<row>
<entry>row 2, column 1</entry>
<entry>row 2, column 2</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
<listitem>
<para>note that the font actually rendered is up to the user agent and so any given size may end up being rendered using a built-in size (e.g. 90% interpreted as 100%)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><programlisting role="font-size-XX"></literal></para>
<itemizedlist>
<listitem>
<para>use a text font of XX for the content of text in a program listing, as in <literal><programlisting role="font-size-80%"></literal>:</para>
<programlisting role="font-size-80%">This is the text of a program listing where
newlines are reflected in the output and spacing " " is preserved.
</programlisting>
<para>or as in <literal><programlisting role="font-size-50%"></literal>:</para>
<programlisting role="font-size-50%">This is the text of a program listing where
newlines are reflected in the output and spacing " " is preserved.
</programlisting>
<para>... rather than using the body font size:</para>
<programlisting>This is the text of a program listing where
newlines are reflected in the output and spacing " " is preserved.
</programlisting>
</listitem>
<listitem>
<para>note that the font actually rendered is up to the user agent and so any given size may end up being rendered using a built-in size (e.g. 90% interpreted as 100%)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><?pb?></literal></para>
<itemizedlist>
<listitem><para>inject a page break (PDF only)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para><literal><?lb?></literal></para>
<itemizedlist>
<listitem><para>inject a line break</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section id="proforma">
<title> Pro forma template</title>
<para> This environment includes a pro forma template of a DocBook XML
instance with placeholders for all the OASIS specification metadata
found in the word processing templates. The XML template has one of
every item of metadata and can be used as a guideline when creating the
metadata for a new document. The prose of the document includes a
detailed narrative of the declaration and use of each of the metadata
components.</para>
<para> The template also includes some limited guidelines to the use of
the DocBook vocabulary that have been carried over from previous
versions of the documentation. With time it is hoped to embellish more
in this section for the benefit of the reader.</para>
<para> The pro forma template is included as part of the package of this
environment and if the document you are reading is part of a completely
installed collection then it can be found at <ulink
url="template/spectools-docbook-template-&stage;.xml"
>template/spectools-docbook-template-&stage;.xml</ulink> and rendered
at <ulink url="template/spectools-docbook-template-&stage;.html"
>template/spectools-docbook-template-&stage;.html</ulink>. Please see
<xref linkend="template"/> for an analysis of the XML
document.</para>
</section>
<section id="sassoc">
<title>
Stylesheet association</title>
<para>
Not included in the final published XML source of OASIS specifications are the stylesheet association <xref linkend="xml-assoc"/> processing instructions that are very handy conveniences to use during the authoring process. This methodology mandates their removal from the final published documents, but encourages their use when writing in order to streamline the writer's review of the formatted content.</para>
<para>
Stylesheet association is not widely employed in the general XML community, typically due to (a) limited awareness by writers of their benefit; and (b) limited conforming support in web browsers.</para>
<para>
An XSLT stylesheet association processing instruction is structured with two pseudo attributes as follows, indicating the type of the stylesheet being engaged and the location of the stylesheet file producing the HTML rendition:</para>
<programlisting><![CDATA[<?xml-stylesheet type="text/xsl" href="place-URL-here"?>
]]></programlisting>
<para>
The benefits of having embedded a stylesheet association processing instruction at the top of one's XML document are realized by opening the XML document being written in a web browser that (a) is aware of the processing instruction; (b) has a conforming XML processor with which to process the stylesheet files; and (c) has a conforming XSLT processor with which to engage the stylesheet files. The act of opening the XML document in the browser engages the HTML stylesheet against the XML content producing the HTML rendition on the browser canvas. At any time during the writing process, merely refreshing the web browser canvas re-engages the stylesheet producing the rendition of the revised content. This removes the necessity to engage the standalone invocation of the stylesheet environment to produce a reviewable rendition.</para>
<para>
For example, this document was authored in an environment where the locally-installed offline version of the publishing environment is available in the local directory <literal>../spec-&version;/</literal>, thus allowing the following stylesheet association processing instruction placed at the top of the XML file before the document type declaration to render the document in an XSLT-aware web browser:</para>
<programlisting><?xml-stylesheet type="text/xsl" href="file:///c:/oasis/
spec-&version;/stylesheets/oasis-specification-html.xsl"?>
</programlisting>
<para>
When a document is being authored in an environment where a copy of this publishing environment is embedded with the document directories, the following stylesheet association processing instruction would point to the embedded copy of the stylesheet fragment:</para>
<programlisting role="font-size-85%"><?xml-stylesheet type="text/xsl"
href="htmlruntime/spec-&version;/stylesheets/oasis-specification-html.xsl"?>
</programlisting>
<note>
<para>When embedding this stylesheet environment in a document's distribution environment, it is important to prune the stylesheet directories to retain only that which is required for HTML rendering. The only directories needed in the spec-&version;/docbook/xsl directory are: xsl/common, xsl/html and xsl/lib. All other directories should be removed.</para>
</note>
<para>
When a document is being authored in an environment where the remotely-installed online version of the publishing environment is to be used, the following stylesheet association processing instruction would work (modulo the latency aspects of accessing resources over the Internet):</para>
<programlisting><?xml-stylesheet type="text/xsl" href="http://docs.oasis-open.org/
templates/DocBook/spec-&version;/stylesheets/oasis-specification-html.xsl"?>
</programlisting>
<para>
Many people believe that stylesheet association is a transient property of an XML document and should not be included in any "official" normative XML content. This methodology, therefore, mandates that any such processing instruction that might be used by the author during the writing phase be removed from the final published XML instance.</para>
</section>
</section>
<appendix id="a.committee" role="non-normative">
<title>Acknowledgments</title>
<para>This specification environment was written with the generous and appreciated assistance of Paul Knight, Chet Ensign, Mary McRae, Will Norris and Jon Bosak.</para>
</appendix>
<appendix id="template">
<title>Sample specification template</title>
<para>
This section describes the instance structure and metadata of the DocBook XML instance <ulink url="template/spectools-docbook-template-&stage;.xml">template/spectools-docbook-template-&stage;.xml</ulink>, a template geared for use with the specification stylesheets. The summarized markup copied from the instance is split into successive <sgmltag>programlisting</sgmltag> fragments interspersed with a narrative regarding how to use the markup in the fragment. Braces "<literal>{}</literal>" are used to indicate replaceable information and the braces should not be in the final document. There is no obligation to use the techniques used below, though what is below is successfully producing the result you are reading.</para>
<para> For the purposes of example in the code below, the locally-installed
copy of the OASIS publishing environment is in the directory
<literal>c:/oasis/spec-0.6/</literal>.</para>
<para>
The XML Declaration uses <literal>ISO-8859-1</literal> instead of <literal>UTF-8</literal> as the content is being typed and remembering the two-byte codes of <literal>UTF-8</literal> is sometimes awkward. Alternatively, using <literal>US-ASCII</literal> limits the typing entirely to 7-bit ASCII characters, requiring accented and other high-bit characters to be entered with entities.</para>
<programlisting><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
]]></programlisting>
<para>
The following is an editing convenience keeping in an XML comment the PUBLIC and SYSTEM identifiers for the document type declaration for each of the online publishing environment, the embedded publishing environment and the local publishing environment. Note how the actual identifiers in this snippet are for the local publishing environment while in the instance you will find the online publishing environment set being used in the document type declaration. When switching back and forth it is a convenience to have a few lines handy for copy/paste, and these are provided at the top of this file (note the URIs for the embedded environment need to be adjusted according to where the directory is located; this snippet is appropriate for this specification document but not for the template location):</para>
<programlisting role="font-size-70%"><![CDATA[<!--
For use when a committee document points at the OASIS web site for publishing:
<?xml-stylesheet type="text/xsl"
href="http://docs.oasis-open.org/templates/DocBook/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
For use when a committee document points to an embedded runtime installation:
<?xml-stylesheet type="text/xsl"
href="htmlruntime/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"htmlruntime/spec-0.6/docbook/docbookx.dtd"
For use when a committee document is published in a local environment only
(note the instructions for local publishing require adjusting the stylesheet
and DocBook directories in these declarations):
<?xml-stylesheet type="text/xsl"
href="file:///c:/oasis/spec-0.6/stylesheets/oasis-specification-html-offline.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///c:/oasis/spec-0.6/docbook/docbookx.dtd"
-->
<?xml-stylesheet type="text/xsl"
href="http://docs.oasis-open.org/templates/DocBook/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
]]></programlisting>
<para>
In the above the XML Stylesheet Association <xref linkend="xml-assoc"/> processing instruction is used to render the XML as HTML for the reader. This is also useful during the authoring process as a convenience for reviewing the rendered version of the authored XML markup when the XML document is open in a conforming browser supporting the association of XSLT stylesheets. After saving any edits to the XML document it is only necessary to refresh the browser to view the rendered results, without requiring any intervening XSLT process.</para>
<para>
The internal declaration subset uses general entities in order to ensure consistent use of strings throughout the document. The <literal>&name;</literal> entity has the base name of the document. The <literal>&version;</literal> entity has the version of the document. The <literal>&standard;</literal> has the document status which is used in meta data and is often referenced in the prose along the lines of "<literal>This &standard; includes the ...</literal>".</para>
<programlisting role="font-size-75%"><![CDATA[[<!--the document properties-->
<!ENTITY name "spectools-docbook-template">
<!ENTITY pversion "0.3">
<!ENTITY version "0.6">
<!ENTITY stage "wd07">
<!ENTITY standard "Stage and revision / Alternate stage and revision">
<!ENTITY this-loc "http://docs.oasis-open.org/templates/DocBook/spec-&version;/template">
<!ENTITY previous-loc "http://docs.oasis-open.org/templates/DocBook/spec-&pversion;/template">
<!ENTITY latest-loc "http://docs.oasis-open.org/templates/DocBook/oasis-specification/template">
<!ENTITY pubdate "14 June 2012">
]]></programlisting>
<para>
The document element for OASIS standards is always <sgmltag>article</sgmltag>. The status, which can have different simultaneous status values separated by "/", is reflected in an attribute:</para>
<programlisting><![CDATA[<article status="&standard;">
]]></programlisting>
<para>
The metadata is kept in the DocBook <sgmltag>articleinfo</sgmltag> element, starting with the source code control, the name and the version of the document. The stylesheets can use the these information items in the synthesis of filenames (see <xref linkend="invokeparam"/>). Note the use of the entity references for consistency.</para>
<programlisting role="font-size-90%"><![CDATA[<articleinfo>
<title>Specification Title Version X.X</title>
<releaseinfo role="cvs"> $]]><![CDATA[Id: spectools-docbook-template-wd07.xml,v 1.7 2012/06/14 01:54:35 admin Exp $ </releaseinfo>
<productname>&name;</productname>
<productnumber>&stage;</productnumber>
<releaseinfo role="track">Standards Track Work Product</releaseinfo>
]]></programlisting>
<para>
The links to the various instantiations of the document and supporting materials are summarized using <literal>releaseinfo</literal> elements with the reserved roles (see <xref linkend="augmentations"/>) for as many files as you have. OASIS rules require the identification of the authoritative publication. Note again the use of the entity references for consistency.</para>
<programlisting><![CDATA[<releaseinfo role="OASIS-specification-this-authoritative"
>&this-loc;/&name;-&stage;.html</releaseinfo>
<releaseinfo role="OASIS-specification-this"
>&this-loc;/&name;-&stage;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-this"
>&this-loc;/&name;-&stage;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-previous"
>&previous-loc;/&name;.html</releaseinfo>
<releaseinfo role="OASIS-specification-previous"
>&previous-loc;/&name;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-previous"
>&previous-loc;/&name;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-latest-authoritative"
>&latest-loc;/&name;.html</releaseinfo>
<releaseinfo role="OASIS-specification-latest"
>&latest-loc;/&name;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-latest"
>&latest-loc;/&name;.xml</releaseinfo>
]]></programlisting>
<para>
The committee is indicated using <literal>role="committee"</literal>.</para>
<programlisting><![CDATA[<releaseinfo role="committee"><ulink url="http://www.oasis-open.org/
committees/">OASIS {official name of technical committee} TC</ulink>
</releaseinfo>
]]></programlisting>
<para>
The various people sited in the document are in the <sgmltag>authorgroup</sgmltag> element, using <sgmltag>editor</sgmltag> and <sgmltag>author</sgmltag> for their respective players, and the <sgmltag>othercredit</sgmltag> element for the committee chairs.</para>
<programlisting role="font-size-80%"><![CDATA[<authorgroup>
<editor>
<firstname>Jane</firstname>
<surname>Doe</surname>
<affiliation>
<orgname><ulink url="www.example.com">Example
Corporation</ulink></orgname>
</affiliation>
<email>jane.doe@example.com</email>
</editor>
<othercredit>
<firstname>Mary</firstname>
<surname>Baker</surname>
<affiliation>
<orgname>Another Corporation</orgname>
</affiliation>
<email>mary.baker@example.com</email>
</othercredit>
<othercredit>
<firstname>James</firstname>
<surname>Butcher</surname>
<affiliation>
<orgname>Associate Member</orgname>
</affiliation>
<email>james.butcher@example.com</email>
</othercredit>
</authorgroup>
]]></programlisting>
<para>
The publishing date is constrained by OASIS conventions to the following format:</para>
<programlisting><![CDATA[<pubdate>&pubdate;</pubdate>
]]></programlisting>
<para>
The copyright information is embedded using the <sgmltag>copyright</sgmltag> element, but note that this information has to be entered as well in the text of the notices.</para>
<programlisting><![CDATA[<copyright>
<year>YYYY</year>
<holder>OASIS Open, Inc. All Rights Reserved.</holder>
</copyright>
]]></programlisting>
<para>
When you want to relate this document to additional or related works use <sgmltag>legalnotice</sgmltag> with <literal>role="additional"</literal> or <literal>role="related"</literal>.</para>
<programlisting role="font-size-80%"><![CDATA[<legalnotice role="additional"><title>Additional Work Product artifacts</title>
<para>This prose specification is one component of a Work Product which also includes:</para>
...
</legalnotice>
<legalnotice role="related"><title>Related Work</title>
<para>This specification replaces or supersedes:</para>
...
</legalnotice>
]]></programlisting>
<para>
When you want to document the namespaces use <sgmltag>legalnotice</sgmltag> with <literal>role="namespaces"</literal>.</para>
<programlisting><![CDATA[<legalnotice role="namespaces">
<title>Declared XML namespaces</title>
<para><ulink url="http://docs.oasis-open.org/ns/{tc-shortname}/xxxx"
>http://docs.oasis-open.org/ns/{tc-shortname}/xxxx</ulink></para>
</legalnotice>
]]></programlisting>
<para>
The abstract has its own DocBook element.</para>
<programlisting><![CDATA[<abstract>
<para>{This specification defines...}</para>
</abstract>
]]></programlisting>
<para>
For the status use <sgmltag>legalnotice</sgmltag> with <literal>role="status"</literal>.</para>
<programlisting><![CDATA[<legalnotice role="status"><title>Status</title>
<para>{Describe the status and stability ...}</para>
...
</legalnotice>
]]></programlisting>
<para>
For the notices use <sgmltag>legalnotice</sgmltag> with <literal>role="notices"</literal> ensuring you use the appropriate version of the legal notices from the markup in this instance.</para>
<programlisting><![CDATA[<legalnotice role="notices"><title>Notices</title>
<para>Copyright © OASIS Open 20??. All Rights Reserved.</para>
...
</legalnotice>
]]></programlisting>
<para>
Thus ends the document metadata. The sections and annexes follow.</para>
<programlisting><![CDATA[</articleinfo>
<section id="s.introduction">
...
<appendix>
...
]]></programlisting>
</appendix>
<appendix id="orch" role="non-normative">
<title>Publishing choreography and orchestration</title>
<para>
There is no obligation to automate the publishing process by choreographing the invocation of validation and production processes, however this methodology offers example orchestrations of these. Note that but for not having a core Ant <xref linkend="ant"/> task for the invocation of an XSL-FO processor, these guidelines would include such an example using that cross-platform Java-based build tool. It that absence, therefore, this section describes both a Windows command prompt and a Linux shell prompt that you may wish to configure for your own use.</para>
<para>
The sample choreography invokes three separate processes in turn to produce the results. These processes are made available by Windows batch files and Linux shell scripts that are not included.</para>
<section>
<title>
Windows batch file preparation</title>
<para>The example Windows batch file choreography in <ulink url="template/spectools-docbook-template.bat">template/spectools-docbook-template.bat</ulink> assumes the presence of three support batch files on the command path summarized as follows:</para>
<itemizedlist>
<listitem>