Skip to content
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
Hixie committed Jan 16, 2009
1 parent 15bc05e commit 88275de2fdfe2fca2141976589efe6681673ec42
Showing with 93 additions and 3 deletions.
  1. +46 −2 index
  2. +47 −1 source
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>
<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>
-->


<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>

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 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>

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.