Permalink
Browse files

[ac] (0) Allow authors to include documentation inside <script> block…

…s that have src='' attributes. (credit: sp)

git-svn-id: http://svn.whatwg.org/webapps@2674 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information...
1 parent 15bc05e commit 88275de2fdfe2fca2141976589efe6681673ec42 @Hixie Hixie committed Jan 16, 2009
Showing with 93 additions and 3 deletions.
  1. +46 −2 index
  2. +47 −1 source
View
48 index
@@ -346,7 +346,8 @@
<ol>
<li><a href=#script><span class=secno>4.3.1 </span>The <code>script</code> element</a>
<ol>
- <li><a href=#scriptingLanguages><span class=secno>4.3.1.1 </span>Scripting languages</a></ol></li>
+ <li><a href=#scriptingLanguages><span class=secno>4.3.1.1 </span>Scripting languages</a></li>
+ <li><a href=#inline-documentation-for-external-scripts><span class=secno>4.3.1.2 </span>Inline documentation for external scripts</a></ol></li>
<li><a href=#the-noscript-element><span class=secno>4.3.2 </span>The <code>noscript</code> element</a></li>
<li><a href=#the-eventsource-element><span class=secno>4.3.3 </span>The <code>eventsource</code> element</a></ol></li>
<li><a href=#sections><span class=secno>4.4 </span>Sections</a>
@@ -9645,7 +9646,8 @@ people expect to have work and what is necessary.
<dd>If there is no <code title=attr-script-src><a href=#attr-script-src>src</a></code>
attribute, depends on the value of the <code title=attr-script-type><a href=#attr-script-type>type</a></code> attribute.</dd>
<dd>If there <em>is</em> a <code title=attr-script-src><a href=#attr-script-src>src</a></code>
- attribute, the element must be empty.</dd>
+ attribute, the element must be either empty or contain only
+ <a href=#inline-documentation-for-external-scripts>script documentation</a>.</dd>
<dt>Element-specific attributes:</dt>
<dd><code title=attr-script-src><a href=#attr-script-src>src</a></code></dd>
<dd><code title=attr-script-async><a href=#attr-script-async>async</a></code></dd>
@@ -10180,6 +10182,46 @@ o............A....e
-->
+ <h5 id=inline-documentation-for-external-scripts><span class=secno>4.3.1.2 </span><dfn title="script documentation">Inline documentation for external scripts</dfn></h5>
+
+ <p>If a <code><a href=#script>script</a></code> element's <code title=attr-script-src><a href=#attr-script-src>src</a></code> attribute is specified, then the
+ contents of the <code><a href=#script>script</a></code> element, if any, must be such
+ that the value of the DOM <code title=dom-script-text><a href=#dom-script-text>text</a></code>
+ attribute, which is derived from the element's contents, matches the
+ <code>documentation</code> production in the following ABNF. <a href=#refsABNF>[ABNF]</a></p> <!-- XXX
+ ftp://ftp.rfc-editor.org/in-notes/std/std68.txt -->
+
+ <pre>documentation ::= *( *( space / tab / comment ) [ line-comment ] newline )
+comment ::= slash star *( not-star / star not-slash ) 1*star slash
+line-comment ::= slash slash *not-newline
+space ::= &lt; a U+0020 SPACE character &gt;
+tab ::= &lt; a U+0009 TAB character &gt;
+newline ::= &lt; a U+000A LINE FEED character &gt;
+star ::= &lt; a U+002A ASTERISK character &gt;
+slash ::= &lt; a U+002F SOLIDUS character &gt;
+not-star ::= &lt; a single Unicode character other than a U+002A ASTERISK character &gt;
+not-slash ::= &lt; a single Unicode character other than a U+002F SOLIDUS character &gt;
+not-newline ::= &lt; a single Unicode character other than a U+000A LINE FEED character &gt;</pre>
+
+ <div class=example>
+
+ <p>This allows authors to include documentation, such as license
+ information or API information, inside their documents while still
+ referring to external script files. The syntax is constrained so
+ that authors don't accidentally include what looks like valid
+ script while also providing a <code title=attr-script-src><a href=#attr-script-src>src</a></code> attribute.</p>
+
+ <pre>&lt;script src="cool-effects.js"&gt;
+ // create new instances using:
+ // var e = new Effect();
+ // start the effect using .play, stop using .stop:
+ // e.play();
+ // e.stop();
+&lt;/script&gt;</pre>
+
+ </div>
+
+
<h4 id=the-noscript-element><span class=secno>4.3.2 </span>The <dfn><code>noscript</code></dfn> element</h4>
@@ -56044,6 +56086,8 @@ TODO (or delay):
form data set the way that is done today.
XXX * placeholder="" for <textarea>, e.g. as seen on:
http://code.google.com/p/support/issues/detail?id=1#makechanges
+ XXX * become more consistent about what markup we use to mark up
+ productions (nothing? <i>? <code>?)
-->
View
48 source
@@ -10157,7 +10157,8 @@ people expect to have work and what is necessary.
attribute, depends on the value of the <code
title="attr-script-type">type</code> attribute.</dd>
<dd>If there <em>is</em> a <code title="attr-script-src">src</code>
- attribute, the element must be empty.</dd>
+ attribute, the element must be either empty or contain only
+ <span>script documentation</span>.</dd>
<dt>Element-specific attributes:</dt>
<dd><code title="attr-script-src">src</code></dd>
<dd><code title="attr-script-async">async</code></dd>
@@ -10787,6 +10788,49 @@ o............A....e
-->
+ <h5><dfn title="script documentation">Inline documentation for external scripts</dfn></h5>
+
+ <p>If a <code>script</code> element's <code
+ title="attr-script-src">src</code> attribute is specified, then the
+ contents of the <code>script</code> element, if any, must be such
+ that the value of the DOM <code title="dom-script-text">text</code>
+ attribute, which is derived from the element's contents, matches the
+ <code>documentation</code> production in the following ABNF. <a
+ href="#refsABNF">[ABNF]</a></p> <!-- XXX
+ ftp://ftp.rfc-editor.org/in-notes/std/std68.txt -->
+
+ <pre>documentation ::= *( *( space / tab / comment ) [ line-comment ] newline )
+comment ::= slash star *( not-star / star not-slash ) 1*star slash
+line-comment ::= slash slash *not-newline
+space ::= &lt; a U+0020 SPACE character >
+tab ::= &lt; a U+0009 TAB character >
+newline ::= &lt; a U+000A LINE FEED character >
+star ::= &lt; a U+002A ASTERISK character >
+slash ::= &lt; a U+002F SOLIDUS character >
+not-star ::= &lt; a single Unicode character other than a U+002A ASTERISK character >
+not-slash ::= &lt; a single Unicode character other than a U+002F SOLIDUS character >
+not-newline ::= &lt; a single Unicode character other than a U+000A LINE FEED character ></pre>
+
+ <div class="example">
+
+ <p>This allows authors to include documentation, such as license
+ information or API information, inside their documents while still
+ referring to external script files. The syntax is constrained so
+ that authors don't accidentally include what looks like valid
+ script while also providing a <code
+ title="attr-script-src">src</code> attribute.</p>
+
+ <pre>&lt;script src="cool-effects.js">
+ // create new instances using:
+ // var e = new Effect();
+ // start the effect using .play, stop using .stop:
+ // e.play();
+ // e.stop();
+&lt;/script></pre>
+
+ </div>
+
+
<h4>The <dfn><code>noscript</code></dfn> element</h4>
@@ -61295,6 +61339,8 @@ TODO (or delay):
form data set the way that is done today.
XXX * placeholder="" for <textarea>, e.g. as seen on:
http://code.google.com/p/support/issues/detail?id=1#makechanges
+ XXX * become more consistent about what markup we use to mark up
+ productions (nothing? <i>? <code>?)
-->
</body>

0 comments on commit 88275de

Please sign in to comment.