-
Notifications
You must be signed in to change notification settings - Fork 34
/
Copy pathindex.html
1617 lines (1221 loc) · 57.7 KB
/
index.html
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
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8">
<title>W3C Manual of Style</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c.js' async class='remove'>
</script>
<script class='remove'>
var respecConfig = {
specStatus: "base",
editors: [
{
name: "Philippe Le Hegaret",
url: "https://www.w3.org/People/LeHegaret",
},
{
name: "Coralie Mercier",
url: "https://www.w3.org/People/Coralie",
}
],
latestVersion: "https://www.w3.org/guide/manual-of-style/",
edDraftURI: null,
license: 'w3c-software-doc',
github: "w3c/guide",
otherLinks: [{
key: 'Mailing list',
data: [{
value: '[email protected]',
href: 'https://lists.w3.org/Archives/Public/spec-prod/'
}]
}],
xref: [ "i18n-glossary" ]
};
</script>
</head>
<body>
<section id='abstract'>
<p>This manual is a guide containing best current practice, written for editors and authors of W3C technical reports. No requirements
for W3C publications are in this document. All requirements for W3C
publications are in <a href="https://www.w3.org/pubrules/doc">W3C
Publication Rules</a>.</p>
</section>
<section id="sotd">
</section>
<section id="Introduction">
<h2>Introduction</h2>
<p>Written for editors and authors of W3C technical reports, this
document assumes that the reader has mastered publishing on the W3C Web
site, and is familiar with the <cite>Style Guide for Online
Hypertext</cite> [<cite><a href=
"#ref-STYLE-GUIDE">STYLE-GUIDE</a></cite>]. It is a companion to the
REQUIRED <cite>Technical Report Publication
Policy</cite> [<cite><a href="#ref-PUBRULES">PUBRULES</a></cite>],
called "pubrules" for short. Following the advice in this manual has
benefits:</p>
<ul>
<li>Non-native English readers, native English readers, and translators
will find your text easy to read and implement.</li>
<li>All audiences can concentrate on ideas rather than the mechanics of
reading.</li>
<li>Polished at early public maturity levels, clean copy eliminates
multiple "typo" reports.</li>
</ul>
<p>Chapter 2 covers <a href="#Validation">validation</a>. Chapters 3
and 4 cover <a href="#Accessibility">accessibility</a> and <a href=
"#I18n">internationalization</a>. Chapter 5 describes <a href=
"#Parts">parts</a> of a W3C technical report. Chapters 6, 7, and 8
cover <a href="#Errata">errata</a>, <a href=
"#References">references</a> and <a href="#Revisions">revisions</a>.
Chapter 9 introduces <a href="#Production">editing tools</a>.
Chapter 10 addresses Normative and Informative requirements, in particular <a href=
"#RFC"><abbr title="Request for Comments">RFC</abbr> 2119 key
words</a>. Chapter 11 presents <a href="#Editorial">editorial
guidelines</a>, and, finally, chapter 12 documents commonly <a href=
"#Terms">misspelled terms</a>.</p>
<p>Bear in mind that our reports are used as world-class primary
reference material. Readability across a wide variety of browsers and
platforms is far more important than using jazzy features. At some
point, what we write becomes history and is preserved on the Web
through the W3C <cite><a href=
"https://www.w3.org/policies/uri-persistence/">Persistence
Policy</a></cite> [<cite><a href=
"#ref-PERSISTENCE">PERSISTENCE</a></cite>].</p>
</section>
<section id="Validation">
<h2>Validation</h2>
<ul>
<li>Make sure there are no broken links in your documents at the time
of publication. Some services on the Web may help you with this,
including the <cite>W3C Link Checker</cite> [<cite><a href=
"#ref-CHECKLINK">CHECKLINK</a></cite>]. Append ",checklink" to a W3C
<abbr title="Uniform Resource Identifier">URI</abbr> to invoke the link
checker.</li>
<li>Make sure your technical report validates in the <cite>W3C Markup
Validation Service</cite> [<cite><a href=
"#ref-VALIDATE">VALIDATE</a></cite>]. Append ",validate" to a W3C
<abbr title="Uniform Resource Identifier">URI</abbr> to invoke the
validator.</li>
<li>Make sure your technical report validates in the <cite>W3C
<abbr title="Cascading Style Sheets">CSS</abbr> Validation
Service</cite> [<cite><a href=
"#ref-CSSVALIDATE">CSSVALIDATE</a></cite>]. Append ",cssvalidate" to a
W3C <abbr title="Uniform Resource Identifier">URI</abbr> to invoke the
<abbr title="Cascading Style Sheets">CSS</abbr> validator.</li>
<li>Make sure any examples in your document validate as well.</li>
</ul>
<p><strong>Note.</strong> It is the editor's responsibility to ensure
that documents are valid before requesting publication.</p>
</section>
<section id="Accessibility">
<h2>Accessibility</h2>
<ul>
<li>Follow the <cite><a href="https://www.w3.org/WAI/standards-guidelines/wcag/">Web Content Accessibility Guidelines</a></cite>
(<abbr>WCAG</abbr>). Can
simpler words express your ideas? Is your text marked up with
structural elements? Are alternatives provided for auditory and visual
content? See also <a href="https://www.w3.org/WAI/test-evaluate/">evaluation tools</a>.</li>
</ul>
</section>
<section id="I18n">
<h2>Internationalization</h2>
<p>Follow the guidelines in <cite>Internationalization Best Practices for Spec Developers</cite> [[INTERNATIONAL-SPECS]] when producing your specification. You might also find it helpful to complete a <a href="https://www.w3.org/International/i18n-drafts/techniques/shortchecklist">self-review</a> early in the development process. If your specification touches on more complex issues, you can also reach out to the Internationalization Working Group for guidance.</p>
<p>Internationalization terminology, particularly terms related to Unicode, can be rather precise. To help avoid problems with the need to define these, import the [[Infra]] standard and [[I18N-GLOSSARY]]. Use the terms found in these documents instead of creating your own and link your use of these terms to the definitions found in these documents. Instructions on how to do this can be found in an appendix of the [[I18N-GLOSSARY]].</p>
<section id="general-i18n">
<h3>Write for a global audience</h3>
<p>Keep in mind that W3C documents serve a global audience.</p>
<ul>
<li>Avoid idioms that are U.S.- or English-specific in favor of more neutral language.</li>
<li>Choose examples that reflect a global audience. For example:
<ul>
<li>When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find suggestions <a href="https://www.w3.org/TR/international-specs/#personal_name_examples">here</a> in [[INTERNATIONAL-SPECS]].</li>
<li>Choose more generic terms for field names, such as "postal code" instead of (U.S.-specific) "ZIP code" or "given name" instead of "first name".</li>
</ul>
<li>In general, use [=locale-neutral=] representations of data values, such as dates, numbers, currency values, and so forth.</li>
<!-- EDNOTE: A previous edition had a section with the id of `Dates`. The id is preserved here to avoid problems
with any links to the older edition.
-->
<li id="Dates">For time and date values, choose an unambiguous representation:
<ul>
<li>For date values that appear in prose, spell out the month (for example, <kbd>6 May 2003</kbd> or <kbd>September 23, 2016</kbd>). All numeric dates such as <kbd translate="no">5/6/03</kbd> or <kbd translate="no">6/5/03</kbd> are ambiguous. Some cultures will read the first example as "June 5" while other cultures will read the second example as that date.</li>
<li>For date values that appear in data, use a format derived from ISO8601, such as those found in [[RFC3339]] or those found in <cite><a href="https://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#date" title="Section 3.2.9 of the XML Schema Datatypes">XML Schema Part 2: Datatypes</a></cite> ([[XMLSchema-2]].</li>
</ul></li>
</ul>
</section>
<section id="Unicode">
<h3>Unicode</h3>
<p>Use <code translate="no">U+XXXX</code> syntax to represent [=Unicode code points=] in the specification. These are space separated when appearing in a sequence. No additional decoration is needed. Note that a [=code point=] may contain four, five, or six hexadecimal digits. When fewer than four digits are needed, the code point number is zero filled.</p>
<aside class="example" title="Code point examples">
<table>
<thead>
<tr>
<th>Character</th>
<th>Name</th>
<th>U+XXXX syntax</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:center"> </td>
<td class="uname">SPACE</td>
<td>U+0020</td>
</tr>
<tr>
<td style="text-align:center">é</td>
<td class="uname">LATIN SMALL LETTER E WITH ACUTE</td>
<td>U+00E9</td>
</tr>
<tr>
<td style="text-align:center">ઊ</td>
<td class="uname">GUJURATI LETTER UU</td>
<td>U+0A8A</td>
</tr>
<tr>
<td style="text-align:center">�</td>
<td class="uname">REPLACEMENT CHARACTER</td>
<td>U+FFFD</td>
</tr>
<tr>
<td style="text-align:center">😮</td>
<td class="uname">FACE WITH OPEN MOUTH</td>
<td>U+1F62E</td>
</tr>
</tbody>
</table>
</aside>
<p>Use the Unicode character name to describe specific code points. Use of the <a href="#char_ref_template">character naming template</a> is recommended.</p>
<p>Unicode assigns unique, immutable names to each assigned [=Unicode code point=]. Using these names in your specification when referring to specific characters (along with the code point in <code class="uname" translate="no">U+XXXX</code> notation) will help make your specification unambiguous.</p>
<p>There are cases where doing this is overly pedantic and detracts from usability, but be cautious about being so informal as to impair meaning.</p>
<section id="char_ref_template">
<h5>Character naming template</h5>
<div class="xref"><span class="seealso">See also</span>
<p>[<a href="https://www.w3.org/International/i18n-activity/guidelines/editing#codepoints">I18N Editing Guidelines</a>].</p>
</div>
<p>Internationalization specifications use (and we recommend the use of) this template for character references:</p>
<pre>
<span class="codepoint" translate="no"><bdi lang="??">&#xXXXX;</bdi>
[<span class="uname">U+XXXX Unicode_character_name</span>]</span>
</pre>
<aside class="example" title="Example of a character reference">
<p>Filling in the above template like this:</p>
<pre>
<span class="codepoint" translate="no"><bdi lang="fr">é</bdi>
[<span class="uname">U+00E9 LATIN SMALL LETTER E WITH ACUTE</span>]</span>
</pre>
<p>Produces output in the page like this: <span class="codepoint" translate="no"><bdi lang="fr">é</bdi> [<span class="uname">U+00E9 LATIN SMALL LETTER E WITH ACUTE</span>]</span>.</p>
</aside>
<p>Some notes about the markup used. The <code translate=no>bdi</code> element is used to ensure that example characters that are [=right-to-left=] do not interfere with the layout of the page. The <code translate=no>lang</code> attribute should be filled in with the most appropriate [[BCP47]] [=language tag=] to get the correct font selection (and other processing) for a given context. Examples in East Asian languages (such as Chinese, Japanese, or Korean) or in the Arabic script can sometimes require greater care in choosing a language tag.</p>
</section>
</section>
<section id="Translations">
<h3>Translations</h3>
<p>W3C has no official translations of its technical reports. W3C does
encourage people to translate the technical reports and helps to track
translators and translations.</p>
<ul>
<li>A central translation page includes links to pages that document
translations of particular specifications [<cite><a href=
"#ref-TRANSLATE">TRANSLATE</a></cite>].</li>
<li>Read the <cite>W3C Intellectual Property <abbr title=
"Frequently Asked Questions list">FAQ</abbr></cite>, <cite><a href=
"https://www.w3.org/copyright/intellectual-rights/#translate">Can I
translate one of your specifications into another language?</a></cite>
and <cite><a href=
"https://www.w3.org/copyright/intellectual-rights/#official">Can I
create the "official" translation?</a></cite> ([<cite><a href=
"#ref-IPRFAQ">IPRFAQ</a></cite>] sections 5.6 and 5.7).</li>
</ul>
<p>Make your specification more readable by adding markup to distinguish common words from keywords in your language. Mark up every occurrence. Use <code>translate="no"</code> as an attribute to communicate to translators that the keyword is part of the [=vocabulary=] of a formal language rather than part of the [=natural language=] text of the document. For example:</p>
<pre class="html">
<p>The title attribute of these elements may be used
to provide the full or expanded form of the expression.
</pre>
<p>becomes:</p>
<pre>
<p>The <code translate="no">title</code> attribute of these elements may be used
to provide the full or expanded form of the expression.
</pre>
<p>A French translator would then know not to translate <em>title</em>
to <em lang="fr">titre</em>.</p>
<p>Do not invent elements to replace natural language. For example, do
not use <code><must/></code> and a stylesheet to render MUST.
Other languages may need grammatical agreement with the sentence's
subject, <span class="not-en">e.g.</span>, in French, MUST will become
<em xml:lang="fr" lang="fr">DOIT</em> if the subject is singular, or
<em xml:lang="fr" lang="fr">DOIVENT</em> if it is plural. Use standard
markup instead.</p>
</section>
</section>
<section id="Parts">
<h2>The Parts of a Technical Report</h2>
<p id="Template">As of November 2005, <a href=
"https://www.w3.org/pubrules/doc">pubrules</a> [<cite><a href=
"#ref-PUBRULES">PUBRULES</a></cite>] includes a technical report
template.</p>
<section id="Title">
<h3>Document Title</h3>
<p>The title of your document in the document head and on the technical
reports index [<cite><a href="#ref-TR">TR</a></cite>] will read as
follows. Optional elements are in square brackets.</p>
<p>Title [(ACRONYM)] ["Specification"] ["Part" Part_Number] [:
Subtitle] ["Module"] [(nth "Edition")] ["Version" Version_Number]</p>
<p>See pubrules [<cite><a href="#ref-PUBRULES">PUBRULES</a></cite>] for
information about the use of "version" and "edition". "Level" and
"revised" are deprecated. Try not to invent a new titling
convention.</p>
<p>Capitalize title words following U.S. usage.</p>
</section>
<section id="Editors">
<h3>Editors and Authors</h3>
<section id="affs">
<h4>Managing Changing Affiliations</h4>
<p>Editor/Author affiliations change over time. Here are examples that
illustrate the suggested approach for managing them.</p>
<dl>
<dt>Still editor</dt>
<dd>Richard Ishida, W3C (and before at Xerox)</dd>
<dd>François Yergeau, Invited Expert (and before at Alis
Technologies)</dd>
<dd>Jane Doe, MyCompany (and before at ThierCompany, and at HisCompany,
and at HerCompany)</dd>
<dt>No longer editor</dt>
<dd>Martin J. Dürst (until Dec 2004 while at W3C)</dd>
<dd>Misha Wolf (until Dec 2002 while at Reuters Ltd.)</dd>
<dd>Tex Texin (until Dec 2004 while an Invited Expert, and before at
Progress Software)</dd>
<dd>FitzChivalry Farseer (until Oct 2005 while at AnyCompany, and
before at ThisCompany, and at ThatCompany)</dd>
</dl>
</section>
</section>
<section id="tAbstract">
<h3>Abstract</h3>
<p><dfn id="must-abstract" class="lint-ignore">Give each document an
Abstract</dfn> (a few paragraphs at most) that summarizes what the
document is about. The Communications Team may use the Abstract as a
whole or in part to publicize your work. Write it for a non-technical
audience.</p>
</section>
<section id="Status">
<h3>Status Section</h3>
<p>The "Status of This Document" section describes the document status
and publication context on the publication date. Pubrules
[<cite><a href="#ref-PUBRULES">PUBRULES</a></cite>] states the
requirements for the status section of each type of technical report
(e.g., use of customized and boilerplate text).</p>
<p>Since the status section does not change over time, express it in
terms that will be valid over time (<span class="not-en">e.g.</span>,
avoid the word "new"). Indicate the anticipated stability of the
document while recognizing that the future is unknown. Readers are
responsible for discovering the latest status information (<span class=
"not-en">e.g.</span>, by following the latest version link, or visiting
the W3C technical reports index [<cite><a href=
"#ref-TR">TR</a></cite>].</p>
<p>The custom paragraph is very important as it actually contains
information! In it, you should explain where a part of the energy of
the group has been invested. The custom paragraph should help a reader
decide "I really should read this draft." This implies that you
shouldn't paste it in from somewhere else. It should be very specific
to this document.</p>
<p>TimBL expressed the goal of the custom paragraph this way, "Don't be
afraid of being honest about the relevant techno-political situation."
In the custom paragraph, make th case for why someone should read this
draft.</p>
<p>In the custom paragraph, include what you would reply to a Member or
colleague who asked you such things as:</p>
<ul>
<li>Are we requesting that people implement this specification? If so,
where should experience reports be sent?</li>
<li>Are we requesting people do <em>not</em> implement the
specification until a later date? What sort of damage do we expect to
inflict on those who do by future changes to the document?</li>
<li>Does it reflect the consensus of a W3C Working Group? (Pay
attention to the authors and acknowledgments.)</li>
<li>Are there any changes expected?</li>
<li>Do we maintain a page of background information?</li>
<li>For pre-release drafts, state in the status section any limits on
redistribution, such as "Member confidential."</li>
</ul>
</section>
</section>
<section id="Errata">
<h2>Errata</h2>
<p>All Recommendations have errors in them. They link to an errata page
that evolves over time. Since the errata page changes over time but a
specific version of a Recommendation does not, place the errata page
<strong>outside</strong> of the <kbd>/TR</kbd> hierarchy. There is an
expectation that documents in the "<abbr title=
"technical report">TR</abbr> zone" will not evolve over time
[<cite><a href="#ref-PERSISTENCE">PERSISTENCE</a></cite>]. For example,
locate errata pages in the portion of the Web space dedicated to the
relevant Working Group or Activity.</p>
<p>Clearly indicate on the errata page:</p>
<ul>
<li>The last modified date for the errata page.</li>
<li>The <abbr title="Uniform Resource Identifier">URI</abbr> of the
source document (<span class="not-en">i.e.</span>, the one with the
errata).</li>
<li>Where to find the latest version of the source document.</li>
</ul>
<p>For example (shown here without links):</p>
<dl style="margin-left: 10%">
<dt>This document:</dt>
<dd>http://www.w3.org/Style/css2-updates/REC-CSS2-19980512-errata</dd>
<dt>Last revised:</dt>
<dd>$Date: 2016/07/10 16:55:10 $</dd>
<dt>This document records known errors in the document:</dt>
<dd>http://www.w3.org/TR/1998/REC-CSS2-19980512</dd>
<dt>The latest version of the CSS 2 Recommendation:</dt>
<dd>http://www.w3.org/TR/REC-CSS2</dd>
</dl>
<p>On the errata page, list the newest entries nearer to the top.</p>
<section id='entries'>
<h3>Entries on an errata
page</h3>
<p>For each entry on the errata page, provide:</p>
<ol>
<li>A unique identifier</li>
<li>The date it was added to the errata page</li>
<li>A classification of the error (e.g., editorial, clarification, bug,
known problem with the document itself)</li>
<li>A short description of the problem and what part of the
Recommendation is affected.</li>
<li>Any proposed corrections and whether those corrections would affect
conformance of documents or software</li>
<li>Any normative corrections; see the section on <a href=
"https://www.w3.org/policies/process/20231103/#errata">Errata
Management</a> in the <cite>W3C Process Document</cite>
([<cite><a href="#ref-PROCESS">PROCESS</a></cite>] section 6.2.4) for
more information about normative corrections</li>
</ol>
<p>Do no remove entries from the errata page; if a correction turns out
to be incorrect, just add another entry (with a cross reference).</p>
</section>
</section>
<section id="References">
<h2>References</a></h2>
<section id="extractor">
<h3>Bibliography Extractor</h3>
<p>The <a href="https://www.specref.org/">SpecRef</a> tool, an Open-Source, Community-Maintained Database of
Web Standards & Related References, contains an exhaustive of references.</p>
<p>The <cite><a href=
"http://www.w3.org/2002/01/tr-automation/tr-biblio-ui">W3C Bibliography
Extractor</a></cite> [<cite><a href=
"#ref-BIB-EXTRACT">BIB-EXTRACT</a></cite>] will automatically generate
a list of references in W3C style.</p>
</section>
<section id="citation">
<h3>Citation</h3>
<p>Reference links (<span class="not-en">e.g.</span>, "[<abbr title=
"Extensible Markup Language">XML</abbr>]") link at least the first mention of a source to the References
section and take the form:</p>
<pre>
<cite><a href="http://www.example.org/example">Full Name</a></cite> [<cite><a href="#ref-REFNAME">REFNAME</a></cite>]
</pre>
<p>Parentheses around square brackets can be omitted unless the
parentheses would contain a section number.</p>
<p>References links occur at minimum at the first mention of the
source. Spell out what the reference link refers to at least in the
first occurrence, <span class="not-en">e.g.</span>:</p>
<pre>
This is discussed in <cite>Namespaces in XML</cite> [XMLName].
</pre>
<p>or</p>
<pre>
This is discussed in the XML namespaces specification [XMLName].
</pre>
<p>and not</p>
<pre>
This is discussed in [XMLName].
</pre>
</section>
<section id="linking-within">
<h3>Citing a Reference From Within a Document</h3>
<p>When linking from the middle of the document to an external
resource:</p>
<ol>
<li>Ensure that the link text, title, and context indicate you are
leaving the document, and</li>
<li>After the link, link to the reference in the references section,
and indicate section, page, or whatever is useful for those when the
link is unavailable (e.g., when printed).</li>
</ol>
<p>Thus, for example:</p>
<pre>
...as is done for the <a href=
"https://www.w3.org/TR/css-ui-3/#outline"
title=
"Section 4.1 of ">'outline' property of CSS Basic User Interface Module Level 3</a> ([<cite><a href=
"#ref-CSS3UI">CSS3UI</a></cite>], section 4.1).
</pre>
</section>
<section id="ref-section">
<h3>References Section</h3>
<ul>
<li>All entries in a references section should be referred to in the
prose. If an entry is not referred to from the body of the document,
make it clear why it is in the References section.</li>
<li>If a reference is a W3C Recommendation track technical report that
has not reached Recommendation, state in the References section that it
is "work in progress."</li>
<li>It is helpful to include references to both persistent resources
and their latest version. Use titles for links. If there is an
institutionalized identifier (<abbr title=
"Uniform Resource Identifier">URI</abbr>) for a document, cite the most
specific identifier. For example, usually you would link the title to
<kbd>http://www.w3.org/TR/1999/REC-html401-19991224</kbd> rather than
to <kbd>http://www.w3.org/TR/html4/</kbd>. For more information on
using versioned and unversioned identifiers, refer to the
<cite><a href="https://www.w3.org/TR/charmod/#sec-RefUnicode">Character
Model for the World Wide Web 1.0: Fundamentals</a></cite>
([[CHARMOD]] section 8).</li>
<li>An entry in a references section takes this form:
<ul>
<li>Title, inside <code>a</code> (if available), inside
<code>cite</code></li>
<li>Comma-delimited list of authors' names</li>
<li>If there are no authors, use editors instead if available.
Following the last family name, say "eds." or "Editors."</li>
<li>Publisher, followed by the date of publication in the form DD Month
YYYY</li>
<li>A sentence containing a text-only <abbr title=
"Uniform Resource Identifier">URI</abbr>.</li>
<li>When available, a sentence ending in the latest version
<abbr title="Uniform Resource Identifier">URI</abbr></li>
</ul>
<p>Example:</p>
<dl>
<dt>[XML1]</dt>
<dd><cite><a href="https://www.w3.org/TR/2006/REC-xml-20060816/">Extensible Markup Language (XML) 1.0 (Fourth Edition)</a></cite>, T. Bray, J. Paoli, E. Maler, C. M. Sperberg-McQueen, F. Yergeau, Editors. World Wide Web Consortium, 16 August 2006, edited in place 29 September 2006. This edition of the XML 1.0 Recommendation is http://www.w3.org/TR/2006/REC-xml-20060816/. The <a href="https://www.w3.org/TR/xml/">latest edition of XML 1.0</a> is available at http://www.w3.org/TR/xml/.</dd>
</dl>
<p>Markup for the example above:</p>
<pre>
<dl>
<dt><a id="ref-XML1" name="ref-XML1">[XML1]</a></dt>
<dd><cite><a href="https://www.w3.org/TR/2006/REC-xml-20060816/">Extensible
Markup Language (XML) 1.0 (Fourth Edition)</a></cite>,
T. Bray, J. Paoli, E. Maler, C. M. Sperberg-McQueen, F. Yergeau,
Editors. World Wide Web Consortium, 16 August 2006, edited in place
29 September 2006. This edition of the XML 1.0 Recommendation is
http://www.w3.org/TR/2006/REC-xml-20060816/. The <a
href="https://www.w3.org/TR/xml/">latest edition of XML 1.0</a>
is available at http://www.w3.org/TR/xml/.</dd>
</pre>
</li>
<li>Reference titles are recommended, not the "<abbr title=
"Uniform Resource Identifier">URI</abbr>-in-your-face" idiom, as link
text; see [<cite><a href="#ref-REF-TITLES">REF-TITLES</a></cite>]. For
example, <strong>Do use</strong>: <kbd><cite><a
href="https://www.w3.org/TR/2016/REC-html51-20161101/">HTML 5.1
Specification</a></cite></kbd>. Do not use:
<kbd><cite><a
href="https://www.w3.org/TR/2016/REC-html51-20161101/">http://www.w3.org/TR/1999/REC-html401-19991224</a></cite></kbd>.</li>
</ul>
</section>
<section id="normative">
<h3>Normative and Informative
References</h3>
<p>See <a href="https://www.w3.org/guide/process/tilt/normative-references.html">Normative References</a> and considerations by the Team.</p>
</section>
</section>
<section id="Revisions">
<h2>Revisions</h2>
<p>See the <cite><a href=
"https://www.w3.org/policies/process/20231103/#rec-modify">W3C Process
Document</a></cite> ([<cite><a href="#ref-PROCESS">PROCESS</a></cite>]
section 6.3.11) for instructions on modifying a W3C Recommendation.</p>
<p><strong>Note.</strong> When a document is revised, the original
publication date remains the same (and on the technical reports index
[<cite><a href="#ref-TR">TR</a></cite>] as well); see pubrules
[<cite><a href="#ref-PUBRULES">PUBRULES</a></cite>] for more
detail.</p>
<p>Be careful not to break links in revisions. If your document uses
latest version <abbr title="Uniform Resource Identifier">URI</abbr>s
with a fragment identifier, unless those anchors are maintained across
versions, links will break.</p>
</section>
<section id="Production">
<h2>Editing tools</h2>
<p>Though the <abbr title="HyperText Markup Language">HTML</abbr> or
<abbr title="Extensible HyperText Markup Language">XHTML</abbr> version
of your specification is always the definitive one, many editors find the use of a tool easier
to work with.</p>
<p>The most popular editing tools are <a href='https://speced.github.io/bikeshed/'>Bikeshed</a> and <a href='https://github.com/speced/respec/wiki'>respec</a>.</p>
<p>For help with this process, you can ask
the experts on the public mailing list [email protected] [<cite><a href=
"#ref-SPEC-PROD">SPEC-PROD</a></cite>].</p>
</section>
<section id="Normative">
<h2>Normative material</h2>
<section id="N-I-sections">
<h3>Normative & Informative sections</h3>
<p>It is important that informative (non-normative) material
is clearly distinguished from normative material. To this end:</p>
<ul>
<li>If the entire document is informative, say so at the top and
do not reference RFC 2119 or use <a href="#RFC">RFC 2119 keywords</a>
</li>
<li>If some sections are informative, say so at the
start of each section, and do not
use <a href="#RFC">RFC 2119 keywords</a> in those sections
</li>
<li>Figures, examples and notes are assumed to always be informative.
To avoid repetition, each figure, example or note does not say this.
<span id="consistent-expectations">Thus,
to avoid breaking user expectations,
document editors <em class="rfc2119">MUST NOT</em> make any
figure, example or note normative.</span>
</li>
</ul>
</section>
<section id="RFC">
<h3><abbr title=
"Request for Comments">RFC</abbr> 2119 Key Words</h3>
<p>Adhere to and credit <cite><abbr title=
"Request for Comments">RFC</abbr> 2119 Key words for use in
<abbr title="Request for Comments">RFC</abbr>s to Indicate Requirement
Levels</cite> [<cite><a href="#ref-KEYWORDS">KEYWORDS</a></cite>]
(<span class="not-en">e.g.</span>, "<em class="rfc2119">MUST</em>", "<em class="rfc2119">MUST NOT</em>", "<em class="rfc2119">REQUIRED</em>").</p>
<p>When these key words are used in the <abbr title=
"Request for Comments">RFC</abbr> sense, make them UPPERCASE, enclose
them in the <code>em</code> element, and style them with <abbr title=
"Cascading Style Sheets">CSS</abbr> class of rfc2119 to make the <em class=
"RFC2119">UPPERCASE</em> readable.</p>
<pre>
<em title="MUST in RFC 2119 context"
class="rfc2119">MUST</em>
.rfc2119 {
font-style: normal;
font-size: 0.875em;
}
</pre>
<p>The author may explain why if these key words are not used in the
<abbr title="Request for Comments">RFC</abbr> sense.</p>
<p>Where they are not <em><q cite=
"ftp://ftp.rfc-editor.org/in-notes/rfc2119.txt">required for
interoperation or to limit behavior which has potential for causing
harm</q></em> these key words <em><q cite=
"ftp://ftp.rfc-editor.org/in-notes/rfc2119.txt">must not be used to try
to impose a particular method on implementors where the method is not
required for interoperability.</q></em></p>
</section>
</section>
<section id="Editorial">
<h2>Editorial Guidelines</h2>
<p>This section refers to editorial practice at W3C. It touches on
grammar, spelling, punctuation, case, linking, appearance and
markup.</p>
<section id="Grammar">
<h3>Grammar</h3>
<ul>
<li>Delete repeated words.</li>
<li>Check subject-verb agreement.</li>
<li>Break long sentences.</li>
<li>Eliminate contractions (<span class="not-en">e.g.</span>, "don't"
should read "do not")?</li>
</ul>
</section>
<section id="Spelling">
<h3>Spelling</h3>
<ul>
<li>Spell-check using a U.S. English dictionary. Append ",spell" to a
W3C <abbr title="Uniform Resource Identifier">URI</abbr> to invoke
W3C's spell checker.</li>
<li>Free dictionaries are also available on the <a title=
"Ispell home page" href=
"https://www.cs.hmc.edu/~geoff/ispell.html">Ispell home
page</a> [<cite><a href="#ref-ISPELL">ISPELL</a></cite>] for UNIX and
the <a title="Excalibur home page at Bucknell" href=
"http://www.eg.bucknell.edu/~excalibr/excalibur.html">Excalibur home
page</a> [<cite><a href="#ref-EXCAL">EXCAL</a></cite>] for Mac OS.</li>
<li>W3C uses <cite>Merriam-Webster's
Collegiate<sup><small>®</small></sup> Dictionary</cite>, 10th Edition
[<cite><a href="#ref-M-W">M-W</a></cite>], on the Web as the spelling
arbiter because it is free, on-line, and available to every technical
report author and editor. If a word does not appear there, use the
<cite>American Heritage<sup><small>®</small></sup> Dictionary</cite>,
4th Edition [<cite><a href="#ref-AH">AH</a></cite>]. Other dictionaries
are used as needed (for example, Random House and Webster's unabridged,
Oxford and Oxford Concise).</li>
<li>W3C uses U.S. English (<span class="not-en">e.g.</span>,
"standardise" should read "standardize" and "behaviour" should read
"behavior").</li>
<li>Form the plural of abbreviations, initialisms and acronyms without
an apostrophe (<span class="not-en">e.g.</span>, the plural of
<abbr title="Uniform Resource Identifier">URI</abbr> is <abbr title=
"Uniform Resource Identifiers">URIs</abbr> not <abbr title=
"Uniform Resource Identifiers">URI's</abbr>). See the FAQ
<cite>"Infrequently Asked Questions Concerning the Proper Spelling of
'DTD' in its Plural Form"</cite> [<cite><a href=
"#ref-PLURAL">PLURAL</a></cite>].</li>
</ul>
</section>
<section id="Punctuation">
<h3>Punctuation</h3>
<ul>
<li>Use correct punctuation. A hard copy of <cite>The Chicago Manual of
Style</cite> or <cite>The Gregg Reference Manual</cite> may be of some
help.</li>
<li>Remember you are typing <abbr title=
"HyperText Markup Language">HTML</abbr> or <abbr title=
"Extensible Markup Language">XML</abbr> not TeX. Use quotation marks
rather than grave accents and apostrophes to quote text (<span class=
"not-en">e.g.</span>, ``value'' should read "value").</li>
</ul>
</section>
<section id="Case">
<h3>Case, Combining Words, and Hyphenation</h3>
<ul>
<li>Capitalize W3C entities to match the <cite>W3C Process
Document</cite> [<cite><a href="#ref-PROCESS">PROCESS</a></cite>]
(<span class="not-en">e.g.</span>, Working Group, Recommendation).</li>
<li>Make the case, number of words, and hyphenation in terms match
<a href="#Terms">chapter 12</a>.</li>
</ul>
</section>
<section id="Misc">
<h3>Miscellaneous</h3>
<ul>
<li>Spell out acronyms and initialisms in their first occurrence in
prose, for example, "Internet Engineering Task Force
(<abbr>IETF</abbr>)" or "Internationalization (<abbr>I18N</abbr>)." In
subsequent occurrences when they are not spelled out, use
<code>abbr</code> elements, and give them
<code>title</code> attributes.</li>
<li>Check references (most commonly, for no full stop after the
<span class="not-en" xml:lang="la" lang="la">et</span> in et al.). Do
the entries match?</li>
</ul>
</section>
<section id="Linking">
<h3>Linking</h3>
<ul>
<li>Unless intentionally referring to the latest document in a series,
always refer to specific W3C documents by using the "this version"
<abbr title="Uniform Resource Identifier">URI</abbr>.</li>
<li>If you are referring to a W3C document using either its this
version or latest version <abbr title=
"Uniform Resource Identifier">URI</abbr>, note whether the <abbr title=
"Uniform Resource Identifier">URI</abbr> ends in a slash or not. These
identifiers do not end in an extension such as "<kbd>.html</kbd>".
Include the extension when intentionally referring to a specific
version (e.g., a <abbr title=
"Graphics Interchange Format">GIF</abbr> image where <abbr title=
"Graphics Interchange Format">GIF</abbr> and <abbr title=
"Portable Network Graphics">PNG</abbr> are both available through
content negotiation).</li>
<li>Visible <abbr title="Uniform Resource Identifier">URI</abbr>s and
<code>href</code> attributes should have the same value.</li>
</ul>
</section>
<section id="Examples">
<h3>Using Examples</h3>
<ul>
<li>Domains in examples adhere to section 3, "Reserved Example Second
Level Domain Names," in <cite><abbr title=
"Request for Comments">RFC</abbr> 2606</cite> [<cite><a href=
"#ref-DOMAINS">DOMAINS</a></cite>]. Use the domains
<kbd>example.com</kbd>, <kbd>example.org</kbd>, and
<kbd>example.net</kbd> for all examples. The Internet Assigned Numbers
Authority (IANA) reserves them for this purpose. If you need an
evocative name or the name of a business, use a machine name (<span
class="not-en">e.g.</span>, <kbd>http://cats.example.org</kbd>).</li>
<li>When not addressed by second level example domains, top level
domains (<abbr title="top level domain">TLD</abbr>s) adhere to section
2, "TLDs for Testing, & Documentation Examples," in
<cite><abbr title="Request for Comments">RFC</abbr> 2606</cite>
[<cite><a href="#ref-DOMAINS">DOMAINS</a></cite>]. Use
<kbd>.test</kbd>, <kbd>.example</kbd>, <kbd>.invalid</kbd> or
<kbd>.localhost</kbd>.</li>
<li>Remember to validate markup in examples. Escaped characters pass
through routine validation.</li>
<li>W3C publications are copyrighted by W3C, and W3C liability,
trademark and document use rules apply. Note that in general, one
should not use material (text, photo, audio) in examples when the
copyright is not held by W3C. If the group wishes to publish
copyrighted materials, it should contact the Team legal staff ([email protected]).</li>
<li>
<p>Use <abbr title="Cascading Style Sheets">CSS</abbr> with
<code>div</code> elements to mark up examples, as is done in the
<a href="https://html.spec.whatwg.org/multipage/semantics.html#document-metadata"
title="Section 4.2. Document metadata">HTML Living Standard</a>
([<cite><a href="#ref-HTML">HTML</a></cite>], section
4.2):</p>
</li>
</ul>
</section>
<section id="Images">
<h3>Images</h3>
<ul>
<li>We recommend that each image be available as PNG, even if you use
content negotiation to serve alternative formats.</li>
<li>Give images a background color (<span class="not-en">e.g.</span>,
white) so your technical report can be read with any style sheet
(<span class="not-en">e.g.</span>, with W3C's dark on light style
sheets, or a user style sheet that specifies a dark background).</li>
<li>Match image size to markup <code>width</code> and
<code>height</code> (or images will be distorted).</li>
<li>See the <a href="https://www.w3.org/TR/WCAG20-TECHS/">Web Content Accessibility
Guidelines Techniques</a> for information about providing alternative
text (<code>alt</code>) and long descriptions (<code>longdesc</code>)
for images. Also, don't forget to spell-check your alternative
text.</li>
</ul>
</section>
<section id="Markup">
<h3>Markup</h3>
<ul>
<li>Use markup as it is intended. The <code>blockquote</code> and
<code>ul</code> and <code>li</code> elements were designed for
quotations and lists and not for indentation. Use <abbr title=
"Cascading Style Sheets">CSS</abbr> instead.</li>
<li>Remove extraneous non-breaking spaces.</li>
<li>Mark up attributes and elements consistently.</li>
<li>Make sure there are no <code>font</code> or <code>basefont</code>
elements in your document.</li>
<li>Make sure all <code>table</code> elements in your document are real
data tables, not tables used for layout.</li>
<li>Make sure there are no <code>bgcolor</code>,
<code>background</code>, <code>color</code>, <code>face</code>,
<code>marginheight</code>, <code>marginwidth</code> or
<code>size</code> attributes.</li>
<li>Give each page <code>lang="en-US"</code> on the <code>html</code>
element for <abbr title="HyperText Markup Language">HTML</abbr>, or
<code>xml:lang="en-US" lang="en-US"</code> on the <code>html</code>
element for <abbr title=
"Extensible HyperText Markup Language">XHTML</abbr> syntax.</li>
<li>Use the <code>span</code> element and <code>lang</code> and
<code>xml:lang</code> attributes for language changes within a
page.</li>
<li>Make semantic distinctions using more than only color, for example,
a font-style change, so that color-blind individuals can see a
difference.</li>
<li>Links with the anchor text "Click here" provide no context. The
visitor may become lost not knowing where "here" is. See also
<cite><a href="https://www.w3.org/QA/Tips/noClickHere">Don't use "click
here" as link text</a></cite> [<cite><a href=
"#ref-CLICK-HERE">CLICK-HERE</a></cite>].</li>
<li>Mark up data <code>table</code> headers with <code>th</code> not by
bolding a <code>td</code>.</li>
</ul>
</section>
<section id="Large">
<h3>Large Documents</h3>
<p>Large single files that may be easy to print and search may not be
easy to download. For large documents:</p>