Source

Anolis / README.src.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
<!doctype html>
<html lang="en-gb-x-sneddy">
<meta charset="utf-8">
<title>Anolis 1.2pre</title>
<link rel="stylesheet" href="style.css">
<style>
a:not([href]) {
background-color: #00f;
color: #fff;
}
span:not([data-anolis-xref=""]):not(.secno) {
background-color: #a00;
color: #fff;
}
</style>

<header>
    <h1>[TITLE]</h1>
    <h2 class="no-num no-toc">Documentation — [DATE]</h2>
</header>

<h2 class="no-num no-toc">Contents</h2>
<!--toc-->

<h2>Introduction</h2>

<p>The need for Anolis came from the need for long technical documents to
include niceties such as cross-references and a table of contents for the
purpose of easy navigation — doing this manually can be a great chore
especially when sections are numbered and a section is added, consequently
changing the numbering of many others, leading to it being advantageous to do
it programmatically.

<p>Anolis does this on HTML documents, as a number of sequential processes.
Currently cross-referencing, section numbering, table of contents creation, and
a number of substitutions are done (mainly relating to the current date).

<h2>Installing Anolis</h2>

<h3>Requirements</h3>

<p>The following are the minimum requirements: later versions should also work
without issue.

<ul>
    <li><a href="http://python.org/">Python</a> 2.3
    <li><a href="http://codespeak.net/lxml/">lxml</a> 2.0
    <li><a href="http://code.google.com/p/html5lib">html5lib</a> 0.10
</ul>

<h3>Obtaining a copy</h3>

<p>Releases are occasionally made. A link to the latest release can be found
from the <a href="http://anolis.gsnedders.com">Anolis website</a>.

<p>Alternatively, a copy can be obtained from <dfn>our <a
href="http://www.selenic.com/mercurial/">Mercurial</a> repository</dfn>: this
is where our ongoing development occurs, and allows any revision (and therefore
any release) to be downloaded. Our repository is located at
<code><!--begin-link-->http://hg.gsnedders.com/anolis/<!--end-link--></code>.

<h3>Installation</h3>

<p>Normally, installation is done through <a
href="http://pypi.python.org/pypi/setuptools">setuptools</a>, with the
following command:

<p><code>python setup.py install</code>

<p>Please see setuptools' documentation for information on installation options
(such as installing in non-standard locations).

<h3>Running the test suite</h3>

<p>The source distribution and the current development copy (in <span
data-anolis-xref="our mercurial repository">Mercurial</span>) both contain a test suite.
It can be run with the following command:

<p><code>python runtests.py</code>

<p>Any test failures should be reported at our <dfn><a
href="http://bugs.gsnedders.com/projects/show/anolis">bug
tracker</a></dfn>.

<h2>Using Anolis</h2>

<p>Anolis is invoked through the <code>anolis</code> command. The
<dfn><code>--help</code></dfn> (or <dfn><code>-h</code></dfn>) option gives
some basic help.

<p>The <dfn><code>--enable</code></dfn> and <dfn><code>--disable</code></dfn>
options enable/disable respectively the process given as the option value
(e.g., <code>--disable=toc</code> disables building the <span
data-anolis-xref="table of contents/section numbering">table of contents and
numbering sections</span>). The default processes are <code>sub</code>
(<span>substitution</span>), <code>toc</code> (<span>table of contents/section
numbering</span>), and <code>xref</code> (<span>cross-referencing</span>). Any
enabled process loaded via <code>from processes import foo</code>, and if that
fails <code>import foo</code> (where <code>foo</code> is the process), and is
then called as <code>foo.foo(ElementTree, **kwargs)</code>.

<p>Some options alter what is used to parse and serialize the document: the
<dfn><kbd>--parser</kbd></dfn> option allows either <kbd>html5lib</kbd> (the
default) or <kbd>lxml.html</kbd> (this is quicker, but does not comply to the
<a href="http://whatwg.org/html">HTML</a> specification) to be used to parse
the input file, and the <dfn><kbd>--serializer</kbd></dfn> option allows the
same two values, but controls the serializer used for output (note that
lxml.html has some rather severe issues as a serializer)<!--; passing the XXX:
need double hyphen <dfn><code>xml</code></dfn> option uses libxml2's XML parser
instead-->.

<p>The <dfn><kbd>--output-encoding</kbd></dfn> option sets the character
encoding used for output — this defaults to UTF-8. Treatment of characters that
cannot be represented in the set output encoding is dependant on the serializer
selected via the <span>--serializer</span> option.

<p>Anolis offers a <dfn>compatibility mode</dfn>, which aims to be compatible
with the <a href="http://www.w3.org/Style/Group/css3-src/bin/postprocess">CSS3
module postprocessor</a> (within reason). This is mainly provided for the sake
of pre-existing <a href="http://w3.org/">W3C</a> documents. The
<dfn><code>--w3c-compat</code></dfn> option turns on this compatibility mode,
although specific options that turn on just one compatibility feature at a time
are also available (and are documented below under each <span
data-anolis-xref="processes">process</span>) — these are all implied by the
<code>--w3c-compat</code> options, with one exception:
<code>--w3c-compat-crazy-substitutions</code>, as it can lead to undesirable
results.

<p>The options <dfn><code>--newline-char</code></dfn> and
<dfn><code>--indent-char</code></dfn> set the newline and indent strings (they
do not have to be a single character) respectively. They default to U+000A LINE
FEED (LF) and U+0020 SPACE respectively. These are only used when generating
large trees of generated markup, such as the table of contents.

<p>Other <span data-anolis-xref="processes">process</span> specific options are
documented under the <span data-anolis-xref="processes">process</span> to which
they belong.

<p>Upon a <dfn>fatal error</dfn>, processing of the document is terminated and
the output file is left unchanged.

<p><dfn>Interactive content</dfn> is as defined in <a
href="http://whatwg.org/html">HTML</a>: the <code>a</code>, <code>bb</code>,
<code>details</code>, and <code>datagrid</code> elements; the
<code>audio</code> and <code>video</code> elements when they have a
<code>controls</code> attribute; the <code>menu</code> element when the
<code>type</code> attribute is case-insensitively equal to
<code>toolbar</code>.

<p><dfn data-anolis-xref="id generation">When an <code>id</code> attribute is
needed, it is created as follows</dfn>:

<ol>
    <li>Let <var>i</var> be equal to 0.
    <li>If the element already has an <code>id</code> attribute, return its
value, and terminate this algorithm.
    <li>If the <code>title</code> attribute is present and its value is not
empty and does not consist of
<span data-anolis-spec=encoding>ASCII whitespace</span> only, let
<var>generated_id</var> be equal to its value; otherwise, let
<var>generated_id</var> be equal to
<span data-anolis-spec=domcore>textContent</span>.
    <li>The <var>generated_id</var> is stripped of leading/trailing
<span data-anolis-spec=encoding>ASCII whitespace</span> and converted to
lowercase (behaviour of this is dependent on the current locale setting of
Python).
    <li>The first of the following list whose condition matches the current
state of the string is done:
        <ol>
            <li>If <var>generated_id</var> is an empty string,
<var>generated_id</var> is set to <code>generatedID</code>.
            <li>If the <dfn><code>--force-html4-id</code></dfn> option is used, or the DOCTYPE's public identifier is one of:
                <ul>
                    <li><code>-//W3C//DTD HTML 4.0//EN</code>
                    <li><code>-//W3C//DTD HTML 4.0 Transitional//EN</code>
                    <li><code>-//W3C//DTD HTML 4.0 Frameset//EN</code>
                    <li><code>-//W3C//DTD HTML 4.01//EN</code>
                    <li><code>-//W3C//DTD HTML 4.01 Transitional//EN</code>
                    <li><code>-//W3C//DTD HTML 4.01 Frameset//EN</code>
                    <li><code>ISO/IEC 15445:2000//DTD HyperText Markup
                      Language//EN</code>
                    <li><code>ISO/IEC 15445:2000//DTD HTML//EN</code>
                    <li><code>-//W3C//DTD XHTML 1.0 Strict//EN</code>
                    <li><code>-//W3C//DTD XHTML 1.0 Transitional//EN</code>
                    <li><code>-//W3C//DTD XHTML 1.0 Frameset//EN</code>
                    <li><code>-//W3C//DTD XHTML 1.1//EN</code>
                </ul>
              Then:
                <ol>
                    <li>All runs of characters apart from U+002D HYPHEN-MINUS
(-), U+002E FULL STOP (.), U+0030 DIGIT ZERO to U+0039 DIGIT NINE (0–9),
U+003A COLON (:), U+0041 LATIN CAPITAL LETTER A to U+005A LATIN CAPITAL LETTER
Z (A–Z), U+005F LOW LINE (_), and U+0061 LATIN SMALL LETTER A to U+007A LATIN
SMALL LETTER Z (a–z) are replaced by a single U+002D HYPHEN-MINUS (-)
character within <var>generated_id</var>.
                    <li>Leading and trailing U+002D HYPHEN-MINUS (-) characters
are removed from <var>generated_id</var>.
                    <li>If <var>generated_id</var> is not empty and if the
first character is not in the range U+0041 LATIN CAPITAL LETTER A to U+005A 
LATIN CAPITAL LETTER Z (A–Z) or U+0061 LATIN SMALL LETTER A to U+007A LATIN 
SMALL LETTER Z (a–z), <var>generated_id</var> is prefixed by a single U+0078 
LATIN SMALL LETTER X (x) character.
                </ol>
            
            <li>Otherwise, runs of characters that do not match the ifragment
production in <a href="http://www.ietf.org/rfc/rfc3987">RFC 3987</a> are
replaced by a single U+002D HYPHEN-MINUS (-) character within
<var>generated_id</var>, and then leading and trailing U+002D HYPHEN-MINUS (-)
characters are removed from <var>generated_id</var>.
        </ol>
    <li>If <var>generated_id</var> is empty, <var>generated_id</var> is set to <code>generatedID</code>.
    <li>Let <var>output_id</var> equal <var>generated_id</var>.
    <li>If <var>output_id</var> matches a ready-existing ID, continue to the
next step; otherwise, jump to step 12.
    <li>Increment <var>i</var> by one.
    <li>Let <var>output_id</var> equal <var>generated_id</var> suffixed with a 
U+002D HYPHEN-MINUS (-) character followed by <var>i</var> as a big-endian base 
10 number.
    <li>Jump back to step 8.
    <li>The generated ID is <var>output_id</var>.
</ol>

<h2><dfn>Processes</dfn></h2>

<p>The elements listed in the below processes, except where otherwise stated,
are the local name of the element <!--either--> in null namespace<!-- or in the
<dfn>HTML namespace</dfn> (<code>http://www.w3.org/1999/xhtml</code>)-->.

<h3><dfn>Cross-referencing</dfn></h3>

<p>Cross-referencing has three essential parts: <dfn
data-anolis-xref="definition">definitions</dfn> that define <dfn
data-anolis-xref="term">terms</dfn>, and <dfn
data-anolis-xref="instance">instances</dfn> of those <span
data-anolis-xref="term">terms</span>.

<p><span data-anolis-xref="term">Terms</span> are taken from the
<code>data-anolis-xref</code> attribute if present, failing that the
<code>title</code> attribute if that is present, otherwise from the
<span data-anolis-spec=domcore>textContent</span> property of the
<code>dfn</code> element. By default, Anolis will throw a
<span>fatal error</span> if a <span>term</span> is defined more than once: this
behaviour can be turned off (causing the final <span>definition</span> of the
<span>term</span> to be the one that is used) by the
<dfn><code>--allow-duplicate-dfns</code></dfn> option.

<p><span data-anolis-xref="definition">Definitions</span> are marked-up with
the <code>dfn</code> element.

<p><span data-anolis-xref="instance">Instances</span> are marked-up with
various elements, depending on the setting of
<dfn><code>--w3c-compat-xref-elements</code></dfn>: if it is disabled (the
default), the <code>abbr</code>, <code>code</code>, <code>i</code>,
<code>span</code>, and <code>var</code> elements are used for <span
data-anolis-xref="instance">instances</span>; if it is enabled, the
<code>abbr</code>, <code>acronym</code>, <code>b</code>, <code>bdo</code>,
<code>big</code>, <code>code</code>, <code>del</code>, <code>em</code>,
<code>i</code>, <code>ins</code>, <code>kbd</code>, <code>label</code>,
<code>legend</code>, <code>q</code>, <code>samp</code>, <code>small</code>,
<code>span</code>, <code>strong</code>, <code>sub</code>, <code>sup</code>,
<code>tt</code>, <code>var</code> elements are used for <span
data-anolis-xref="instance">instances</span>. Those that are only there in
<span>compatibility mode</span> are there because either they should not
semantically be used for an <span>instance</span>, or because they are not
present in <a href="http://whatwg.org/html">HTML</a>. An
<span>instance</span> is only used if it does not have an <span>interactive
content</span> or <code>dfn</code> element as either a parent or a child.

<p>Both <span data-anolis-xref="definition">definitions</span> and <span
data-anolis-xref="instance">instances</span> are <dfn
data-anolis-xref="cross-reference normalization">normalized</dfn> as follows:

<ul>
    <li>Leading and trailing
<span data-anolis-spec=encoding>ASCII whitespace</span> is stripped,
    <li>Converted to lowercase (behaviour of this is dependent on the current
locale setting of Python),
    <li>All consecutive <span data-anolis-spec=encoding>ASCII whitespace</span>
is replaced with a single U+0020 SPACE CHARACTER<!-- unless there is a
<code>pre</code> element as a parent-->, and
    <li>If <dfn><code>--w3c-compat-xref-normalization</code></dfn> is enabled,
all characters apart from U+0020 SPACE CHARACTER, U+002D HYPHEN-MINUS (-),
U+0030 DIGIT ZERO to U+0039 DIGIT NINE (0–9), U+0041 LATIN CAPITAL LETTER A
to U+005A LATIN CAPITAL LETTER Z (A–Z), and U+0061 LATIN SMALL LETTER A to
U+007A LATIN SMALL LETTER Z (a–z) are removed.
</ul>

<p>If the <span>instance</span> is contained within a <code>span</code>
element, the <code>span</code> element is turned into an <code>a</code>
element, and a <code>href</code> attribute is added to link it to the
<span>definition</span> (e.g., <code>&lt;span>foo&lt;/span></code> becomes
<code>&lt;a href=#foo>foo&lt;/a></code>) — all other attributes are
preserved. Otherwise (when the <span>instance</span> is not contained within a
<code>span</code> element), the location of the <code>a</code> element when
linking an <span>instance</span> is dependent on the
<dfn><code>--w3c-compat-xref-a-placement</code></dfn> option: if it is disabled
(the default), the <code>a</code> element is placed around the element
containing the <span>instance</span> (e.g., <code>&lt;i>foo&lt;/i></code>
becomes <code>&lt;a href=#foo>&lt;i>foo&lt;/i>&lt;/a></code>); if it is
enabled, the <code>a</code> element goes within the element containing the
<span>instance</span> and goes around all of its content (e.g.,
<code>&lt;i>foo&lt;/i></code> becomes <code>&lt;i>&lt;a
href=#foo>foo&lt;/a>&lt;/i></code>).

<h3><dfn>Table of contents/section numbering</dfn></h3>

<p>To create a table of contents, and to number the <span
data-anolis-xref="section">sections</span> of the document, an
<dfn>outline</dfn> is created (this is a list of <span
data-anolis-xref="section">sections</span>, which can each contain more <span
data-anolis-xref="section">sections</span>, where a <dfn>section</dfn>
represents a part of the document, and often has a <dfn
data-anolis-xref="section heading">heading</dfn> associated with it — for more
detailed definitions see <a href="http://whatwg.org/html">HTML</a>). This
means not only are the <code>h1</code><code>h6</code> elements supported, but
also elements such as <code data-anolis-xref="">section</code> are used to
create the <span>outline</span>. After creating the <span>outline</span>, every
<span>section</span> with a depth between those provided by
<dfn><code>--min-depth</code></dfn> and <dfn><code>--max-depth</code></dfn>
(defaulting to two and six respectively), and which has a <span
data-anolis-xref="section heading">heading</span>, is numbered if it does not
have <code>no-num</code> as a class, and is added to the table of contents if
it does not have <code>no-toc</code> as a class. <span
data-anolis-xref="section">Sections</span> without a <span
data-anolis-xref="section heading">heading</span> are treated as if they did
not exist, unless they have children, in which they will appear to exist while
not existing all at once (e.g., they increment the <span>section</span>
numbering, though that is not output anywhere; and they get a list item in the
table of contents, with only the children within it, and no link to the
<span>section</span> itself).

<p>The format of <span>section</span> numbers should comply with <a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=6937">ISO
2145:1978</a>, Numbering of divisions and subdivisions in written documents.
This means that each <span>section</span> number is given by Arabic numerals,
seperated by a single U+002E FULL STOP character, and there is no trailing
U+002E FULL STOP character.

<p>The <span>section</span> number is inserted as the first child node of the
<span>section heading</span> as a <code>span</code> element with the
<code>class</code> attribute set to <code>secno</code>: this is copied into the
table of contents.

<p>Pre-existing <code>span</code> elements with a class of <code>secno</code>
are removed from all <span data-anolis-xref="section heading">section
headings</span>, regardless of whether their depth falls within the range given
by <code>--min-depth</code> and <code>--max-depth</code>.

<p>The table of contents is built up as an ordered list (an <code>ol</code>
element), with each <span>section</span> marked up as a <code>li</code>
element, and child <span data-anolis-xref="section">sections</span> are marked
up with an <code>ol</code> within that <code>li</code> (and this continues
recursively, ad infinitum). By default, the root element of the table of
contents (an <code>ol</code> element) is given a <code>class</code> attribute
set to <code>toc</code>; however, with the
<dfn><code>--w3c-compat-class-toc</code></dfn> option this is placed on every
<code>ol</code> within the table of contents. The entire <span>section
heading</span> is copied to be the content of the list item, with all
<span>interactive content</span> elements and <code>id</code> attributes
removed.

<p>A <span>normal comment substitution</span> is done with
<var>sub_identifier</var> equal to <code>toc</code>, and the table of contents
as the replacement.

<h3><dfn>Substitution</dfn></h3>

<p>Various strings are replaced in magic ways: a <dfn>normal string
substitution</dfn> takes the form of <code>[xxx]</code> where xxx is
case-sensitively the replacement, which may be followed by any characters apart
from U+005D RIGHT SQUARE BRACKET (]) before the final U+005D RIGHT SQUARE
BRACKET character — these extra characters are effectively a comment, and
carry absolutely no meaning, and vanish into some as-of-yet unknown abyss when
the string replacement is done. The entire string must be contained within a
single text node.

<p>A <dfn>normal comment substitution</dfn> is one where there is a string,
<var>sub_identifier</var>, that identifies the comment for the substitution,
and the replacement. All nodes between a comment with a value equal to (with
leading and trailing <span data-anolis-spec=encoding>ASCII whitespace</span>
removed) <code>begin-</code> followed by <var>sub_identifier</var> and one with
q value equal to (with leading and trailing
<span data-anolis-spec=encoding>ASCII whitespace</span> removed)
<code>end-</code> followed by <var>sub_identifier</var> are removed, and
replaced with the replacement. Additionally, any comment (with leading and
trailing <span data-anolis-spec=encoding>ASCII whitespace</span> removed) with
a value equal to <var>sub_identifier</var> is replaced with a comment with a
value of <code>begin-</code> followed by <var>sub_identifier</var>, the
replacement, and then a comment with a value of <code>end-</code> followed by
<var>sub_identifier</var>.

<p>The <dfn>W3C status</dfn> is given by the
<code>--w3c-status=<var>status</var></code> argument.

<p>If that argument isn't given, it is found, when needed by one of the
substitutions, by iterating all text nodes in document order (i.e., attribute
values and comments have no effect), and for each node, the following is done
(in this order):

<ol>
    <li>If the node contains, case-insensitively, "latest", followed by one or
more <span data-anolis-spec=encoding>ASCII whitespace</span> characters,
followed by "version", searching stops, and the default is used (ED).
    <li>Otherwise, if the node, case-sensitively, contains
"http://www.w3.org/TR/" followed by one of "MO", "WD", "CR", "PR", "REC",
"PER", or "NOTE", which in turn is followed by U+002D HYPHEN-MINUS (-), then
searching stops, and the status is whatever matched the previous list of
options by the first match in the text node.
</ol>

<p>A side-effect of doing it in this order is the fact that if a node contains
both of these possible strings is that the latter is ignored, meaning that the
default (ED) is used.

<!-- I wish the above was more sane — it took me several hours to work out
(though the comment in the CSS3 Module Postprocessor docs saying, "If there is
a H2 subheading under the H1 that gives the spec's status, the [STATUS]
variable will be initialized from that, otherwise it will default to WD." did
not help me work it out quickly, as what is done is completely utterly
different to that) — even though the algorithm is simple enough, it is just
far too unexpected. Sadly, though, pre-existing documents depend on this very
exact behaviour, and thus it cannot be changed. -->

<p>There is also a <dfn>long W3C status</dfn>, which correlates to the
<span>W3C status</span> under the following mapping:

<table>
    <tr>
        <th><span>W3C Status</span>
        <th><span>Long W3C Status</span>
    <tr>
        <td>MO
        <td>W3C Member-only Draft
    <tr>
        <td>ED
        <td>Editor's Draft
    <tr>
        <td>WD
        <td>W3C Working Draft
    <tr>
        <td>CR
        <td>W3C Candidate Recommendation
    <tr>
        <td>PR
        <td>W3C Proposed Recommendation
    <tr>
        <td>REC
        <td>W3C Recommendation
    <tr>
        <td>PER
        <td>W3C Proposed Edited Recommendation
    <tr>
        <td>NOTE
        <td>W3C Working Group Note
</table>

<p>By default, the <span data-anolis-xref="normal string substitution">normal
string substitutions</span> are:

<dl>
    <dt><code>[<!---->DATE]</code>
    <dd>This is replaced with the current date for UTC±0 in the form of, e.g.,
<samp>31 July 2008</samp>. The word used for the month is dependent on the
current locale of Python. The number of the day of the month has no leading
zeros.
    
    <dt><code>[<!---->CDATE]</code>
    <dd>This is replaced with the current date for UTC±0 in the form YYYYMMDD,
e.g., <samp>20080731</samp>. This is a conforming <a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=40874">ISO
8601:2004</a> date.
    
    <dt><code>[<!---->YEAR]</code>
    <dd>This is replaced with the current year for UTC±0, in the form YYYY,
e.g., <samp>2008</samp>. This is a conforming <a
href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=40874">ISO
8601:2004</a> year.
    
    <dt><code>[<!---->TITLE]</code>
    <dd>This is replaced with the
<span data-anolis-spec=domcore>textContent</span> of the first
<code>title</code> element which is within the first <code>head</code> of the
document, or an empty string if such a <code>title</code> element does not
exist.
</dl>

<p>There is one comment substitution by default. Any nodes between a comment
with a value equal to (with leading and trailing
<span data-anolis-spec=encoding>ASCII whitespace</span> removed)
<code>begin-link</code> and one with a value equal to <code>end-link</code>,
with <span>interactive content</span> elements removed (though children of
those elements preserved), are effectively wrapped in an <code>a</code> element
which has a <code>href</code> attribute equal to the
<code data-anolis-spec=domcore>textContent</code> of all the nodes between the
two comments concatenated in document order. The two comments must have the
same parent, otherwise a <span>fatal error</span> occurs.

<p>If <dfn><code>--w3c-compat-substitutions</code></dfn> is enabled, the
following <span data-anolis-xref="normal string substitution">normal string
substitutions</span> are done in addition to those above:

<dl>
    <dt><code>[STATUS]</code>
    <dd>This is replaced with the <span>W3C status</span>.
    
    <dt><code>[LONGSTATUS]</code>
    <dd>This is replaced with the <span>long W3C status</span>.
</dl>

<p>Additionally, the following <span data-anolis-xref="normal comment
substitution">normal comment substitutions</span> are done:

<dl>
    <dt><var>sub_identifier</var> equal to <code>logo</code>
    <dd>Replacement is equal to: <code>&lt;p>&lt;a
href="http://www.w3.org/">&lt;img alt="W3C"
src="http://www.w3.org/Icons/w3c_home"/>&lt;/a>&lt;/p></code> (parsed as an XML
fragment, and serialized into the output document in the needed format).
    
    <dt><var>sub_identifier</var> equal to <code>copyright</code> 
    <dd>Replacement is equal to: <code>&lt;p class="copyright">&lt;a
href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright&lt;/a>
&#xA9; [<!---->YEAR] &lt;a href="http://www.w3.org/">&lt;abbr title="World
Wide Web Consortium">W3C&lt;/abbr>&lt;/a>&lt;sup>&#xAE;&lt;/sup> (&lt;a
href="http://www.csail.mit.edu/">&lt;abbr title="Massachusetts Institute of
Technology">MIT&lt;/abbr>&lt;/a>, &lt;a
href="http://www.ercim.org/">&lt;abbr title="European Research Consortium
for Informatics and Mathematics">ERCIM&lt;/abbr>&lt;/a>, &lt;a
href="http://www.keio.ac.jp/">Keio&lt;/a>, &lt;a
href="http://ev.buaa.edu.cn/">Beihang&lt;/a>), All Rights Reserved. W3C &lt;a
href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability&lt;/a>,
&lt;a
href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark&lt;/a>
and &lt;a
href="http://www.w3.org/Consortium/Legal/copyright-documents">document
use&lt;/a> rules apply.&lt;/p></code> (parsed as an XML fragment, and
serialized into the output document in the needed format).
</dl>

<p>There is one further string substitution, and this is only done when
<dfn><code>--w3c-compat-crazy-substitutions</code></dfn> is enabled (note that
this is not included in <code>--w3c-compat</code>). A string of
<code>http://www.w3.org/StyleSheets/TR/W3C-</code> followed by one or more
characters in the range U+0041 LATIN CAPITAL LETTER A to U+005A LATIN CAPITAL
LETTER Z (A–Z) is replaced with whatever
<code>http://www.w3.org/StyleSheets/TR/W3C-[STATUS]</code> would evaluate to
be. Like the <span data-anolis-xref="normal string substitution">normal string
substitutions</span>, this string must be contained in a single text node.

<!-- Is that crazy enough to justify the option name? -->

<h3>References</h3>

<p>A "references" section can be generated automagically by enabling the
<dfn><code>refs</code></dfn> process. There are two kinds of elements relevant
to this process:
<span data-anolis-xref="reference instance">reference instances</span> and
<span data-anolis-xref="reference section">reference sections</span>.
<span>Reference data</span> is also required.

<p><dfn>Reference data</dfn> is to be given as a
<dfn><code>references.json</code></dfn> file, in the <code>data</code> folder.
The expected data structure is a set of name-value pairs, with a pair for each
possible reference. The name is referred to as the
<dfn>reference abbreviation</dfn>, and the value is to be a set with the
following name-value pairs:
<ul class=brief>
  <li><dfn data-anolis-xref=reference-title><code>title</code></dfn>:
      the title of the referenced document;
  <li><dfn data-anolis-xref=reference-href><code>href</code></dfn>:
      the URL of the referenced document;
  <li><dfn data-anolis-xref=reference-authors><code>authors</code></dfn>:
      an array of authors or editors of the referenced document;
  <li><dfn data-anolis-xref=reference-publisher><code>publisher</code></dfn>:
      the organisation publishing the referenced document (optional);
  <li><dfn data-anolis-xref=reference-isbn><code>isbn</code></dfn>:
      for dead tree publications, their ISBN (optional).
</ul>

<p><dfn data-anolis-xref="reference instance">Reference instances</dfn> are
defined by <code title>span</code> elements with a
<code title>data-anolis-ref</code> attribute. Their
<span data-anolis-spec=domcore>textContent</span> must be the
<span>reference abbreviation</span> of a reference defined in the
<span>reference data</span>. A <span>reference instance</span> is either
<i>informative</i> or <i>normative</i>: it is <i>informative</i> if the element
has an <code title>informative</code> class and <i>normative</i> otherwise.

<p><dfn data-anolis-xref="reference section">Reference sections</dfn> are
<code title>div</code> elements, wherein the reference lists will be
constructed.
In <span>compatibility mode</span>, two distinct
<span data-anolis-xref="reference section">reference sections</span> are used:
one with <code title>anolis-references-normative</code> as its id, for those
references with at least one <i>normative</i>
<span data-anolis-xref="reference instance">instance</span>, and one with
<code title>anolis-references-informative</code> as its id, for the others.
When Anolis is not in <span>compatibility mode</span>, just one
<span>reference section</span> is used, with an
<code title>anolis-references</code> id. In this case, the references for which
all <span data-anolis-xref="reference instance">instances</span> are
<i>informative</i> are prefixed with "(Non-normative)&#xa0;".

<h3>Cross-specification cross-referencing</h3>
<p>The <dfn><code>xspecxref</code></dfn>
<span data-anolis-xref="processes">process</span> makes it possible to reference
<span data-anolis-xref="x-terms">terms</span> defined in other documents, with
or without the the cooperation of its author. This
<span data-anolis-xref="processes">process</span> works in a way very similar to
the <code>xref</code> process.

<p>The essential parts of this <span data-anolis-xref="processes">process</span>
are <dfn data-anolis-xref="x-instances">instances</dfn> of
<dfn data-anolis-xref="x-terms">terms</dfn>, which are defined in
<dfn data-anolis-xref="x-documents">documents</dfn>. These
<span data-anolis-xref="x-documents">documents</span> are referenced by their
respective <dfn data-anolis-xref="x-shortnames">shortnames</dfn>. The elements
used to mark up the <span data-anolis-xref="x-instances">instances</span> must
have a <dfn><code>data-anolis-spec</code></dfn> attribute whose value is a
<span data-anolis-xref="x-shortnames">shortnames</span>.

<p>In order to generate links to the other
<span data-anolis-xref="x-documents">document</span>, a JSON file with the
<dfn>list of defined terms</dfn> for each
<span data-anolis-xref="x-documents">document</span> must be supplied in the
<dfn><code>xrefs</code></dfn> subfolder of the <code>data</code> folder, which
must be listed in the <dfn><code>specs.json</code></dfn>. This file must contain
a set of name-value mappings where the name is a
<span data-anolis-xref="x-shortnames">shortname</span> and the value is the URL
of its <span data-anolis-xref="x-documents">document</span>'s
<span>list of defined terms</span>, relative to the <code>xrefs</code> folder.

<div class=example>
<p>For example, the <code>specs.json</code> file could look as follows:
<pre>{
  "webidl": "webidl.json",
  "domcore": "dom/webdomcore.json",
  "html": "dom/html5.json",
  "csscascade": "css/css3cascade.json",
  "cssbackgrounds": "css/css4backgrounds.json"
}</pre>
</div>

<p>Each <span>list of defined terms</span> must contain a set of name-value
pairs, with the following names:
<ul class=brief>
  <li><dfn data-anolis-xref="xspecxref-url"><code>url</code></dfn>:
      the URL of the <span data-anolis-xref="x-documents">document</span>, with
      a traling "<code title>#</code>";
  <li><dfn data-anolis-xref="xspecxref-definitions"><code>definitions</code></dfn>:
      a set of name-value mappings where the names are the
      <span data-anolis-xref="x-terms">terms</span> in the
      <span data-anolis-xref="x-documents">document</span>,
      <span data-anolis-spec=domcore>converted to lowercase</span>, and the
      values are the
      <span data-anolis-spec=domcore data-anolis-xref=concept-id>ID</span>s of
      the defining element in the
      <span data-anolis-xref="x-documents">document</span>.
</ul>

<div class=example>
<p>For example, the <code title>webdomcore.json</code> file could look as
follows:
<pre>{
  "url": "http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#",
  "definitions": {
    "converted to lowercase": "converted-to-lowercase",
    "concept-id": "concept-id"
  }
}</pre>
</div>

<p>In order to create such a file, the <dfn><code>--dump-xrefs</code></dfn>
option can be used. Calling Anolis with the
<code>--dump-xrefs=<var title>path</var></code> argument will update the
<span>list of defined terms</span> at <var title>path</var> with the
<span data-anolis-xref="x-terms">terms</span> currently defined in the
input document.

<p>Before the first use, a JSON file must be provided at <var title>path</var>,
with the <code data-anolis-xref="xspecxref-url">url</code> property already
present.

<h2 class="no-num">Acknowledgements</h2>

<p>Thanks to Andrew Sidwell, Anne van Kesteren, Henri Sivonen, Ian Hickson,
James Graham, Lachlan Hunt, Magnus Kristiansen, Michael(tm) Smith, and Philip
Taylor for their ever needed help.

<p>Special thanks to Bert Bos for creating the CSS3 Module Postprocessor, on
which this is partially based, and (with <code>--w3c-compat</code>) claims to
be partially compatible with. Further special thanks to Bert Bos for creating a
number of things (especially the algorithm for finding the <span>W3C
status</span>) that took the author of Anolis many hours to reverse
engineer.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.