HTML Standard Tracker


File a bug

SVNBugCommentTime (UTC)
2674[Authors] [Conformance Checkers] Allow authors to include documentation inside <script> blocks that have src='' attributes. (credit: sp)2009-01-16 01:45
@@ -10150,21 +10150,22 @@ people expect to have work and what is necessary.
    <dd><span>Flow content</span>.</dd>
    <dd><span>Phrasing content</span>.</dd>
    <dt>Contexts in which this element may be used:</dt>
    <dd>Where <span>metadata content</span> is expected.</dd>
    <dd>Where <span>phrasing content</span> is expected.</dd>
    <dt>Content model:</dt>
    <dd>If there is no <code title="attr-script-src">src</code>
    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>
    <dd><code title="attr-script-defer">defer</code></dd>
    <dd><code title="attr-script-type">type</code></dd>
    <dd><code title="attr-script-charset">charset</code></dd>
    <dt>DOM interface:</dt>
 <pre class="idl">interface <dfn>HTMLScriptElement</dfn> : <span>HTMLElement</span> {
            attribute DOMString <code title="dom-script-src">src</code>;
@@ -10780,20 +10781,63 @@ o............A....e
   <p>When examining types to determine if they support the language,
   user agents must not ignore unknown MIME parameters &mdash; types
   with unknown parameters must be assumed to be unsupported.</p>
    XXX we should reference #refsRFC4329
+  <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
+ -->
+  <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.stop();
+  </div>
   <h4>The <dfn><code>noscript</code></dfn> element</h4>
   <dl class="element">
    <dd><span>Metadata content</span>.</dd>
    <dd><span>Flow content</span>.</dd>
    <dd><span>Phrasing content</span>.</dd>
    <dt>Contexts in which this element may be used:</dt>
    <dd>In a <code>head</code> element of an <span title="HTML documents">HTML document</span>, if there are no ancestor <code>noscript</code> elements.</dd>
@@ -61288,14 +61332,16 @@ TODO (or delay):
        string as a hexadecimal number.
  XXX * expose the form data set, either as an object (on which one can
        invoke the JSON serialiser), or in the form of a method on
        HTMLFormElement that returns the form data set serialised
        according to a particular encoding (defaulting to the form's
        enctype="" one, probably). This would allow forms to be used
        with XHR-like systems without having to manually construct the
        form data set the way that is done today.
  XXX * placeholder="" for <textarea>, e.g. as seen on:
+ XXX * become more consistent about what markup we use to mark up
+       productions (nothing? <i>? <code>?)