-
Notifications
You must be signed in to change notification settings - Fork 14
/
Copy pathFAQ-xml2rfcv3.xml
1543 lines (1355 loc) · 49.3 KB
/
FAQ-xml2rfcv3.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='utf-8'?>
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" obsoletes="" updates=""
docName="FAQ-xml2rfcv3-15" submissionType="IETF" category="info" xml:lang="en" version="3"
ipr="none" tocInclude="true" consensus="no" symRefs="true" sortRefs="true">
<!-- xml2rfc v2v3 conversion 2.17.0 -->
<!-- It is intended for the HTML output to be read, not the text output. -->
<front>
<title abbrev="xml2rfc FAQ">xml2rfc Frequently Asked Questions</title>
<author initials="A." surname="Russo" fullname="Alice Russo">
<organization>RFC Production Center</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date/>
<abstract>
<t>
This is a list of frequently asked questions regarding xml2rfc, a tool
that can be used to create Internet-Drafts or RFCs.</t>
<t><strong>This FAQ is for version 3 of xml2rfc; the vocabulary has been
changed significantly from version 2.</strong> For guidance on version
2, please see the <eref
target="https://www.rfc-editor.org/materials/xml2rfcFAQ.html">FAQ for xml2rfc
v2</eref>.
</t>
</abstract>
<note>
<name>Note</name>
<t>This document has been replaced by <eref target="https://authors.ietf.org"/>.
</t>
</note>
</front>
<middle>
<!-- THE BASICS -->
<section numbered="true" toc="default">
<name>The Basics</name>
<section numbered="true" toc="default">
<name>What is xml2rfc?</name>
<t>
xml2rfc is a tool that lets you convert an XML source file into a text, HTML,
PDF, expanded XML file, or various other options. It is available as
a web-based service (<eref target="https://author-tools.ietf.org/"/>) or for download (<eref target="https://pypi.org/project/xml2rfc/"/>. Version 3 of the tool adds new
features and is used by the RFC Editor to create RFCs.
</t>
</section>
<section numbered="true" toc="default">
<name>Why should I use xml2rfc?</name>
<t>
It's an easy way to create an Internet-Draft in the proper
format. It handles boilerplate text and reference text. The HTML
and PDF output formats have new features (such as including SVG figures and non-ASCII
characters), and the source file can be used for metadata
extraction. Also, the RFC Editor will make use of your source file.
(For background, see the <eref target="https://www.rfc-editor.org/rse/format-faq/">RFC Format FAQ</eref>.)
</t>
</section>
<section numbered="true" toc="default">
<name>How much XML do I need to know?</name>
<t>
You need the essentials. XML uses start and end tags, which are
nested and matching, and they are case-sensitive. See
"XML basics" in <xref target="howto" format="title"/> for
more details.
</t>
</section>
<section numbered="true" toc="default">
<name>Where can I get more information?</name>
<ul>
<li>Web service to convert a file: <eref
target="https://author-tools.ietf.org"/> (Previously: <eref target="https://xml2rfc.tools.ietf.org/experimental.html"/>)</li>
<li>
The v3 vocabulary: See <eref
target="https://xml2rfc.tools.ietf.org/xml2rfc-doc.html">"Xml2rfc
Vocabulary Version 3 Schema"</eref>.
(Earlier documentation is in <xref target="RFC7991"/> and <xref
target="I-D.levkowetz-xml2rfc-v3-implementation-notes"/>.)
</li>
<li>The schema in RelaxNG: <eref
target="https://svn.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc">v3.rnc</eref>
(which includes the schema of the SVG profile: <eref target="https://svn.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/SVG-1.2-RFC.rnc">SVG-1.2-RFC.rnc</eref>).</li>
<li>
xml2rfc mailing list: <eref target="https://www.ietf.org/mailman/listinfo/xml2rfc"/>
</li>
<li>Report a bug in xml2rfc: <eref
target="https://trac.ietf.org/tools/xml2rfc/trac/report/1"/></li>
</ul>
</section>
</section>
<!-- CREATING A DRAFT -->
<section numbered="true" toc="default" anchor="s_creating_draft">
<name>Creating a Draft</name>
<section numbered="true" toc="default">
<name>What's the recommended setup?</name>
<t>
You have several choices when getting started with xml2rfc, such as:
</t>
<ul spacing="normal">
<li>
Use the tool on the web (<eref target="https://author-tools.ietf.org"/> via UI or API) or install it locally (<eref target="https://pypi.org/project/xml2rfc"/>).
</li>
<li>
Use the citation libraries online or maintain a local copy.
</li>
<li>
Edit in your favorite editor or use an XML editor.
</li>
</ul>
<t>
There are also tools available to let you edit non-XML source and then compile
it to xml2rfc XML:
</t>
<ul spacing="normal">
<li>
<eref target="https://github.com/cabo/kramdown-rfc2629">kramdown-rfc2629</eref>
</li>
<li>
<eref target="https://mmark.miek.nl/post/about/">mmark</eref>
</li>
</ul>
<t>
If you intend to host your draft in <tt>git</tt> or on Github, see
<eref target="https://ietf-gitwg.github.io/"></eref> for advice.
</t>
</section>
<section anchor="q_templates" numbered="true" toc="default">
<name>Where can I get a template?</name>
<t>
There is a v3 template available here: <eref
target="https://tools.ietf.org/tools/templates/draft-davies-template-bare-07.xml"/>. In
addition, several templates for xml2rfc v2 are available
from <xref target="templates" format="default">https://tools.ietf.org/tools/templates</xref>. They
include templates for a generic draft (e.g., draft-davies-template-bare.xml), as well as for a draft
containing a MIB module (e.g., mib-doc-template-xml.txt).
</t>
</section>
<section numbered="true" toc="default">
<name>How can I do it without a template?</name>
<t>
You can convert an existing XML file from the v2 vocabulary to the v3
vocabulary using xml2rfc --v2v3 (see <xref target="q_convert_v2v3"/>), and go
from there. Use <t> elements for paragraphs, and
<figure><artwork> elements for figures. Use <![CDATA[
... ]]> within <sourcecode> or <artwork> elements that contain
the less than character (<). (See <xref target="q_CDATA" format="title"/>
for more information.)
</t>
<t>
To get a citation like "[RFC2119]", use <tt><xref
target="RFC2119"/></tt>. See <xref target="s_using_refs" format="title"/> for more information.
</t>
</section>
<section numbered="true" toc="default">
<name>How do I use the <tt>rfc</tt> element to create an Internet-Draft?</name>
<t>
Use the <tt>category</tt> attribute to indicate the intended category of your
draft, where <tt>std</tt> is Standards Track, <tt>info</tt> is
Informational, <tt>exp</tt> is Experimental, <tt>bcp</tt> is Best Current
Practice, and <tt>historic</tt> is Historic.
</t>
<t>Use the <tt>submissionType</tt> attribute to indicate the intended
document stream, where the value can be <tt>IETF</tt>, <tt>IAB</tt>,
<tt>IRTF</tt>, or <tt>independent</tt>.</t>
<t>
See <xref target="RFC7991" sectionFormat="of" section="A.1"/> for information about the ipr attribute.
</t>
<t>
Use the docName attribute to indicate the filename.
</t>
<t>
If the document potentially updates or obsoletes any RFCs, use the
updates and obsoletes attributes to indicate the relevant RFC
numbers. For Internet-Drafts, this information will be displayed in
the header, followed by "(if approved)".
</t>
<t>
For example, putting it together:
</t>
<sourcecode type="xml"><![CDATA[
<rfc
xmlns:xi="http://www.w3.org/2001/XInclude"
category="info"
submissionType="IETF"
ipr="trust200902"
docName="draft-ietf-wgname-topic-00"
updates="1234, 1235"
obsoletes="1236"
sortRefs="true"
version="3">
]]></sourcecode>
<t>
Note: The attributes number and seriesNo will be added by the RFC Editor
if your draft is approved for publication as an RFC.
</t>
<t>
Note: Some features that used to be processing instructions (in v2)
are now attributes of the rfc element (in v3) -- for
example, <tt>sortRefs</tt> and <tt>symRefs</tt>.
</t>
</section>
</section>
<!-- USING REFERENCES -->
<section anchor="s_using_refs" numbered="true" toc="default">
<name>Using References</name>
<section numbered="true" toc="default" anchor="q_add_reference">
<name>How do I put in a reference?</name>
<t>
A set of online citation libraries are maintained on <xref target="xml2rfc"
format="default">xml2rfc.tools.ietf.org</xref>. They include citations for
RFCs, Internet-Drafts, and documents produced by the W3C and 3GPP, among
others.
</t>
<t>
To make use of the citation libraries, use an xi:include in the references
section as follows.
</t>
<sourcecode type="xml"><![CDATA[
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
]]></sourcecode>
<t>
For an Internet-Draft, the citation filename uses the draft string. For example:
</t>
<sourcecode type="xml"><![CDATA[
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-wgname-topic.xml"/>
]]></sourcecode>
<t>Preferably, use the citation libraries when possible. However,
another option is to include the complete reference element (see
<xref target="q_full_ref" format="default"/>). Here's a template of a
reference element:
</t>
<sourcecode type="xml"><![CDATA[
<reference anchor="" target="">
<front>
<title></title>
<author initials="" surname="" fullname="">
<organization />
</author>
<date month="" year="" />
</front>
<seriesInfo name="" value="" />
<refcontent></refcontent>
</reference>
]]></sourcecode>
<t>
All are cited textually in the same manner -- by using xref elements where the
target corresponds to the anchor of the reference element, e.g., <xref
target="RFC2119" />. The anchors for RFCs are "RFCNNNN" (4 digits, using
leading zeros) and the anchors for Internet-Drafts are "I-D.<name without
"draft-" or the version number>".
</t>
</section>
<section anchor="q_full_ref" numbered="true" toc="default">
<name>How do I insert the full reference?</name>
<t>
There are several ways to insert the full reference element from the
citation library:
</t>
<ol spacing="normal" type="1">
<li>
Keep a local copy of the citation libraries. They are available from
<xref target="xml2rfc" format="default">https://xml2rfc.tools.ietf.org</xref>.
</li>
<li>
Use a browser to look it up online, e.g.,
<eref target="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>, and
copy the page source.
</li>
<li>Run xml2rfc with output mode set to XML. The output will include the
complete reference elements for any entities and includes.
</li>
</ol>
</section>
<section numbered="true" toc="default">
<name>How do I change the reference tags from symbolic to numeric, i.e., from [RFC2119] to [1]?</name>
<t>
In the <tt>rfc</tt> element, set the attribute <tt>symRefs="no"</tt> for
symbolic references. This makes reference tags be numeric, e.g., [1], instead
of symbolic, e.g., [RFC2119].
</t>
</section>
<section numbered="true" toc="default">
<name>How do I make the reference tag [IKEv2] instead of [RFC4306]?</name>
<t>
Use the <tt>displayreference</tt> element and set the <tt>to</tt> attribute to
the nickname. Tip: place it before the first <tt>references</tt> element. For example:
</t>
<sourcecode type="xml"><![CDATA[
<displayreference target="RFC7296" to="IKEv2"/>
<references>
[...]
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7296.xml"/>
]]></sourcecode>
<t>
yields:
</t>
<dl>
<dt><strong>[IKEv2]</strong></dt>
<dd>Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T. Kivinen, "Internet Key Exchange Protocol Version 2 (IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296, October 2014, <<eref target="https://www.rfc-editor.org/info/rfc7296"/>>.
</dd>
</dl>
</section>
<section numbered="true" toc="default">
<name>How do I get the references listed in alphabetical order?</name>
<t>
In the rfc element, set the attribute <tt>sortRefs="yes"</tt>. Note that sortRefs only has an effect if <tt>symRefs="yes"</tt>.
</t>
</section>
<section numbered="true" toc="default" anchor="q_using_eref">
<name>How do I reference a URL?</name>
<t>
The eref element for an external reference creates a link in the HTML output. For example:
</t>
<sourcecode type="xml"><![CDATA[
<eref target="https://www.w3.org">
]]></sourcecode>
<t>
yields <eref target="https://www.w3.org"/>.</t>
<sourcecode type="xml"><![CDATA[
<eref target="https://www.w3.org">W3C Home Page</eref>
]]></sourcecode>
<t>yields
<eref target="https://www.w3.org">W3C Home Page</eref>.</t>
<t>
Another option is using xref and creating a reference that uses the target attribute for the URL. For example:
</t>
<sourcecode type="xml"><![CDATA[
<reference anchor="W3C" target="https://www.w3.org/">
<front>
<title>World Wide Web Consortium (W3C)</title>
<author/>
</front>
</reference>
]]></sourcecode>
<t>
yields
</t>
<artwork><![CDATA[
[W3C] "World Wide Web Consortium (W3C)", <https://www.w3.org/>.
]]></artwork>
</section>
<section numbered="true" toc="default">
<name>How do I get two sections of references: Normative and Informative References?</name>
<t>
Use the name element (child of the references element) as follows:
</t>
<sourcecode type="xml"><![CDATA[
<back>
<references>
<name>Normative References</name>
...
</references>
<references>
<name>Informative References</name>
...
</references>
</back>
]]></sourcecode>
</section>
<section numbered="true" toc="default">
<name>How do I create a reference to a BCP (or STD) that contains
multiple RFCs?</name>
<t>
Use <referencegroup> with an xi:include for each RFC inside of it:
</t>
<sourcecode type="xml"><![CDATA[
<referencegroup anchor="STD78" target="https://www.rfc-editor.org/info/std78">
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5343.xml"/>
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5590.xml"/>
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5591.xml"/>
<xi:include
href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6353.xml"/>
</referencegroup>
]]></sourcecode>
<t>which yields</t>
<artwork><![CDATA[
[STD78] Schoenwaelder, J., "Simple Network Management Protocol
(SNMP) Context EngineID Discovery", STD 78, RFC 5343,
September 2008.
Harrington, D. and J. Schoenwaelder, "Transport Subsystem
for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 5590, June 2009.
Harrington, D. and W. Hardaker, "Transport Security Model
for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 5591, June 2009.
Hardaker, W., "Transport Layer Security (TLS) Transport
Model for the Simple Network Management Protocol (SNMP)",
STD 78, RFC 6353, July 2011.
<https://www.rfc-editor.org/info/std78>
]]></artwork>
</section>
<section numbered="true" toc="default">
<name>How do I make a cross-reference to another section?</name>
<t>
Make sure the section you want to reference has an anchor attribute.
For example:
</t>
<sourcecode type="xml"><![CDATA[
<section anchor="s_using_lists">
]]></sourcecode>
<t>
Then, refer to it with an <xref> element:
</t>
<sourcecode type="xml"><![CDATA[
See <xref target="s_using_lists" />.
]]></sourcecode>
<t>
which yields
</t>
<blockquote>
See <xref target="s_using_lists" />.
</blockquote>
<t>
(where the number of that section is determined dynamically).
</t>
</section>
<section anchor="q_link_to_a_section" numbered="true" toc="default">
<name>What about referring to a section in another document?
or How do I link to a section in another RFC?</name>
<t>
Use <xref> and set the sectionFormat attribute to various options.
</t>
<dl newline="true">
<dt>
sectionFormat="of":
</dt>
<dd>
See <xref target="RFC7991" sectionFormat="of" section="1.3"/>.
</dd>
<dt>
sectionFormat="comma":
</dt>
<dd>
See <xref target="RFC7991" sectionFormat="comma" section="1.3"/>.
</dd>
<dt>
sectionFormat="parens":
</dt>
<dd>
See <xref target="RFC7991" sectionFormat="parens" section="1.3"/>.
</dd>
<dt>
sectionFormat="bare":
</dt>
<dd>
See <xref target="RFC7991" sectionFormat="bare" section="1.3"/>.
</dd>
<dt>
(default) When sectionFormat is not set at all, the output is the same as
"of":
</dt>
<dd>
See <xref target="RFC7991" section="1.3"/>.
</dd>
<!-- This example needs correction.
<dt>
With text content within the xref element:
</dt>
<dd>
See <xref target="RFC7991" section="1.3">the wonderful Section 1.3 of RFC 7991</xref>.
</dd>
-->
</dl>
</section>
<section numbered="true" toc="default">
<name>How do I link to multiple sections within a document (e.g., 'see Sections 3 and 4')?</name>
<t>
Use <xref> with the format attribute. For example, assuming the anchors
for the relevant sections match the targets:
</t>
<sourcecode type="xml"><![CDATA[
See Sections <xref target="s_using_refs" format="counter" /> and
<xref target="s_using_lists" format="counter" />.
]]></sourcecode>
<t>
yields the output:
</t>
<blockquote>
See Sections <xref target="s_using_refs" format="counter" /> and
<xref target="s_using_lists" format="counter" />.
</blockquote>
<t>
Note: The format attribute can have the value "title", which displays the title of the
section. For example,
</t>
<sourcecode type="xml"><![CDATA[
See Sections <xref target="s_using_refs" format="title" /> and
<xref target="s_using_lists" format="title" />.
]]></sourcecode>
<t>
yields the output:
</t>
<blockquote>
See <xref target="s_using_refs" format="title" /> and <xref target="s_using_lists" format="title" />.</blockquote>
</section>
<section numbered="true" toc="default">
<name>How do I link to multiple sections in another document
(e.g., 'see Sections 5 and 6 in RFC 3550')?</name>
<t>Use <xref> with sectionFormat="bare". For example:</t>
<sourcecode type="xml"><![CDATA[
See Sections <xref target="RFC3550" section="5" sectionFormat="bare" /> and
<xref target="RFC3550" section="6" sectionFormat="bare" /> in
<xref target="RFC3550"/>.
]]></sourcecode>
<t>
yields the output:
</t>
<blockquote><t>
See Sections <xref target="RFC3550" section="5" sectionFormat="bare" />
and <xref target="RFC3550" section="6" sectionFormat="bare" /> in
<xref target="RFC3550"/>.
</t></blockquote>
</section>
</section>
<!-- USING LISTS -->
<section numbered="true" toc="default" anchor="s_using_lists">
<name>Using Lists</name>
<section numbered="true" toc="default">
<name>How do I get different kinds of lists?</name>
<t>
For bulleted lists, use the <ul> element.
</t>
<t>
For an empty list (indentation only), use the <ul> element with
<tt>empty="true"</tt>.
</t>
<t>
For definition lists (a.k.a. hanging lists in xml2rfc v2),
use the <dl> element. See <xref
target="q_def_lists"/>.
</t>
<t>
For numbers or letters, use the type attribute of the <ol>
element; examples below.
</t>
<t>
For full details, see <xref target="RFC7991" sectionFormat="of" section="2.34.5"/> and the <eref target="https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-type-attribute-5">schema documentation</eref>.
</t>
<ul empty="true" spacing="normal">
<li>
type="1" --> 1, 2, 3, ...
</li>
<li>
type="I" --> I, II, III, ...
</li>
<li>
type="i" --> i, ii, iii, ...
</li>
<li>
type="a" --> a, b, c, ...
</li>
<li>
type="A" --> A, B, C, ...
</li>
<li>
type="REQ%d:" --> [See <xref target="q_fancy_lists" format="default"/>.]
</li>
</ul>
</section>
<section anchor="q_fancy_lists" numbered="true" toc="default">
<name>How do I get a list like (1), (2), (3) or (a), (b), (c)?</name>
<artwork name="" type="" align="left" alt=""><![CDATA[
(1)
(2) is <ol type="(%d)">
(3)
(a)
(b) is <ol type="(%c)">
(c)
REQ1:
REQ2: is <ol type="REQ%d:">
REQ3:
]]></artwork>
</section>
<section anchor="q_continued_numbering" numbered="true" toc="default">
<name>How do I get continuous numbering in a list that is split by
text (or across sections)?</name>
<t>
Set the group attribute to the same value for each <ol> element. For example:</t>
<sourcecode type="xml"><![CDATA[ <ol type="REQ%d:" group="reqs">
<li>do a</li>
<li>do b</li>
</ol>
<t>Here is text in between.</t>
<ol type="REQ%d:" group="reqs">
<li>do c</li>
<li>do d</li>
</ol>
<t>Here is more text in between.</t>
<ol type="REQ%d:" group="reqs">
<li>do e</li>
<li>do f</li>
</ol>
]]></sourcecode>
<t>yields:</t>
<ol type="REQ%d:" group="reqs">
<li>do a</li>
<li>do b</li>
</ol>
<t>Here is text in between.</t>
<ol type="REQ%d:" group="reqs">
<li>do c</li>
<li>do d</li>
</ol>
<t>Here is more text in between.</t>
<ol type="REQ%d:" group="reqs">
<li>do e</li>
<li>do f</li>
</ol>
</section>
<section anchor="q_def_lists" numbered="true" toc="default">
<name>How do I get indentation? or How do I use definition lists?</name>
<t>
Use a <dl> element (definition list), where each <dt> (term) in
has a corresponding <dd> (description).
</t>
<t>
For example:</t>
<sourcecode type="xml"><![CDATA[
<dl>
<dt>Unassigned:</dt>
<dd>Unused and available for assignment via
documented procedures.</dd>
<dt>Reserved:</dt>
<dd>Not to be assigned. Reserved values are
held for special uses, such as to extend the namespace
when it become exhausted. Reserved values are not
available for general assignment.</dd>
</dl>
]]></sourcecode>
<t>yields:</t>
<dl>
<dt>Unassigned:</dt>
<dd>Unused and available for assignment via
documented procedures.</dd>
<dt>Reserved:</dt>
<dd>Not to be assigned. Reserved values are
held for special uses, such as to extend the namespace
when it become exhausted. Reserved values are not
available for general assignment.</dd>
</dl>
<t>Note: The appearance is slightly different in the text output.</t>
<t>
Use <tt>newline="true"</tt> to get a line
break after the term. For example:</t>
<sourcecode type="xml"><![CDATA[
<dl newline="true">
<dt>Unassigned:</dt>
<dd>Unused and available for assignment via
documented procedures.</dd>
<dt>Reserved:</dt>
<dd>Not to be assigned. Reserved values are
held for special uses, such as to extend the namespace
when it become exhausted. Reserved values are not
available for general assignment.</dd>
</dl>
]]></sourcecode>
<t>yields:</t>
<dl newline="true">
<dt>Unassigned:</dt>
<dd>Unused and available for assignment via
documented procedures.</dd>
<dt>Reserved:</dt>
<dd>Not to be assigned. Reserved values are
held for special uses, such as to extend the namespace
when it become exhausted. Reserved values are not
available for general assignment.</dd>
</dl>
</section>
<section anchor="q_nested_lists" numbered="true" toc="default">
<name>How do I create nested lists?</name>
<t>The key is that any text before or after the inner list must be in a <t> element.</t>
<t>Example: <ol> nested within <dl></t>
<sourcecode type="xml"><![CDATA[
<dl>
[...]
<dt>Foo validator:</dt>
<dd>
<t>It performs the following actions:</t>
<ol type="1" spacing="compact">
<li>runs</li>
<li>jumps</li>
<li>walks</li>
</ol>
</dd>
[...]
</dl>
]]></sourcecode>
<t>yields:</t>
<dl>
<dt>Foo validator:</dt>
<dd>
<t>It performs the following actions:</t>
<ol type="1" spacing="compact">
<li>runs</li>
<li>jumps</li>
<li>walks</li>
</ol>
</dd>
</dl>
<t>Example: <ul> nested within <ol></t>
<sourcecode><![CDATA[
<ol type="Step %d:">
[...]
<li><t>Send it to</t>
<ul spacing="compact">
<li>Alice</li>
<li>Bob</li>
<li>Carol</li>
</ul>
</li>
[...]
</ol>
]]></sourcecode>
<t>yields:</t>
<ol type="Step %d:">
<li>
<t>Send it to:</t>
<ul spacing="compact">
<li>Alice</li>
<li>Bob</li>
<li>Carol</li>
</ul>
</li>
</ol>
</section>
</section>
<!-- FINER POINTS -->
<section numbered="true" toc="default">
<name>The Finer Points</name>
<section anchor="q_CDATA" numbered="true" toc="default">
<name>What is CDATA for?</name>
<t>
A CDATA block is left alone by xml2rfc. It does not try to parse XML
inside of a CDATA block. (For example, if a figure contains "<", you don't
have to use &lt;) So it is especially good for when there are XML
examples in the document.
</t>
</section>
<section numbered="true" toc="default">
<name>What are the entities used for special characters?</name>
<t>To prevent these characters from being parsed as XML, use
</t>
<artwork name="" type="" align="left" alt=""><![CDATA[
& for &
< for <
> for >
]]></artwork>
<t>In addition, the following entities are defined:</t>
<artwork name="" type="" align="left" alt=""><![CDATA[
for non-breaking space
&nbhy; for non-breaking hyphen
&wj; for word joiner
]]></artwork>
</section>
<section numbered="true" toc="default">
<name>How do I indicate the editor of the document?</name>
<t>Use the role attribute of the author element. For example:</t>
<sourcecode type="xml"><![CDATA[
<author initials="J" surname="Doe" fullname="John Doe" role="editor">
]]></sourcecode>
</section>
<section numbered="true" toc="default" anchor="using_contact">
<name>How do I list the contributors or include acknowledgments?</name>
<t>In a "Contributors" section, you can use the <contact>
element, which has the same structure as the <author> element.
Including address information is optional.
</t>
<t>In an "Acknowledgments" section, you can use the <contact> element
within <t> to list inviduals' names (typically without address information).</t>
</section>
<section numbered="true" toc="default">
<name>How do I insert questions for my coauthors?</name>
<t>
You can use comments <!-- --> or <cref> elements.
Comments are only visible in the XML source file.
</t>
<t>
Example of using comments:
</t>
<sourcecode type="xml"><![CDATA[
<!-- [JD] This point needs revision.-->
]]></sourcecode>
<t>
<cref> will show up in
the output when the attribute display="true" (which is the default).
</t>
<t>
Example of using <cref>:
</t>
<sourcecode type="xml"><![CDATA[
<cref anchor="Q1" source="JD">This point needs revision.</cref>
]]></sourcecode>
<t>
yields
</t>
<t><cref anchor="Q1" source="JD">This point needs revision.</cref></t>
</section>
</section>
<!-- MISCELLANEOUS -->
<section numbered="true" toc="default">
<name>Miscellaneous</name>
<section anchor="q_valid" numbered="true" toc="default">
<name>How do I know if my XML is valid?</name>
<t>xml2rfc validates it.
Also, you can run rfclint: <eref target="https://pypi.org/project/rfclint/"/>.
</t>
</section>
<section anchor="q_HTMLoutput" numbered="true" toc="default">
<name>Can I get a different kind of HTML output?</name>
<t>
Yes, rfc2629.xslt by Julian Reschke provides a different kind of
HTML output than the HTML output mode of
xml2rfc. See <eref
target="https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html">"Transforming
RFC7749-formatted XML through XSLT"</eref> for more information.
</t>
</section>
<section numbered="true" toc="default" anchor="q_id2xml">
<name>Is there a tool that will turn my text file into an XML file (i.e., id2xml)?</name>
<t>
Yes, id2xml is available here: <eref
target="https://pypi.org/project/id2xml/"/>. It is available as a web
service on <eref target="https://xml2rfc.tools.ietf.org/"/>.
</t>
</section>
</section>
<section numbered="true" toc="default" anchor="s_new_with_v3">
<name>New with v3</name>
<!-- TEMPLATE FOR A NEW QUESTION
<section anchor="q_" numbered="true" toc="default">
<name>How do I ?</name>
<t>
</t>
</section>
-->
<section anchor="q_convert_v2v3" numbered="true" toc="default">
<name>How do I convert my XML file from v2 to v3 so I can make
use of the new features?</name>
<t>On the command line: <tt>xml2rfc --v2v3 inputfile.xml</tt>. You can
use the <tt>--add-xinclude</tt> option to replace RFC and I-D reference elements
with the appropriate xi:include element.</t>
<t>Or, using the web service
(<eref target="https://xml2rfc.tools.ietf.org/experimental.html"/>),
select "Output format: convert v2 to v3 XML".
</t>
<t>After converting it to v3, please see <xref target="q_post_conversion_review"/>.</t>
</section>
<section anchor="q_post_conversion_review" numbered="true" toc="default">
<name>After converting an XML file from v2 to v3, what further
updates might be needed for the v3 XML file?</name>
<t>You may want to do the following (for the sake of generating good
output and having a semantically accurate XML file):</t>
<ul>
<li><t>Review each list.</t>
<ul>
<li>Is it really a list? Or should indentation be added in another manner,
e.g., <![CDATA[<blockquote>]]>.</li>
<li>If so, should it be <![CDATA[<dl>, <ul>, or <ol>]]>? See <xref target="s_using_lists"/>.</li>
</ul>
</li>
<li><t>Review each <![CDATA[<artwork>]]>.</t>
<ul>
<li>Should it be <![CDATA[<sourcecode>]]>? If so, what type? See <xref target="q_sourcecode"/>.</li>
<li>Should it be a table? See <xref target="q_table"/>.</li>
</ul>
</li>
<li>Search for URLs; should these be <eref>? See <xref target="q_using_eref"/>.</li>
<li>Look for equations or other text where new features may improve
clarity. See <xref target="q_new_features"/>.</li>
<li>Search for hardcoded citation tags (e.g., [RFC5234]) and update to
<xref>s. See <xref target="q_add_reference"/>.</li>