source: rfc2629xslt/rfc2629xslt.txt @ 1664

Last change on this file since 1664 was 1661, checked in by julian.reschke@…, 8 years ago

update to latest version of rfc2629.xslt

  • Property svn:eol-style set to native
File size: 47.4 KB
Line 
1
2
3
4RFC2629 through XSLT                                          J. Reschke
5                                                              greenbytes
6                                                              March 2012
7
8
9            Transforming RFC2629-formatted XML through XSLT
10
11
12
13Table of Contents
14
15   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . ancho
16   2.  Supported RFC2629 elements  . . . . . . . . . . . . . . . . suppo
17     2.1.   Extension elements . . . . . . . . . . . . . . . . . . ancho
18   3.  Processing Instructions . . . . . . . . . . . . . . . . . . proce
19     3.1.   Supported xml2rfc-compatible PIs . . . . . . . . . . . ancho
20     3.2.   Unsupported xml2rfc-compatible PIs . . . . . . . . . . ancho
21     3.3.   Extension PIs  . . . . . . . . . . . . . . . . . . . . ancho
22   4.  Anchors . . . . . . . . . . . . . . . . . . . . . . . . . . ancho
23   5.  Supported XSLT engines  . . . . . . . . . . . . . . . . . . xslt.
24     5.1.   Standalone Engines . . . . . . . . . . . . . . . . . . ancho
25     5.2.   In-Browser Engines . . . . . . . . . . . . . . . . . . xslt.
26   6.  Transforming to HTML  . . . . . . . . . . . . . . . . . . . outpu
27     6.1.   HTML compliance  . . . . . . . . . . . . . . . . . . . ancho
28     6.2.   Standard HTML LINK elements  . . . . . . . . . . . . . html.
29     6.3.   Standard HTML metadata . . . . . . . . . . . . . . . . ancho
30     6.4.   Dublin Core (RFC2731) metadata . . . . . . . . . . . . rfc27
31     6.5.   Experimental hCard support . . . . . . . . . . . . . . hcard
32   7.  Transforming to XHTML . . . . . . . . . . . . . . . . . . . outpu
33   8.  Transforming to CHM (Microsoft Compiled Help) . . . . . . . outpu
34   9.  Transforming to PDF . . . . . . . . . . . . . . . . . . . . outpu
35     9.1.   Via XSL-FO . . . . . . . . . . . . . . . . . . . . . . outpu
36       9.1.1.  Extension feature matrix  . . . . . . . . . . . . . ancho
37       9.1.2.  Example: producing output for Apache FOP  . . . . . ancho
38     9.2.   Via X(HTML)  . . . . . . . . . . . . . . . . . . . . . outpu
39   10. Transforming to ePub  . . . . . . . . . . . . . . . . . . . outpu
40   11. Generic Extensions  . . . . . . . . . . . . . . . . . . . . exten
41     11.1.  <abnf-char-sequence> element . . . . . . . . . . . . . ext.e
42     11.2.  <anchor-alias> element . . . . . . . . . . . . . . . . ext.e
43     11.3.  <bcp14> element  . . . . . . . . . . . . . . . . . . . ext.e
44     11.4.  <bb> element . . . . . . . . . . . . . . . . . . . . . ext.e
45     11.5.  <bc> element . . . . . . . . . . . . . . . . . . . . . ext.e
46     11.6.  <blockquote> element . . . . . . . . . . . . . . . . . ext.e
47     11.7.  <boilerplate> element  . . . . . . . . . . . . . . . . ext.e
48     11.8.  <bt> element . . . . . . . . . . . . . . . . . . . . . ext.e
49     11.9.  <dfn> element  . . . . . . . . . . . . . . . . . . . . ext.e
50     11.10. <feedback> element . . . . . . . . . . . . . . . . . . ext.e
51     11.11. <h> element  . . . . . . . . . . . . . . . . . . . . . ext.e
52
53
54
55Reschke                                                         [Page 1]
56
57Documentation             RFC2629 through XSLT                March 2012
58
59
60     11.12. <highlight> element  . . . . . . . . . . . . . . . . . ext.e
61     11.13. <length-of> element  . . . . . . . . . . . . . . . . . ext.e
62     11.14. <link> element . . . . . . . . . . . . . . . . . . . . ext.e
63     11.15. <lt> element . . . . . . . . . . . . . . . . . . . . . ext.e
64     11.16. <note> element . . . . . . . . . . . . . . . . . . . . ext.e
65     11.17. <parse-xml> element  . . . . . . . . . . . . . . . . . ext.e
66     11.18. <prose> element  . . . . . . . . . . . . . . . . . . . ext.e
67     11.19. <q> element  . . . . . . . . . . . . . . . . . . . . . ext.e
68     11.20. <ref> element  . . . . . . . . . . . . . . . . . . . . ext.e
69     11.21. <source> element . . . . . . . . . . . . . . . . . . . ext.e
70     11.22. <sup> element  . . . . . . . . . . . . . . . . . . . . ext.e
71     11.23. Extensions to Xml2rfc <artwork> element  . . . . . . . ext-r
72     11.24. Extensions to Xml2rfc <iref> element . . . . . . . . . ext-r
73     11.25. Extensions to Xml2rfc <list> element . . . . . . . . . ext-r
74     11.26. Extensions to Xml2rfc <rfc> element  . . . . . . . . . ext-r
75     11.27. Extensions to Xml2rfc <section> element  . . . . . . . ext-r
76     11.28. Extensions to Xml2rfc <xref> element . . . . . . . . . ext-r
77   12. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . utili
78     12.1.  Checking References  . . . . . . . . . . . . . . . . . check
79     12.2.  Generating Graphs from References  . . . . . . . . . . ancho
80     12.3.  Producing reference entries for books  . . . . . . . . ancho
81     12.4.  Down-converting to RFC2629bis DTD  . . . . . . . . . . clean
82     12.5.  Extracting artwork . . . . . . . . . . . . . . . . . . extra
83     12.6.  GRRDL  . . . . . . . . . . . . . . . . . . . . . . . . grddl
84   13. Informative References  . . . . . . . . . . . . . . . . . . ancho
85   Appendix A.  RELAX NG Compact Schema  . . . . . . . . . . . . . gramm
86   Appendix B.  Implementation Notes . . . . . . . . . . . . . . . ancho
87     B.1.   Recognized type attributes for <artwork> element . . . ancho
88   Appendix C.  Examples . . . . . . . . . . . . . . . . . . . . . examp
89     C.1.   Using the 'Internal Subset'  . . . . . . . . . . . . . examp
90     C.2.   Customization  . . . . . . . . . . . . . . . . . . . . examp
91   Appendix D.  Producing the IETF 'Boilerplate' . . . . . . . . . boile
92     D.1.   The /rfc/@ipr Attribute  . . . . . . . . . . . . . . . attri
93       D.1.1.  Current Values: '*trust200902'  . . . . . . . . . . attri
94       D.1.2.  Historic Values . . . . . . . . . . . . . . . . . . attri
95     D.2.   The /rfc/@category Attribute . . . . . . . . . . . . . attri
96     D.3.   The /rfc/@submissionType Attribute . . . . . . . . . . attri
97     D.4.   The /rfc/@consensus Attribute  . . . . . . . . . . . . attri
98     D.5.   The /rfc/@number Attribute . . . . . . . . . . . . . . attri
99     D.6.   The /rfc/@docName Attribute  . . . . . . . . . . . . . attri
100     D.7.   The /rfc/@obsoletes Attribute  . . . . . . . . . . . . attri
101     D.8.   The /rfc/@updates Attribute  . . . . . . . . . . . . . attri
102   Appendix E.  License  . . . . . . . . . . . . . . . . . . . . . licen
103   Appendix F.  Change Logs  . . . . . . . . . . . . . . . . . . . ancho
104     F.1.   Package  . . . . . . . . . . . . . . . . . . . . . . . ancho
105     F.2.   amazon-asin.xslt . . . . . . . . . . . . . . . . . . . ancho
106     F.3.   check-references.xslt  . . . . . . . . . . . . . . . . ancho
107     F.4.   gen-reference-graph.xslt . . . . . . . . . . . . . . . ancho
108
109
110
111Reschke                                                         [Page 2]
112
113Documentation             RFC2629 through XSLT                March 2012
114
115
116     F.5.   rfc2629.xslt . . . . . . . . . . . . . . . . . . . . . ancho
117     F.6.   rfc2629toFO.xslt . . . . . . . . . . . . . . . . . . . ancho
118     F.7.   xsl11toAn.xslt . . . . . . . . . . . . . . . . . . . . ancho
119     F.8.   xsl11toFop.xslt  . . . . . . . . . . . . . . . . . . . ancho
120     F.9.   xsl11toXep.xslt  . . . . . . . . . . . . . . . . . . . ancho
121   Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . .     0
122   Author's Address  . . . . . . . . . . . . . . . . . . . . . . .     0
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
167Reschke                                                         [Page 3]
168
169Documentation             RFC2629 through XSLT                March 2012
170
171
1721.  Introduction
173
174   This document describes a set of XSLT transformations that can be
175   used to transform RFC2629-compliant XML (see [RFC2629]) to various
176   output formats, such as HTML and PDF.  The main topics are
177
178   o  compliance to the xml2rfc XML element set (Section 2),
179
180   o  support for xml2rfc processing instructions (Section 3),
181
182   o  the names of anchor elements generated in HTML and PDF output
183      (Section 4),
184
185   o  various XSLT engines that can be used (Section 5),
186
187   o  outputting HTML (Section 6) and XHTML (Section 7),
188
189   o  outputting CHM (Compiled Microsoft Help, Section 8),
190
191   o  outputting PDF (Section 9),
192
193   o  outputting ePub (Section 10),
194
195   o  extensions to the xml2rfc vocabulary (Section 11).
196
197   o  various utilities (Section 12).
198
199   The full distribution is available at
200   <http://greenbytes.de/tech/webdav/rfc2629xslt.zip>.
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223Reschke                                                         [Page 4]
224
225Documentation             RFC2629 through XSLT                March 2012
226
227
2282.  Supported RFC2629 elements
229
230   "rfc2629.xslt" supports both all RFC2629 grammar elements and the
231   extensions implemented in xml2rfc 1.36.
232
2332.1.  Extension elements
234
235   "rfc2629.xslt" supports two kind of extension elements, using
236   different XML namespaces.
237
238   The first set contains (hopefully) generally useful extensions, see
239   Section 11.
240
241   The second set is used for change and issue tracking and currently is
242   not documented here.  Please email the author in case you're
243   interested in using these extensions.
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
279Reschke                                                         [Page 5]
280
281Documentation             RFC2629 through XSLT                March 2012
282
283
2843.  Processing Instructions
285
286   All PIs can be set as XSLT parameter as well, overriding any value
287   that is found in the source file to be transformed.
288
289   Using processing instructions:
290
291   <?rfc toc="yes"?>
292   <?rfc-ext support-rfc2731="no"?>
293
294   Using XSLT parameters (Saxon):
295
296   java -cp saxon.jar com.icl.saxon.StyleSheet source.xml rfc2629.xslt \
297     xml2rfc-toc=yes xml2rfc-ext-support-rfc2731=no > result.html
298
299   Using XSLT parameters (xsltproc):
300
301   xsltproc --param xml2rfc-toc '"yes"' \
302      --param xml2rfc-ext-support-rfc2731 '"no"' \
303      rfc2629.xslt source.xml > result.html
304
305   (note the required quoting of string parameters)
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
335Reschke                                                         [Page 6]
336
337Documentation             RFC2629 through XSLT                March 2012
338
339
3403.1.  Supported xml2rfc-compatible PIs
341
342   +------+--------------+------------------+------------+-------------+
343   | PI   | PI           | XSLT parameter   | default    | comment     |
344   | targ | pseudo-attri | name             |            |             |
345   | et   | bute         |                  |            |             |
346   +------+--------------+------------------+------------+-------------+
347   | rfc  | background   | xml2rfc-backgrou | (not set)  |             |
348   |      |              | nd               |            |             |
349   |      |              |                  |            |             |
350   | rfc  | compact      | xml2rfc-compact  | "no"       | only        |
351   |      |              |                  |            | applies to  |
352   |      |              |                  |            | HTML output |
353   |      |              |                  |            | method when |
354   |      |              |                  |            | printing    |
355   |      |              |                  |            |             |
356   | rfc  | comments     | xml2rfc-comments | (not set)  |             |
357   |      |              |                  |            |             |
358   | rfc  | editing      | xml2rfc-editing  | "no"       |             |
359   |      |              |                  |            |             |
360   | rfc  | footer       | xml2rfc-footer   | (not set)  |             |
361   |      |              |                  |            |             |
362   | rfc  | header       | xml2rfc-header   | (not set)  |             |
363   |      |              |                  |            |             |
364   | rfc  | inline       | xml2rfc-inline   | (not set)  |             |
365   |      |              |                  |            |             |
366   | rfc  | iprnotified  | xml2rfc-iprnotif | "no"       |             |
367   |      |              | ied              |            |             |
368   |      |              |                  |            |             |
369   | rfc  | linkmailto   | xml2rfc-linkmail | "yes"      |             |
370   |      |              | to               |            |             |
371   |      |              |                  |            |             |
372   | rfc  | private      | xml2rfc-private  | (not set)  |             |
373   |      |              |                  |            |             |
374   | rfc  | refparent    | xml2rfc-private  | "Reference | Title for   |
375   |      |              |                  | s"         | References  |
376   |      |              |                  |            | sections    |
377   |      |              |                  |            | when        |
378   |      |              |                  |            | automatical |
379   |      |              |                  |            | ly inserted |
380   |      |              |                  |            |             |
381   | rfc  | rfcedstyle   | xml2rfc-rfcedsty | (not set)  | (limited    |
382   |      |              | le               |            | support)    |
383   |      |              |                  |            |             |
384   | rfc  | sortrefs     | xml2rfc-sortrefs | "no"       |             |
385   |      |              |                  |            |             |
386
387
388
389
390
391Reschke                                                         [Page 7]
392
393Documentation             RFC2629 through XSLT                March 2012
394
395
396   | rfc  | symrefs      | xml2rfc-symrefs  | "yes"      | The default |
397   |      |              |                  |            | has changed |
398   |      |              |                  |            | from "no"   |
399   |      |              |                  |            | to "yes" as |
400   |      |              |                  |            | of June 6,  |
401   |      |              |                  |            | 2007 and    |
402   |      |              |                  |            | xml2rfc     |
403   |      |              |                  |            | 1.33pre4.   |
404   |      |              |                  |            |             |
405   | rfc  | toc          | xml2rfc-toc      | "no"       |             |
406   |      |              |                  |            |             |
407   | rfc  | tocdepth     | xml2rfc-tocdepth | 99         |             |
408   |      |              |                  |            |             |
409   | rfc  | topblock     | xml2rfc-topblock | "yes"      |             |
410   +------+--------------+------------------+------------+-------------+
411
4123.2.  Unsupported xml2rfc-compatible PIs
413
414   +--------+------------------+---------------------------------------+
415   | PI     | PI               | comment                               |
416   | target | pseudo-attribute |                                       |
417   +--------+------------------+---------------------------------------+
418   | rfc    | include          | incompatible with XML/XSLT processing |
419   |        |                  | model, please use external entities   |
420   |        |                  | instead                               |
421   |        |                  |                                       |
422   | rfc    | needLines        |                                       |
423   |        |                  |                                       |
424   | rfc    | slides           |                                       |
425   |        |                  |                                       |
426   | rfc    | strict           |                                       |
427   |        |                  |                                       |
428   | rfc    | subcompact       |                                       |
429   |        |                  |                                       |
430   | rfc    | tocindent        | (defaults to "yes")                   |
431   |        |                  |                                       |
432   | rfc    | tocompact        |                                       |
433   +--------+------------------+---------------------------------------+
434
435
436
437
438
439
440
441
442
443
444
445
446
447Reschke                                                         [Page 8]
448
449Documentation             RFC2629 through XSLT                March 2012
450
451
4523.3.  Extension PIs
453
454   +------+-----------------+-----------------------+------+-----------+
455   | PI   | PI              | XSLT parameter name   | defa | descripti |
456   | targ | pseudo-attribut |                       | ult  | on        |
457   | et   | e               |                       |      |           |
458   +------+-----------------+-----------------------+------+-----------+
459   | rfc- | allow-markup-in | xml2rfc-allow-markup- | "no" | Enables   |
460   | ext  | -artwork        | in-artwork            |      | support   |
461   |      |                 |                       |      | for       |
462   |      |                 |                       |      | specific  |
463   |      |                 |                       |      | elements  |
464   |      |                 |                       |      | inside    |
465   |      |                 |                       |      | abstract  |
466   |      |                 |                       |      | elements  |
467   |      |                 |                       |      | (using    |
468   |      |                 |                       |      | this      |
469   |      |                 |                       |      | extension |
470   |      |                 |                       |      | makes the |
471   |      |                 |                       |      | document  |
472   |      |                 |                       |      | incompati |
473   |      |                 |                       |      | ble to    |
474   |      |                 |                       |      | the       |
475   |      |                 |                       |      | RFC2629bi |
476   |      |                 |                       |      | s DTD;    |
477   |      |                 |                       |      | see       |
478   |      |                 |                       |      | descripti |
479   |      |                 |                       |      | on of     |
480   |      |                 |                       |      | conversio |
481   |      |                 |                       |      | n XSLT in |
482   |      |                 |                       |      | Section 1 |
483   |      |                 |                       |      | 2.4).     |
484   |      |                 |                       |      |           |
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503Reschke                                                         [Page 9]
504
505Documentation             RFC2629 through XSLT                March 2012
506
507
508   | rfc- | authors-section | xml2rfc-ext-authors-s |      | When      |
509   | ext  |                 | ection                |      | "end",    |
510   |      |                 |                       |      | place the |
511   |      |                 |                       |      | authors   |
512   |      |                 |                       |      | section   |
513   |      |                 |                       |      | at the    |
514   |      |                 |                       |      | end (just |
515   |      |                 |                       |      | before    |
516   |      |                 |                       |      | the       |
517   |      |                 |                       |      | copyright |
518   |      |                 |                       |      | statement |
519   |      |                 |                       |      | s). This  |
520   |      |                 |                       |      | seems to  |
521   |      |                 |                       |      | be the    |
522   |      |                 |                       |      | preferred |
523   |      |                 |                       |      | order in  |
524   |      |                 |                       |      | the       |
525   |      |                 |                       |      | newest    |
526   |      |                 |                       |      | RFCs.     |
527   |      |                 |                       |      |           |
528   | rfc- | duplex          | xml2rfc-ext-duplex    | no   | When set  |
529   | ext  |                 |                       |      | to "yes", |
530   |      |                 |                       |      | format    |
531   |      |                 |                       |      | the PDF   |
532   |      |                 |                       |      | output    |
533   |      |                 |                       |      | for       |
534   |      |                 |                       |      | doublesid |
535   |      |                 |                       |      | ed        |
536   |      |                 |                       |      | printing. |
537   |      |                 |                       |      |           |
538   | rfc- | include-index   | xml2rfc-ext-include-i | "yes | When set  |
539   | ext  |                 | ndex                  | "    | to "no",  |
540   |      |                 |                       |      | no index  |
541   |      |                 |                       |      | will be   |
542   |      |                 |                       |      | generated |
543   |      |                 |                       |      | .         |
544   |      |                 |                       |      |           |
545   | rfc- | include-referen | xml2rfc-ext-include-r |      | When set  |
546   | ext  | ces-in-index    | eferences-in-index    |      | to "yes", |
547   |      |                 |                       |      | index     |
548   |      |                 |                       |      | entries   |
549   |      |                 |                       |      | are       |
550   |      |                 |                       |      | generated |
551   |      |                 |                       |      | for all   |
552   |      |                 |                       |      | reference |
553   |      |                 |                       |      | s.        |
554   |      |                 |                       |      |           |
555
556
557
558
559Reschke                                                        [Page 10]
560
561Documentation             RFC2629 through XSLT                March 2012
562
563
564   | rfc- | justification   | xml2rfc-ext-justifica | "nev | "never":  |
565   | ext  |                 | tion                  | er"  | never     |
566   |      |                 |                       |      | emit      |
567   |      |                 |                       |      | justified |
568   |      |                 |                       |      | text,     |
569   |      |                 |                       |      | "always": |
570   |      |                 |                       |      | always    |
571   |      |                 |                       |      | emit      |
572   |      |                 |                       |      | justified |
573   |      |                 |                       |      | text,     |
574   |      |                 |                       |      | "print":  |
575   |      |                 |                       |      | only emit |
576   |      |                 |                       |      | justified |
577   |      |                 |                       |      | text for  |
578   |      |                 |                       |      | print     |
579   |      |                 |                       |      | media.    |
580   |      |                 |                       |      |           |
581   | rfc- | parse-xml-in-ar | xml2rfc-parse-xml-in- | "no" | May be    |
582   | ext  | twork           | artwork               |      | used to   |
583   |      |                 |                       |      | enable    |
584   |      |                 |                       |      | parsing   |
585   |      |                 |                       |      | of XML    |
586   |      |                 |                       |      | content   |
587   |      |                 |                       |      | in        |
588   |      |                 |                       |      | figures   |
589   |      |                 |                       |      | (MSXML    |
590   |      |                 |                       |      | only).    |
591   |      |                 |                       |      |           |
592   | rfc- | support-rfc2731 | xml2rfc-ext-support-r | "yes | Decides   |
593   | ext  |                 | fc2731                | "    | whether   |
594   |      |                 |                       |      | the HTML  |
595   |      |                 |                       |      | transform |
596   |      |                 |                       |      | ation     |
597   |      |                 |                       |      | should    |
598   |      |                 |                       |      | generate  |
599   |      |                 |                       |      | META tags |
600   |      |                 |                       |      | according |
601   |      |                 |                       |      | Section 6 |
602   |      |                 |                       |      | .4.       |
603   |      |                 |                       |      |           |
604
605
606
607
608
609
610
611
612
613
614
615Reschke                                                        [Page 11]
616
617Documentation             RFC2629 through XSLT                March 2012
618
619
620   | rfc- | sec-no-trailing | xml2rfc-ext-sec-no-tr |      | When set  |
621   | ext  | -dots           | ailing-dots           |      | to "yes", |
622   |      |                 |                       |      | add       |
623   |      |                 |                       |      | trailing  |
624   |      |                 |                       |      | dots to   |
625   |      |                 |                       |      | section   |
626   |      |                 |                       |      | numbers.  |
627   |      |                 |                       |      | This      |
628   |      |                 |                       |      | seems to  |
629   |      |                 |                       |      | be the    |
630   |      |                 |                       |      | preferred |
631   |      |                 |                       |      | format in |
632   |      |                 |                       |      | the       |
633   |      |                 |                       |      | newest    |
634   |      |                 |                       |      | RFCs.     |
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
671Reschke                                                        [Page 12]
672
673Documentation             RFC2629 through XSLT                March 2012
674
675
6764.  Anchors
677
678   The transformation automatically generates anchors that are supposed
679   to be stable and predictable and that can be used to identify
680   specific parts of the document.  Anchors are generated both in HTML
681   and XSL-FO content (but the latter will only be used for PDF output
682   when the XSL-FO engine supports producing PDF anchors).
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
727Reschke                                                        [Page 13]
728
729Documentation             RFC2629 through XSLT                March 2012
730
731
732                 The following anchors get auto-generated:
733
734     +-----------------------+---------------------------------------+
735     | Anchor name           | Description                           |
736     +-----------------------+---------------------------------------+
737     | rfc.abstract          | Abstract                              |
738     |                       |                                       |
739     | rfc.authors           | Authors section                       |
740     |                       |                                       |
741     | rfc.copyright         | Copyright section                     |
742     |                       |                                       |
743     | rfc.copyrightnotice   | Copyright notice                      |
744     |                       |                                       |
745     | rfc.figure._n_        | Figures (titled)                      |
746     |                       |                                       |
747     | rfc.figure.u._n_      | Figures (untitled)                    |
748     |                       |                                       |
749     | rfc.index             | Index                                 |
750     |                       |                                       |
751     | rfc.ipr               | Intellectual Property                 |
752     |                       |                                       |
753     | rfc.iref._n_          | Internal references                   |
754     |                       |                                       |
755     | rfc.note._n_          | Notes (from front section)            |
756     |                       |                                       |
757     | rfc.references        | References                            |
758     |                       |                                       |
759     | rfc.references._n_    | Additional references                 |
760     |                       |                                       |
761     | rfc.section._n_       | Section _n_                           |
762     |                       |                                       |
763     | rfc.section._n_.p._m_ | Section _n_, paragraph _m_            |
764     |                       |                                       |
765     | rfc.status            | Status of memo                        |
766     |                       |                                       |
767     | rfc.table._n_         | Tables (titled)                       |
768     |                       |                                       |
769     | rfc.table.u._n_       | Tables (untitled)                     |
770     |                       |                                       |
771     | rfc.toc               | Table of contents                     |
772     |                       |                                       |
773     | rfc.xref._name_._n_   | References to reference _n_ to _name_ |
774     +-----------------------+---------------------------------------+
775
776
777
778
779
780
781
782
783Reschke                                                        [Page 14]
784
785Documentation             RFC2629 through XSLT                March 2012
786
787
7885.  Supported XSLT engines
789
790   The transformation requires a non-standard extension function (see
791   exsl:node-set [1]) which is however widely available.  XSLT
792   processors that do not support this extension (or a functional
793   equivalent, such as msxsl:node-set) currently are not supported.
794
795   Input documents do not always specify the date completely.  In this
796   case, the transformation attempts to let the XSLT engine to compute
797   the system date, using either scripting in Microsoft's XSLT engine,
798   or the exsl:date-time [2] extension function.
799
8005.1.  Standalone Engines
801
802   The following XSLT engines are believed to work well:
803
804   o  Windows: MSXML3 and MSXML4 (<http://msdn.microsoft.com/xml>;
805      command line processor "msxsl" is available from Microsoft
806      Download Center [3])
807
808   o  Java: Saxon (<http://saxon.sourceforge.net/>)
809
810   o  Java: Xalan (<http://xml.apache.org/xalan-j/>)
811
812   o  C/C++: xsltproc (libxslt) (<http://xmlsoft.org/XSLT/>, make sure
813      that you have a current version)
814
8155.2.  In-Browser Engines
816
817   The following browsers seem to work fine:
818
819   o  Internet Explorer 5.5 (Windows version, if MSXML3 is installed)
820
821   o  Internet Explorer 6 and newer
822
823   o  Firefox 3.0 and newer
824
825
826      *  Be aware that XSLT execution can be suppressed using
827         NoScript [4]
828
829      *  Firefox does not load external DTDs nor external entities, see
830         Mozilla Bug 22942 [5], thus entities like &nbsp; need to be
831         declared in the internal subset (Appendix C.1)
832
833      *  There seems to be a new problem in Firefox 4 where it
834         occasionally does the initial rendering with the wrong width
835         (people who can reproduce this problem please comment on
836
837
838
839Reschke                                                        [Page 15]
840
841Documentation             RFC2629 through XSLT                March 2012
842
843
844         <https://bugzilla.mozilla.org/show_bug.cgi?id=640390>.
845
846      *  Date computation is available in Firefox starting with Firefox
847         6 (see <https://bugzilla.mozilla.org/show_bug.cgi?id=603159>)
848
849   o  Safari 3 (starting with version 3.0.4)
850
851
852      *  Date computation not available (see
853         <https://bugs.webkit.org/show_bug.cgi?id=4079>)
854
855   o  Google Chrome
856
857
858      *  Date computation not available (see
859         <https://bugs.webkit.org/show_bug.cgi?id=4079>)
860
861   o  Opera (starting with version 10)
862
863
864      *  Date computation not available
865
866   The following browsers are known not to work properly:
867
868   o  Firefox 1.*/2.*: (missing extension function - see change request
869      at Mozilla BugZilla 193678 [6])
870
871   o  Opera 9.21: execution fails, potentially to a somewhat complex
872      XPath expression (reported to Opera as bug 245725).
873
874   o  Opera 9.5 and 9.6: transformation appears to work, but CSS isn't
875      getting applied (reported to Opera as bug 337388 on 2008-06-12).
876
877   o  Safari 2.* supports client-side XSLT as of MacOS X 10.4, but
878      misses required extension functions.  A problem with stylesheets
879      producing non-ASCII output (such as NBSP characters) has been
880      fixed as of OSX 10.4.4.  Both problems have been reported through
881      Apple's bug tracking system, see <http://drakken.dbc.mtview.ca.us/
882      pipermail/xml2rfc/2005-May/002073.html> and
883      <http://bugs.webkit.org/show_bug.cgi?id=4079>.
884
885
886
887
888
889
890
891
892
893
894
895Reschke                                                        [Page 16]
896
897Documentation             RFC2629 through XSLT                March 2012
898
899
9006.  Transforming to HTML
901
902   Transformation to HTML can be done inside the browser if it supports
903   XSLT.  To enable this, add the following processing instruction to
904   the start of the source file:
905
906     <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
907
908   (and ensure that "rfc2629.xslt" is present).
909
9106.1.  HTML compliance
911
912   The transformation result is supposed to conform to the HTML 4.01
913   strict DTD [HTML].  This can be checked using the W3C's online
914   validator at <http://validator.w3.org>.
915
9166.2.  Standard HTML LINK elements
917
918   LINK elements exist since HTML 2.0.  They can be used to embed
919   content-independant links inside the document.  Unfortunately, only
920   few user agents support this element.  Firefox users may want to
921   check the Link Widgets [7] extension.
922
923                 The following LINK elements are produced:
924
925   +-----------+-------------------------------------------------------+
926   | LINK type | description                                           |
927   +-----------+-------------------------------------------------------+
928   | alternate | for RFCs, a link to the authorative ASCII version on  |
929   |           | the IETF web site                                     |
930   |           |                                                       |
931   | appendic  | pointer to all top-level appendics                    |
932   |           |                                                       |
933   | author    | pointer to "authors" section                          |
934   |           |                                                       |
935   | chapter   | pointer to all top-level sections                     |
936   |           |                                                       |
937   | contents  | pointer to table of contents                          |
938   |           |                                                       |
939   | copyright | pointer to copyright statement                        |
940   |           |                                                       |
941   | index     | pointer to index                                      |
942   +-----------+-------------------------------------------------------+
943
944   The figure below shows how Mozilla Firefox 1.0 displays the Site
945   Navigation Bar for rfc2396.xml.
946
947
948
949
950
951Reschke                                                        [Page 17]
952
953Documentation             RFC2629 through XSLT                March 2012
954
955
9566.3.  Standard HTML metadata
957
958          The following standard HTML META elements are produced:
959
960      +-----------+-------------------------------------------------+
961      | META name | description                                     |
962      +-----------+-------------------------------------------------+
963      | generator | from XSLT engine version and stylesheet version |
964      |           |                                                 |
965      | keywords  | from keyword elements in front section          |
966      +-----------+-------------------------------------------------+
967
9686.4.  Dublin Core (RFC2731) metadata
969
970   Unless turned off using the "rfc-ext support-rfc2731" processing
971   instruction, the transformation will generate metadata according to
972   [RFC2731] and [DC-HTML].
973
974                The following DCMI properties are produced:
975
976   +-------------------------+-----------------------------------------+
977   | META name               | description                             |
978   +-------------------------+-----------------------------------------+
979   | DC.Creator              | from author information in front        |
980   |                         | section                                 |
981   |                         |                                         |
982   | DC.Date.Issued          | from date information in front section  |
983   |                         |                                         |
984   | DC.Description.Abstract | from abstract                           |
985   |                         |                                         |
986   | DC.Identifier           | document URN [RFC2648] from "docName"   |
987   |                         | attribute                               |
988   |                         |                                         |
989   | DC.isPartOf             | RFC ISSN (for RFCs)                     |
990   |                         |                                         |
991   | DC.Relation.Replaces    | from "obsoletes" attribute              |
992   +-------------------------+-----------------------------------------+
993
9946.5.  Experimental hCard support
995
996   The generated author information is formatted in hCard [8] format.
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007Reschke                                                        [Page 18]
1008
1009Documentation             RFC2629 through XSLT                March 2012
1010
1011
10127.  Transforming to XHTML
1013
1014   Transforming to XHTML requires slightly different XSLT output options
1015   and is implemented by the derived transformation script
1016   "rfc2629toXHTML.xslt".
1017
1018      Note: Microsoft Internet Explorer does _not_ support XHTML.
1019      Therefore it usually makes more sense to generate plain old HTML.
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063Reschke                                                        [Page 19]
1064
1065Documentation             RFC2629 through XSLT                March 2012
1066
1067
10688.  Transforming to CHM (Microsoft Compiled Help)
1069
1070   To generate a CHM file using Microsoft's HTML Help Compiler (hhc),
1071   three files are required in addition to the HTML file.
1072
1073   1.  hhc - table of contents file (HTML)
1074
1075   2.  hhk - index file (HTML)
1076
1077   3.  hhp - project file (plain text)
1078
1079   The three files are generated with three specific transformations,
1080   each requiring the additional XSLT parameter "basename" to specify
1081   the filename prefix.
1082
1083   Example:
1084
1085   saxon rfc2616.xml rfc2629toHhp.xslt basename=rfc2616  > rfc2616.hhp
1086   saxon rfc2616.xml rfc2629toHhc.xslt basename=rfc2616  > rfc2616.hhc
1087   saxon rfc2616.xml rfc2629toHhk.xslt basename=rfc2616  > rfc2616.hhk
1088   hhc rfc2616.hhp
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119Reschke                                                        [Page 20]
1120
1121Documentation             RFC2629 through XSLT                March 2012
1122
1123
11249.  Transforming to PDF
1125
11269.1.  Via XSL-FO
1127
1128   Transformation to XSL-FO [XSL-FO] format is available through
1129   "rfc2629toFO.xslt" (which includes "rfc2629.xslt", so keep both in
1130   the same folder).
1131
1132   Compared to HTML user agents, XSL-FO engines unfortunately either
1133   come as open source (for instance, Apache FOP) or feature-complete
1134   (for instance, AntennaHouse XSL Formatter), but not both at the same
1135   time.
1136
1137   As Apache FOP needs special workarounds (index generation), and some
1138   popular extensions aren't standardized yet, the translation produces
1139   a generic output (hopefully) conforming to [XSL-FO].  Specific
1140   backends ("xsl11toFop.xslt", "xsl11toXep.xslt", "xsl11toAn.xslt")
1141   then provide post-processing for the individual processors.
1142
1143      Note: the output is currently targeted at Apache FOP 1.0.
1144
11459.1.1.  Extension feature matrix
1146
1147   +------------+-------------+------------+-------------+-------------+
1148   |            | PDF anchors |     PDF    |     PDF     |    Index    |
1149   |            |             |  bookmarks |   document  |   cleanup   |
1150   |            |             |            | information |             |
1151   +------------+-------------+------------+-------------+-------------+
1152   | XSL 1.1    | no, but can |     yes    |   no, but   |     yes     |
1153   | WD [9]     |      be     |            |   uses XEP  |             |
1154   |            | auto-genera |            |    output   |             |
1155   |            |   ted from  |            |  extensions |             |
1156   |            |     "id"    |            |             |             |
1157   |            |  attributes |            |             |             |
1158   |            |             |            |             |             |
1159   | Antenna    |      no     |  yes [11]  |   yes [11]  |   yes [11]  |
1160   | House XSL  |             |  (from XSL |  (from XEP  |  (just page |
1161   | formatter  |             |     1.1    |   document  |  duplicate  |
1162   | [10]       |             | bookmarks) |    info)    | elimination |
1163   |            |             |            |             |  , from XSL |
1164   |            |             |            |             |   1.1 page  |
1165   |            |             |            |             |    index)   |
1166   |            |             |            |             |             |
1167   | Apache     |     yes     |  yes (from |     yes     |      no     |
1168   | FOP [12]   |             |   XSL 1.1  |             |             |
1169   |            |             | bookmarks) |             |             |
1170   |            |             |            |             |             |
1171
1172
1173
1174
1175Reschke                                                        [Page 21]
1176
1177Documentation             RFC2629 through XSLT                March 2012
1178
1179
1180   | RenderX    |      no     |  yes [14]  |   yes [14]  |   yes [14]  |
1181   | XEP [13]   |             |  (from XSL |             |  (from XSL  |
1182   |            |             |     1.1    |             |   1.1 page  |
1183   |            |             | bookmarks) |             |    index)   |
1184   +------------+-------------+------------+-------------+-------------+
1185
11869.1.2.  Example: producing output for Apache FOP
1187
1188   Example:
1189
1190   saxon rfc2616.xml rfc2629toFo.xslt > tmp.fo
1191   saxon tmp.fo xsl11toFop.xslt > rfc2629.fo
1192
11939.2.  Via X(HTML)
1194
1195   PDF output can also be produced directly from (X)HTML.  One simple
1196   approach is to rely on the browser's printing function, and to use a
1197   printer driver that produces PDF.  Depending on the brower's CSS
1198   capabilities, the output will behave properly with respect to table
1199   breaks etc.
1200
1201   An alternative is PrinceXML (see <http://www.princexml.com/>), which
1202   can produce PDF directly from (X)HTML input, based on the CSS
1203   printing information.
1204
1205   For instance, PDF output with text justification turned on can be
1206   produced with:
1207
1208   saxon input.xml rfc2629toXHTML.xslt xml2rfc-ext-justification=print \
1209     > output.xhtml
1210   prince output.xhtml output.pdf
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231Reschke                                                        [Page 22]
1232
1233Documentation             RFC2629 through XSLT                March 2012
1234
1235
123610.  Transforming to ePub
1237
1238   Experimental transformation to ePub format is available through a set
1239   of stylesheets, and the Unix Shell script "mkepub.sh" (which requires
1240   that "zip" and either "saxon" or "xsltproc" are installed).
1241
1242   For instance, an epub version of rfc2616.xml can be generated like
1243   this:
1244
1245   mkepub.sh rfc2616.xml
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287Reschke                                                        [Page 23]
1288
1289Documentation             RFC2629 through XSLT                March 2012
1290
1291
129211.  Generic Extensions
1293
1294   This section documents extensions implemented in "rfc2629.xslt",
1295   using the extension namespace "http://purl.org/net/xml2rfc/ext".
1296
129711.1.  <abnf-char-sequence> element
1298
1299   Converts the contained quoted string into a hex-encoded character
1300   sequence, for use in case-sensitive ABNF productions.
1301
1302   For instance, "<x:abnf-char-sequence>"HTTP"</x:abnf-char-sequence>"
1303   gets converted to "%x48.54.54.50".
1304
130511.2.  <anchor-alias> element
1306
1307   Using its "value" attribute, this element allows the definition of an
1308   internal link target alias for the enclosing element.  This alias can
1309   then be used with the <ref> element for intra-document references.
1310
1311   Note that the anchor alias is not subject to the naming constraints
1312   that apply to anchor elements (which are XML names).
1313
131411.3.  <bcp14> element
1315
1316   This element marks the content as being one of the normative keywords
1317   defined in [RFC2119].
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343Reschke                                                        [Page 24]
1344
1345Documentation             RFC2629 through XSLT                March 2012
1346
1347
1348   The DOCTYPE definition below allows using these keywords using XML
1349   entity expansion: such as in "...server &MUST; accept...".
1350
1351   <!DOCTYPE rfc [
1352    <!ENTITY MAY "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1353      >MAY</bcp14>">
1354    <!ENTITY MUST "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1355      >MUST</bcp14>">
1356    <!ENTITY MUST-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1357      >MUST NOT</bcp14>">
1358    <!ENTITY OPTIONAL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1359      >OPTIONAL</bcp14>">
1360    <!ENTITY RECOMMENDED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1361      >RECOMMENDED</bcp14>">
1362    <!ENTITY REQUIRED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1363      >REQUIRED</bcp14>">
1364    <!ENTITY SHALL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1365      >SHALL</bcp14>">
1366    <!ENTITY SHALL-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1367      >SHALL NOT</bcp14>">
1368    <!ENTITY SHOULD "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1369      >SHOULD</bcp14>">
1370    <!ENTITY SHOULD-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'
1371      >SHOULD NOT</bcp14>">]>
1372
137311.4.  <bb> element
1374
1375   Marking up a string as <bb> indicates that it represents the bottom
1376   line of a box drawing, replacing the "+" and "-" characters
1377   accordingly.
1378
137911.5.  <bc> element
1380
1381   Marking up a string as <bc> indicates that it represents a center
1382   line of a box drawing, replacing the "|" character accordingly.
1383
138411.6.  <blockquote> element
1385
1386   This element is like the "blockquote" element in [HTML] (note this is
1387   a block-level element!).  It should contain one or more <t> child
1388   elements.
1389
139011.7.  <boilerplate> element
1391
1392   Can be used to include boilerplate (status, copyright, ...) into the
1393   front or back section. <section> elements within <x:boilerplate>
1394   appear as unnumbered sections in the output.
1395
1396
1397
1398
1399Reschke                                                        [Page 25]
1400
1401Documentation             RFC2629 through XSLT                March 2012
1402
1403
1404   _This element currently can not be "down-translated" for use in
1405   xml2rfc!_
1406
140711.8.  <bt> element
1408
1409   Marking up a string as <bt> indicates that it represents the top line
1410   of a box drawing, replacing the "+" and "-" characters accordingly.
1411
141211.9.  <dfn> element
1413
1414   This element is like the "dfn" element in [HTML].
1415
141611.10.  <feedback> element
1417
1418   This elements allows declaring a feedback link for document
1419   reviewers.  The template string takes the form of a URI template,
1420   such as:
1421
1422<x:feedback template="mailto:ietf-http-wg@w3.org?subject={docname},%20%22{section}%22&amp;body=&lt;{ref}&gt;:"/>
Note: See TracBrowser for help on using the repository browser.