forked from speced/respec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1059 lines (1038 loc) · 48.6 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>
<head>
<title>ReSpec.js — W3C Specification Writing Tool</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8' />
<script src='http://darobin.github.com/respec/builds/respec-w3c-common.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
// document info
specStatus: "ED",
shortName: "respec-js",
// publishDate: "2009-08-06",
// previousMaturity: "WD",
// previousPublishDate: "2009-03-15",
// previousURI : "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
copyrightStart: "2009",
edDraftURI: "http://darobin.github.com/respec/docs/",
// lcEnd: "2010-08-06",
// editors
editors: [
{ name: "Robin Berjon", url: "http://berjon.com/",
company: "Robineko", companyURL: "http://robineko.com/" },
],
// WG
wg: "People Who Like To Write Specs Help Group",
wgURI: "http://berjon.com/",
wgPublicList: "spec-writers-anonymous",
wgPatentURI: "",
};
</script>
</head>
<body>
<section id='abstract'>
This is the documentation for <a title='ReSpec'>ReSpec.js</a>, a tool that helps with specification editing primarily
within a W3C context.
</section>
<section id='sotd'>
<p>
This paragraph is here to demonstrate that it is possible to add a completely custom
piece of HTML inside the SotD.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
<dfn>ReSpec</dfn> is a Javascript [[ECMA-262]] based tool that unobtrusively allows editors
to write a specification focusing on the actual features and correctness, while needing to
pay as little attention as possible to issues pertaining to styling, referential integrity,
and the friendly dragon to slay that are the W3C Publication Rules.
</p>
<p>
There are many good existing tools that can be used to produce W3C specifications. A
non-exhaustive list includes:
</p>
<ul>
<li><a href='http://www.w3.org/2002/xmlspec/'>XMLSpec</a></li>
<li><a href='http://www.w3.org/Style/Group/css3-src/bin/postprocess'>CSS3 Module PostProcessor</a></li>
<li><a href='http://anolis.gsnedders.com/'>Anolis</a></li>
<li><a href='http://dev.w3.org/2006/webapi/ReSpec/'>ReSpec</a> (Perl version)</li>
<li>Many I forget...</li>
</ul>
<p>
But I was dissatisfied with all of them, including the one I wrote. The primary reason for
that was that they all require one to run a tool in between editing and reloading the
browser — an extra step that at the end of a long day's work editing is one step too many.
Beyond that there are some smaller issues that I personally have with each, but it is
largely a matter of taste.
</p>
<p>
At this point I have applied at least cursory testing to this tool using Firefox 3.5,
Opera 10, and Safari 4. Without testing I would expect it to work in a reasonably recent
Chrome, and not in any version of Internet Explorer (patches welcome).
</p>
</section>
<section>
<h2>Support</h2>
<p>
The official support channel for ReSpec is <a href='mailto:spec-prod@w3.org'>spec-prod@w3.org</a>.
The archives are available at
<a href='http://lists.w3.org/Archives/Public/spec-prod/'>http://lists.w3.org/Archives/Public/spec-prod/</a>.
You can subscribe by sending email to
<a href='mailto:spec-prod-request@w3.org?Subject=subscribe'>spec-prod-request@w3.org</a> with
"subscribe" as the subject line.
</p>
<p>
<strong>Please</strong> use that instead of emailing me (Robin) directly as the chances are that questions
or enhancement ideas will be shared by others. Thanks!
</p>
</section>
<section>
<h2>Concepts</h2>
<p>
The fundamental ideas that underlie <a title='ReSpec'>ReSpec.js</a> are:
</p>
<dl>
<dt>It Just HTML</dt>
<dd>
You just edit HTML, with some extra convention but nothing extra. All the decoration is
performed by the script, informed by some very basic configuration. There is a simple
<a href='template.html'>template</a> that you can use to get started.
</dd>
<dt>No Tool</dt>
<dd>
You never have to run a tool outside of your editor and browser. While the specification
is being developed that's all that's needed. When a snapshot is needed for publication,
all it takes is saving the generated DOM to a file (the script is very careful to cleanly
remove itself and its dependencies so that you should normally get a document that's
PubRules-OK).
</dd>
<dt><abbr title="Don't Repeat Yourself">DRY</abbr></dt>
<dd>
You shouldn't have to repeat anything within a specification, or across specifications
(apart from the template). For instance, marking RFC 2119 keywords is automatic, the
WebIDL support makes it possible to specify both the WebIDL and its documentation in
the same place without repeating a single part of it, etc..
</dd>
</dl>
</section>
<section>
<h2>General Structure</h2>
<p>
Most of what is described here will make a whole lot more sense if you look at the
<a href='template.html'>template</a>'s source before you get started.
</p>
<p>
The general structure of a <a>ReSpec</a> document is that of an HTML5 [[!HTML5]] document, with a
few extra conventions so that the <a>ReSpec</a> processor may infer additional semantics.
</p>
<p>
Inside <code>head</code>, the <code>title</code> element contains the title that will also
be used to generate the <code>h1</code> in the specification's header. Then external <code>script</code>
element loads in <a>ReSpec</a>, and another one inlines the basic configuration that it requires.
</p>
<p>
Inside the <code>body</code>, each section of the specification is contained inside a
<code>section</code> element. At least one of these MUST have an <code>id</code> of
"abstract" (and MUST contain just the text of the abstract). Sections can be
nested to any depth and are expected to have a heading title. Any of
<code>h2</code>-<code>h6</code> is acceptable as they will be automatically renamed to
the <em>hN</em> applicable to that depth.
</p>
<p>
If there is a <code>section</code> element with <code>id</code> "sotd" anywhere with the
document, it will be removed, and its content will be inserted inside the <em>Status of
this Document</em> as additional custom content.
</p>
<p>
If there is a <code>section</code> element with <code>id</code> "conformance" in the document
(and that element MAY be completely empty), it will be replaced with a template conformance
section that mentions the RFC 2119 keywords and the such. If it has any content it will be
appended after that template.
</p>
<p>
During processing, <code>section</code> elements will be converted to <code>div</code>
elements with <code>class</code> "section". Note that this will only happen if you request
that XHTML1 be generated. (X)HTML5 has a section element, so it will not be replaced.
</p>
<p>
Any section at the beginning that has a <code>class</code> of "introductory" will not
be included in the Table of Contents. The first root-level section with a <code>class</code> of
"appendix" will start the appendices section, labelled with letters.
</p>
<p>
Each <code>section</code> MAY have an <code>id</code> — if not, one will be generated
based on the <code>textContent</code> of its heading.
</p>
<p>
Any <code>section</code> that has a <code>class</code> of "informative" will be marked as
"non-normative" in the output using the usual text.
</p>
<p>
You MUST NOT create sections for the <em>Status of this Document</em>, the <em>ToC</em>, or
the <em>References</em> as they will be automatically generated for you.
</p>
<p>Same document references may be created using the following
formatting:
</p>
<pre>
<a href="#general-structure" class="sectionRef"></a>
</pre>(It is
necessary for the explicit closing tag to be present.)
The class signals that this will be replaced with a link containing
the section number and title as follows:
<pre><a href="#general-structure" class="sectionRef">section Section-Number Section-Title</a></pre>
</section>
<section>
<h2>Configuration</h2>
<p>
The only part of <a>ReSpec</a> that isn't just straightforward HTML is the configuration, which
thankfully is minimal (and a lot simpler than the HTML that it generates and which is
required in all W3C specifications).
</p>
<p>
The configuration is stored in a Javascript object called <code>respecConfig</code>.
</p>
<dl>
<dt>specStatus</dt>
<dd>
<p>
This is the status of the document, as keyed in the following table. If in doubt,
use <code>ED</code>.
</p>
<table class='simple'>
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr><td>NOTE</td><td>Note</td></tr>
<tr><td>FPWD-NOTE</td><td>First Public WG Note</td></tr>
<tr><td>WG-NOTE</td><td>Working Group Note</td></tr>
<tr><td>CG-NOTE</td><td>Co-ordination Group Note</td></tr>
<tr><td>IG-NOTE</td><td>Interest Group Note</td></tr>
<tr><td>Member-SUBM</td><td>Member Submission</td></tr>
<tr><td>Team-SUBM</td><td>Team Submission</td></tr>
<tr><td>XGR</td><td>Incubator Group Report</td></tr>
<tr><td>MO</td><td>Member-Only Document</td></tr>
<tr><td>ED</td><td>Editor's Draft</td></tr>
<tr><td>FPWD</td><td>First Public Working Draft</td></tr>
<tr><td>WD</td><td>Working Draft</td></tr>
<tr><td>LC</td><td>Last Call Working Draft</td></tr>
<tr><td>CR</td><td>Candidate Recommendation</td></tr>
<tr><td>PR</td><td>Proposed Recommendation</td></tr>
<tr><td>PER</td><td>Proposed Edited Recommendation</td></tr>
<tr><td>REC</td><td>Recommendation</td></tr>
<tr><td>RSCND</td><td>Rescinded Recommendation</td></tr>
<tr><td>unofficial</td><td>An unofficial draft. Use this if you're producing a document outside of W3C</td></tr>
<tr><td>base</td><td>Just the basic template, not a specification</td></tr>
</tbody>
</table>
<p>
The <code>specStatus</code> is used to pick the base style sheet, as well as to configure
various parts of the specification's header and <em>Status of this Document</em>. Some of
the header notably depends on whether the specification is on "Rec-track", which is the
case if the <code>specStatus</code> is one of: "FPWD", "WD", "LC", "CR", "PR", "PER", or "REC".
</p>
</dd>
<dt>shortName</dt>
<dd>
The specification's short name, as in http://www.w3.org/TR/<strong>short-name</strong>/. Note
that short names are assigned by the Director — ask your Team contact or Chair in advance of
publication.
</dd>
<dt>subtitle</dt>
<dd>
W3C specifications have an optional subtitle that is displayed
below the title in the heading section. Define yours here if you have
one.
</dd>
<dt>copyrightStart</dt>
<dd>
Some W3C specifications have a copyright that spans a range of years.
You can specify the optional starting year with this parameter.
</dd>
<dt>publishDate</dt>
<dd>
When a draft is made ready for publication it is often done several days in advance. In that
case, set this to the desired date in YYYY-MM-DD format. Otherwise comment it out, it'll
default to today.
</dd>
<dt>previousPublishDate</dt>
<dd>
If there is a previously published version of this draft, set this to its date in YYYY-MM-DD
format. If there isn't simply comment it out (or set it to a false value).
</dd>
<dt>previousMaturity</dt>
<dd>
If there is a previously published version of this draft, set this to its maturity level.
</dd>
<dt>previousURI</dt>
<dd>
If the previous version wasn't in the W3C TR space, you can supply an explicit URI. If it
is in TR space then the URI will be automatically determined.
</dd>
<dt>additionalCopyrightHolders</dt>
<dd>
If there are additional copyright holders in addition to the W3,
they can be listed in this parameter. For example, if the copyright
notice without <code>additionalCopyrightHolders</code> reads
"Copyright © 2009 W3C ... " then with
"Foo" listed it will read "Copyright © 2009 Foo &
W3C ... ".
</dd>
<dt>edDraftURI</dt>
<dd>
If there a publicly available Editor's Draft, this is the link to it. This will typically be
the link to the CVS version of the document you're editing.
</dd>
<dt>implReport</dt>
<dd>
For a PR draft this specifies the URI of an implementation report and
is noted in the status section. Use of this parameter is not
required for a PR draft, as such information can be supplied
in the custom paragraph if needed. This is otherwise ignored.
</dd>
<dt>lcEnd</dt>
<dd>
If the draft is a Last Call WD it needs to have a review period with a given end date. This is
that date in YYYY-MM-DD format. It is also required and used
in the status section of a PR draft to indicate when the
previous LC ended. This is otherwise ignored.
</dd>
<dt>crEnd</dt>
<dd>
If the draft is a Candidate Recommendation it needs to have an end date that is the promised
<em>minimal</em> date before which it will not transition to PR. This is that date in YYYY-MM-DD format.
This is otherwise ignored.
</dd>
<dt>prEnd</dt>
<dd>
If the draft is a Proposed Recommendation it needs to have
an end date for the PR period. This is that date in YYYY-MM-DD format.
This is otherwise ignored. When prEnd is used, lcEnd should
also be specified indicating the end of the earlier LC.
</dd>
<dt>prevRecShortname</dt>
<dd>If there is an earler version of this specification at the
Recommendation level, set this to the shortname of that
version. This is
optional and not usually necessary.
<dt>extraCSS</dt>
<dd>
This is an array that contains URI references (that may be absolute or relative) to additional
CSS style sheets that you may wish to be loaded into the document. It is RECOMMENDED that you
include <code>http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css</code> as one of those, though
you may of course skip it and take care of the additional styles yourself.
</dd>
<dt>editors</dt>
<dd>
<p>
An array describing editors that contains objects with the following fields:
</p>
<table class='simple'>
<thead>
<tr><th>key</th><th>optional</th><th>description</th></tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>No</td>
<td>
The name of the editor.
</td>
</tr>
<tr>
<td>url</td>
<td>Yes</td>
<td>
The URL to the editor's website.
</td>
</tr>
<tr>
<td>company</td>
<td>Yes</td>
<td>
The editor's affiliation.
</td>
</tr>
<tr>
<td>companyURL</td>
<td>Yes</td>
<td>
The URL to the editor's affiliation's website.
</td>
</tr>
<tr>
<td>mailto</td>
<td>Yes</td>
<td>
The email address for the editor.
</td>
</tr>
<tr>
<td>note</td>
<td>Yes</td>
<td>Additional note related to this editor, displayed
as parenthetical after other
information.
</td>
</tr>
</tbody>
</table>
<p>
At least one editor is required, and you can have as many as you want. They will be displayed
in the provided order. There are two conventions usually
applied within W3C: by alphabetical
order of last name, or of first name — choose whichever
applies to your WG. Sometimes one
editor who stands out as having contributed far more than
most is placed first.
</p>
<p>
A note may be used to display additional relevant
information, such as the specific release the editor
worked on, for example. This could be done by setting
note to "2nd Edition", for example:
</p>
<dl><dt>Mr Example, Foo Company ( 2nd Edition )</dt><dd></dd></dl>
</dd>
<dt>authors</dt>
<dd>
<p>
An array describing authors that contains objects with
fields for each author. The format and definitions of the
fields are the same as for editors.
<p>
Use of authors is entirely optional,none are required. You
can have as many authors as you want. Display is the same
as described for editors.
</p>
</dd>
<dt>errata</dt>
<dd>Specifies the optional URI to the errata for the document. This is normally
only available when the document is a 'REC'.</dd>
<dt>alternateFormats</dt>
<dd><p>If specified, defines an array of
alternate formats in which document is available (e.g., XML, Postscript). The
format of the array is:</p>
<table class='simple'>
<thead>
<tr><th>key</th><th>description</th></tr>
</thead>
<tbody>
<tr>
<td>uri</td>
<td>
the relative or absolute URI to the alternate version.
</td>
</tr>
<tr>
<td>label</td>
<td>
the label to use for the version.
</td>
</tr>
</tbody>
</table>
</dd>
<dt>maxTocLevel</dt>
<dd>
If specified, is an integer used to indicate the maximum depth of the ToC. The depth is the
number of numbering levels, so for instance 4.19.5 is at depth 3. The first level is always
included in the ToC (otherwise there would be no ToC).
</dd>
<dt>doRDFa</dt>
<dd>
If this parameter is set, ReSpec.js will embed various RDFa attributes throughout
the generated specification. The triples generated use vocabulary items from dcterms,
foaf, bibo, and w3p. The parameter defaults to "1.1". If set to "1.0"
the system will generate (old, depecated) RDFa 1.0 content. If set to "1.1" it will
generate RDFa 1.1 content. If set to "false" then no RDFa will be embedded in the document.
</dd>
<dt>noIDLSorting</dt>
<dd>
By default, the generated WebIDL is produced in the order in which it is in the document, but
the generated HTML descriptions that match are sorted (this behaviour matches that found in
the DOM specifications). Setting this option to true causes the generated HTML to also be in
document order.
</dd>
<dt>noIDLIn</dt>
<dd>
Historically, IDL parameters have all started with "in", as inherited from OMG IDL. In WebIDL
this is optional, and this option turns it off for the entire document.
</dd>
<dt>noRecTrack</dt>
<dd>
If this document is of a status that usually goes with Rec Track, but isn't intended for it,
set this to true.
</dd>
<dt>noLegacyStyle</dt>
<dd>
if set, removes legacy DOM-style sections (Attributes etc.) following WebIDL blocks. This
brings ReSpec closer to the style used in Anolis.
</dd>
<dt>refNote</dt>
<dd>
<p>If the <code>refNote</code> parameter is defined, the
text contained within it is
provided as a paragraph in the References section, before
the normative and informative reference sub-sections. If
not defined then no paragraph is included.
</p><p>
This
may be used to provide a note regarding use of subsequent revisions
of references for example:
<pre class='example sh_html'>
respecConfig.refNote = "Dated references below are to the latest known \
or appropriate edition of the referenced work. The referenced works \
may be subject to revision, and conformant implementations may follow, \
and are encouraged to investigate the appropriateness of following, \
some or all more recent editions or replacements of the works \
cited. It is in each case implementation-defined which editions are \
supported.";
</pre></dd>
<dt>wg</dt>
<dd>
The full and official name of the group (WG, IG, CG, XG, TF, etc.) in charge of this document.
</dd>
<dt>wgURI</dt>
<dd>
The URI to the public page of the group named in <code>wg</code>.
</dd>
<dt>wgPublicList</dt>
<dd>
The name of the public mailing list for the group named in <code>wg</code>, without the
"@w3c.org" part. For instance for the DAP WG it is "public-device-apis".
</dd>
<dt>wgPatentURI</dt>
<dd>
<p>
The URI to the patent status for this group. This is for Rec-track documents only.
</p>
<p>
<span style='color: #f00; font-weight: bold;'>IMPORTANT</span>: this is an important
and legally relevant piece of information. Do <strong>not</strong> copy this URI from
another document unless you are certain that it is the correct one that applies to your
group and to that document. If you have the slightest shade of a doubt, ask your
friendly neighbourhood Team Contact.
</p>
<dt>addPatentNote</dt>
<dd>
<p>Additional note to follow patent information in status of
document, such as note on additional information related to disclosures.</p>
</dd>
</dl>
</section>
<section>
<h2>Table of Contents & Numbering</h2>
<p>
The <abbr title='Table of Contents'>ToC</abbr> is generated entirely for you, so long as
you are careful to stick to the following simple rules:
</p>
<ul>
<li>Sections are contained inside <code>section</code> elements</li>
<li>The first element child of a section MUST be a <code>h<var>n</var></code> element containing its title</li>
</ul>
<p>
Sections can be nested to any depth. Any of <code>h2</code>-<code>h6</code> is acceptable for
their required title as they will be automatically renamed to the <em>hN</em> applicable to that depth.
</p>
<p>
Any section at the beginning that has a <code>class</code> of "introductory" will not
be included in the Table of Contents. The first root-level section with a <code>class</code> of
"appendix" will start the appendices section, labelled with letters.
</p>
<p>
Each <code>section</code> MAY have an <code>id</code> — if not, one will be generated
based on the <code>textContent</code> of its heading (the algorithm was taken with minor
modification from Anolis).
</p>
</section>
<section>
<h2>RFC 2119</h2>
<p>
Any editor who wishes to do a good job MUST have read RFC 2119 [[!RFC2119]]. This
<abbr title='Request For Comments'>RFC</abbr> defines a number of keywords that have a specific
meaning in a standards context.
</p>
<p>
<a>ReSpec</a> recognises the full list of keywords (MUST, MUST NOT, REQUIRED, SHALL, SHALL
NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL) without requiring any specific
markup. They only need to be in uppercase so as to distinguish them from the regular
usage of such words that may otherwise occur.
</p>
</section>
<section>
<h2>Definitions</h2>
<p>
A <dfn>definition</dfn> is a term that is specified or clarified for the specific use of the
given specification. It is created using the <code>dfn</code> element. The terms being defined
will be either and in order (as per slightly enriched [[!HTML5]]):
</p>
<ol>
<li>the <code>title</code> attribute of the <code>dfn</code> element</li>
<li>
the <code>title</code> attribute of the only child element of <code>dfn</code> when it is
<code>abbr</code> or <code>acronym</code>
</li>
<li>
the <code>textContent</code> of the <code>dfn</code> element
</li>
</ol>
<p>
<a title='definition'>Definitions</a> can then be referred to using an <code>a</code> element
(as per [[!HTML5]]) without an <code>href</code> attribute (it will be added). As in this paragraph,
the <code>title</code> attribute can be used to provide the exact term to which the reference
is being made.
</p>
<p>
When referring to a term defined in another specification, the <code>a</code> element without
<code>href</code> is still to be used, but with a <code>class</code> set to "externalDFN".
</p>
</section>
<section>
<h2>References</h2>
<p>
Specifications make two kinds of references: normative and informative (sometimes referred to as
"non-normative" or "other references"). Reference maintenance is always painful, and will
regularly go out of synch.
</p>
<p>
<a>ReSpec</a> relies on an <a href='bibref/biblio.js'>external database of references</a> stored as the
<code>berjon.biblio</code> Javascript object. The keys to that database are the terms used to
refer to a given specification, and the values the <abbr title='HyperText Markup Language'>HTML</abbr>
that is inserted. The contents of that database were originally extracted from the database in
Refer format that is part of the CSS3 Module Preprocessor but is now maintained separately.
</p>
<p>
If you wish to acces an automatically generated HTML version of the biblio DB you can get it
<a href='biblio.html'>in the biblio.html file</a>, but be warned that this may be slow to
render. Using the initial JS document is often easier.
</p>
<p>
If you notice that a given entry is missing or out of date, you may patch it directly in CVS,
or contact Robin to update it.
</p>
<p>
In order to insert an informative reference, look for its code in the database and use the
following syntax: <code>[<!---->[CODE]]</code>. This will produce a result like the following: [[DAHUT]].
</p>
<p>
Likewise, in order to insert a normative reference, look for its code in the database and use the
same syntax but with a "!" in front of the code: <code>[<!---->[!CODE]]</code>. This will produce
a result like the following: [[!ELEMENTTRAVERSAL]].
</p>
<p>If the <code>refNote</code> parameter is defined then a paragraph will be
created in the References section with the content of that
parameter, as noted in the Configuration section.</p>
</section>
<section>
<h2>Abbreviations</h2>
<p>
<a>ReSpec</a> supports both <code>abbr</code> and <code>acronym</code> (and really doesn't want to hear
about the debate concerning these two — if you have a side, use whatever makes you happy). Once an
abbreviation is defined anywhere inside the document using one of these two elements and its <code>title</code>
attribute, any occurrence of the same abbreviation anywhere else in the body of the specification will
see itself wrapped automatically in the same element, with the same <code>title</code>. You can therefore
define an abbreviation thus: <abbr title='Devious Application of Hibernation to Ukulele Trolling'>DAHUT</abbr>.
</p>
<p>
Note that thanks the standard header, some abbreviations like W3C or ERCIM are always defined, while others
such as DAHUT come from the rest of the content.
</p>
</section>
<section>
<h2>Best Practice Documents</h2>
<p>
<p>Best practices may be shown, numbered and formatted using the
following formatting:
<pre class='example'>
<div class="practice">
<p>
<span id="sample-practice" class="practicelab">Title of the practice</span></p>
<p class="practicedesc">
More detailed decription of the practice.
</p>
</div>
</pre>
<div class="practice">
<p>
<span id="sample-practice" class="practicelab">Title of the practice</span></p>
<p class="practicedesc">
More detailed decription of the practice.
</p>
</div>
<p>If a <code>section</code> element with <code>id</code> "bp-summary" is
present, then a summary
list of best practices will be placed in it, linked to the best
practices that have an id on the <code>span</code> element.</p>
<pre class="example">
<section id='bp-summary'></section>
</pre>
</section>
<section>
<h2>Including other data</h2>
<p>
Sometimes a specification will need to incorporate data that is best kept in
an external file (e.g., an XML Schema implementation of the datatypes would be in an
'.xsd' file, but should also be in-line in the spec). <a>ReSpec</a> permits this
by allowing inclusion of arbitrary external data and also allowing optional
transformation of that data.
</p>
<p>
To reference an external resource, define the resource via the <code>data-include</code>
attribute (e.g., <code><div data-include='myDatatypes.xsd'></div></code> ).
The contents of the element with that attribute will be replaced with the data read from
the file.
</p>
<p>
To perform one or more transformations on the contents before they are placed in
the document, specify the names of transformation methods via the <code>data-oninclude</code>
attribute (e.g., <code><div data-include='myDatatypes.xsd' data-oninclude='updateSchema'></div></code> ).
Each whitespace separated method named will be called and passed
two parameters: the <code>berjon.respec</code> object and the contents of the
resource retrieved.
</p>
<p>
Here's a simple transformation method:
</p>
<pre class='example'>
function updateExample(doc, content) {
// perform transformations to make it render and prettier
return '<pre class="example">' + doc._esc(content) + '</pre>';
}
</pre>
</section>
<section>
<h2>Transforming data</h2>
<p>
Another thing you might want to do is transform arbitrary content in
your document (for example, to ensure that content within an 'example'
block is escaped). You can do this via the <code>data-transform</code>.
Just like the <code>data-oninclude</code> attribute above, this allows
you to specify a whitespace separated list of method names. Each will be called
and passed two parameters: the <code>berjon.respec</code> object and the contents of
the element.
</p>
<p>Here is an example, using the same method as above:</p>
<pre class='example'>
function updateExample(doc, content) {
// perform transformations to make it render and prettier
return '<pre class="example">' + doc._esc(content) + '</pre>';
}
</pre>
<p>And then the content:</p>
<pre class='example'>
<pre class='example' data-transform='updateExample'>
<html>
...
</html>
</pre>
</pre>
</section>
<section>
<h2>WebIDL Support</h2>
<p>
WebIDL [[!WEBIDL]] is the language that is used to define <abbr title='Application Programming Interface'>API</abbr>s
inside W3C specifications. It is powerful and very expressive, and at this stage <a>ReSpec</a>
only supports a limited (but hopefully useful) subset of it.
</p>
<p>
The issues with editing WebIDL directly in documents are as follow:
</p>
<ul>
<li>While evolving, it is easy to get the WebIDL proper and the accompanying prose out of sync</li>
<li>Proper linking from WebIDL to content and back is often too tedious to be done in full</li>
<li>Syntax highlighting is generally given up on</li>
</ul>
<p>
<a>ReSpec</a> does its best to provide all three of the above at a minimal cost.
</p>
<p>
Currently only interface and exception definitions are supported, and on them only the
simple variants of attributes, constants, and operations (with extended attributes
everywhere). Additional features will be added on a need-to-be-done basis.
</p>
<p>
The approach is simple. An interface is defined using a <code>dl</code> element, with a <code>class</code>
of "idl" and the <code>title</code> of which is the defining line for the interface, for
instance <code>[Constructor] interface Dahut : Mammal, Cryptoid</code> or
<code>exception Boom</code>.
</p>
<p>
Inside the <code>dl</code>, each <code>dt</code>/<code>dd</code> pair defines an interface
member (attribute, constant, or operation). The content of the <code>dt</code> element is the line
that defines the member (e.g. <code>readonly attribute DOMString chirality</code> or
<code>void yell ([AllowAny] in unsigned long volume, [TreatNullAs=EmptyString] in DOMString sentence)</code>);
and the <code>dd</code> element contains the description.
</p>
<p>
This format has the advantage of keeping information well-grouped together, using HTML
markup for the most part (so that even WYSIWYG editors can be used), while being simple
to parse and sufficiently expressive for most needs (especially as more features are
added).
</p>
<p>
The output that is generated replaces the <code>dl</code> with a syntax-highlighted and linked
WebIDL segment with all the members for the given interface in the order in which they were
defined; followed by two subsections listing respectively attributes and methods in alphabetical
order (further details will progressively be added to those descriptions).
</p>
<p>
An example will probably speak more clearly; the following simple code:
</p>
<pre class='example sh_html'><dl title='[Constructor] interface Dahut : Mammal, Cryptoid' class='idl'>
<dt>const unsigned short LEVROGYROUS = 0</dt>
<dd>
Turning left.
</dd>
<dt>const unsigned short DEXTROGYROUS = 1</dt>
<dd>
Turning right.
</dd>
<dt>readonly attribute DOMString chirality</dt>
<dd>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor (...)
</dd>
<dt>attribute unsigned long age</dt>
<dd>
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip (...)
</dd>
<dt>Dahut turnAround (in float angle, in boolean fall)</dt>
<dd>
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat (...)
</dd>
<dt>unsigned long trip ()</dt>
<dd>
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit (...)
</dd>
<dt>void yell ([AllowAny] in unsigned long volume, [TreatNullAs=EmptyString] in DOMString sentence)</dt>
<dd>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt (...)
</dd>
</dl></pre>
<p>
Will produce the following WebIDL section with links and syntax highlighting, as well as the two
following subsections that list attributes and methods:
</p>
<dl title='[Constructor] interface Dahut : Mammal, Cryptoid' class='idl'>
<dt>const unsigned short LEVROGYROUS = 0</dt>
<dd>
Turning left.
</dd>
<dt>const unsigned short DEXTROGYROUS = 1</dt>
<dd>
Turning right.
</dd>
<dt>readonly attribute DOMString chirality</dt>
<dd>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</dd>
<dt>attribute unsigned long age</dt>
<dd>
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
</dd>
<dt>Dahut turnAround (in float angle, in boolean fall)</dt>
<dd>
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
</dd>
<dt>unsigned long trip ()</dt>
<dd>
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</dd>
<dt>void yell ([AllowAny] in unsigned long volume, [TreatNullAs=EmptyString] in DOMString sentence)</dt>
<dd>
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</dd>
</dl>
<p>
The <a href='test-spec/webidl.html'>WebIDL testing document</a> provides a number of additional
examples.
</p>
<div class="note">
The <code>data-merge</code> attribute on the interface <code>dl</code> element instructs the
preprocessor to merge other definition(s) with the interface definition. The value of the
<code>data-merge</code> attribute is a whitespace delimited list of definition names to be
merged with the interface.
</div>
</section>
<section>
<h2>Saving the Generated Specification</h2>
<section>
<h2>In the Browser</h2>
<p>
Of course the downside of the approach taken by <a>ReSpec</a> is that the specification as it is
expected to be, with all its bells and whistles, exists only in your browser's memory. Publishing
directly with the script would not work as it does not work for all browsers (and there are still
quite a few people using Internet Explorer out there) and would not show all the content for
search indexing. And sadly enough browsers aren't very good at saving HTML that's been modified
by script.
</p>
<p>
The solution that is used here is that you hit the <code>Ctrl+Shift+Alt+S</code> key combination (this is
subject to change until we agree on an option we all like). That will show a menu offering to either
"Save as HTML", "Save as HTML (Source)", "Save as XHTML1", "Save as XHTML1 (Source)", "Save as XHTML5", or "Save as XHTML5
(Source)". You can hit <code>Esc</code> to hide it.
</p>
<p>
Those options are very similar. The non-source ones open a new window (which may be in a new tab depending
on your configuration) and shows you a document that should look exactly the same as the one you're
editing. That's normal. The difference is that it's a static document that represents the same DOM
tree as the live one after <a>ReSpec</a> has run. That page you can then save using your browser's
vanilla saving mechanism (be sure to refuse any option that tries to save the complete page with
images and other dependencies — you want just the (X)HTML). The "Source" alternative shows you the same
page's source code so that you can paste it into your favourite editor.
</p>
<p>
Note that some browsers will still save the original document when you use the non-Source alternative,
so if in doubt use the Source alternative.
</p>
<p>
Currently only HTML 4.01 and XHTML 1.0 are supported.
HTML5 is not supported because it is currently rejected
by PubRules.
</p>
<p>
The idea is that such snapshots would be created only when actual official W3C publication is
required — all the while that the specification is an Editor's Draft it should simply live
as itself.
</p>
<p>The tool is also capable of producing a diff-marked version.
, but if you have a configuration setting of
'previousDiffURI' set to a document to compare to
When selected, the tool will use special configuration
parameter 'previousDiffURI' (or the previousURI if
previousDiffURI is not defined) and the current content to produce
a diffmarked version by passing parameters 'oldfile' and
'newcontent' to the diff tool. It also sets the 'base' parameter.
By default, the diff tool is set to
http://www.aptest.com/standards/htmldiff/htmldiff.pl. You can
override this with the configuration parameter 'diffTool'.
</p>
</section>
<section>
<h2>Using a Command-line Utility</h2>
<p>
<code><a href="https://raw.github.com/darobin/respec/develop/tools/respec2html.js">respec2html.js</a></code>
is a command-line utility that converts a ReSpec source file to an HTML file. It depends on
<a href="http://phantomjs.org">PhantomJS</a>.
</p>
<pre class='example'>
Usage:
phantomjs respec2html.js respec-source html-output [timeout]
respec-source ReSpec source file, or an URL to the file
html-output Name for the HTML file to be generated
[timeout] An optional timeout in seconds, default is 10
</pre>
</section>
</section>
<section class='appendix'>
<h2>Examples</h2>
<p>
The source code of this very document makes use of many <a>ReSpec</a> features. It provides a good starting
point for examples.
</p>
<p>
Additionally there is a <a href='test-spec/index.html'>test specification</a> that exercises all
features at least in part, and can therefore be studied to see different aspects of <a>ReSpec</a> in action.
</p>
</section>
<section class='appendix'>
<h2>History</h2>
<p>
The initial <a>ReSpec</a> processor was written in Perl, for the Web API WG.
</p>
<ul>
<li>
2009-08-05 — first public release
</li>
<li>
2009-08-06 — set license to W3C; fixed publishDate bug (MaxF); reorganised code;
changed keyboard shortcut; added Esc to hide save menu; adding custom content to
the SotD (for TLR).
</li>
<li>
2009-08-10 - made hN renamed to the proper name h2-h6 depending on depth.
</li>
<li>
2009-08-25 - added handling of the Conformance section.
</li>
<li>
2009-08-27 - added support for WebIDL const; fixed bug that prevented inheritance;
added support for informative sections; made the script load its own dependencies;
made it possible to describe individual parameters in methods (NEEDS DOCUMENTING).
</li>
<li>
2009-08-28 - made an HTML document that dumps the biblio for easier reading, even if
slow; added support for syntax highlighting using SHJS.
</li>
<li>
2009-09-02 - added previousMaturity to link properly to previous versions.
</li>
<li>
2009-09-10 - added support for exception definitions (NEEDS DOCUMENTING); added
support for definition which exceptions and exception codes can be raised by a
given method (NEEDS DOCUMENTING); added support for exceptions that can be raised
by attributes (NEEDS DOCUMENTING).
</li>