Skip to content

Commit

Permalink
[ac] (0) Allow authors to include documentation inside <script> block…
Browse files Browse the repository at this point in the history
…s that have src='' attributes. (credit: sp)

git-svn-id: http://svn.whatwg.org/webapps@2674 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
Hixie committed Jan 16, 2009
1 parent 15bc05e commit 88275de
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 3 deletions.
48 changes: 46 additions & 2 deletions index
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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>?)
-->


48 changes: 47 additions & 1 deletion source
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 88275de

Please sign in to comment.