Update/add source header comments (continued) (#1226)

Fix #1201 Finish the rest of the files...
w3c · Feb 22, 2018 · 43ca139 · 43ca139
1 parent 51b984a
commit 43ca139
Show file tree

Hide file tree

Showing 22 changed files with 268 additions and 79 deletions.
diff --git a/sections/browsers.include b/sections/browsers.include
@@ -4,7 +4,7 @@
 
     Browsers
 
-  This source produces chapter 6:
+  This source produces Chapter 6: Loading Web pages
   https://w3c.github.io/html/browsers.html
 
   It covers Window and WindowProxy objects,

diff --git a/sections/dom.include b/sections/dom.include
@@ -7,7 +7,7 @@
   This source produces chapter 3: "Semantics, structure, and APIs of HTML documents"
   https://w3c.github.io/html/dom.html
 
-  It covers
+  It covers:
   - the "Document" object, significantly extending what is defined in the DOM specification
       including attributes of it like document.cookies, document.referrer, document.head, document.forms, etc.
   - The HTMLElement interface

diff --git a/sections/iana.include b/sections/iana.include
@@ -4,11 +4,10 @@
 
     IANA
 
-  This source produces Chapter 12: "IANA considerations"
+  This source produces Chapter 12: IANA considerations
   https://w3c.github.io/html/iana.html
 
   It covers:
-
   - text/html
   - multipart/x-mixed-replace
   - applicatoin/xhtml+xml

diff --git a/sections/infrastructure.include b/sections/infrastructure.include
@@ -4,7 +4,7 @@
 
     Infrastructure
 
-  This section produces chapter 2: Common Infrastructure
+  This section produces Chapter 2: Common Infrastructure
   https://w3c.github.io/html/infrastructure.html
 
   It covers:

diff --git a/sections/introduction.include b/sections/introduction.include
@@ -1,16 +1,21 @@
 <section>
+
 <!--
 
-This is the source file for Introduction.html
-All the content is "non-normative". It contains
-- a background / potted history of HTML
-- a few design notes
-- a note on HTML and XML syntax
-- information on how the spec is written and how to read it
-- some privacy considerations
-- an introduction to HTML itself, how to write it, etc.
-- non-normative conformance requirements for content
-- links to some other specs: charmod, unicode security, and some accessibility specs
+    Introduction
+
+ This source produces Chapter 1: Introduction
+ https://w3c.github.io/html/introduction.html
+
+  All the content is "non-normative". It covers:
+  - a background / potted history of HTML
+  - a few design notes
+  - a note on HTML and XML syntax
+  - information on how the spec is written and how to read it
+  - some privacy considerations
+  - an introduction to HTML itself, how to write it, etc.
+  - non-normative conformance requirements for content
+  - links to some other specs: charmod, Unicode security, and some accessibility specs
 
 -->
 

diff --git a/sections/obsolete.include b/sections/obsolete.include
@@ -1,13 +1,17 @@
 <section>
+
 <!--
 
-        OBSOLETE
-
-This section produces Chapter 11: Obsolete Features https://w3c.github.io/html/obsolete.html
+    Obsolete
+
+  This section produces Chapter 11: Obsolete Features
+  https://w3c.github.io/html/obsolete.html
+
+  It covers features which are deprecated and should or must not be used in conforming
+  HTML content, but which user agents need to handle because there is a body of legacy
+  content using them.
 
-It covers features which are deprecated and should or must not be used in conforming HTML content,
-  but which user agents need to handle because there is a body of legacty content using them.
-  Examples include
+  Examples include:
   - appcache
   - applet
   - keygen

diff --git a/sections/rendering.include b/sections/rendering.include
@@ -1,7 +1,40 @@
 <section>
+
 <!--
 
-        RENDERING
+    Rendering
+
+  This source produces Chapter 10: Rendering
+  https://w3c.github.io/html/rendering.html
+
+  It covers:
+  - Introduction to Rendering
+  - The CSS user agent style sheet and presentational hints
+  - Non-replacement elements, such as:
+    + Hidden elements
+    + The page
+    + Flow & Phrasing content
+    + Bidirectional text
+    + Quotes
+    + Sections and headings
+    + Lists
+    + Tables
+    + Margin collapsing quirks
+    + Form controls
+    + The hr, fieldset, and legend elements
+  - Replaced elements, such as:
+    + Embedded content, images, and attributes for each
+    + Image maps
+  - Widgets, such as:
+    + the various form controls
+    + details and summary
+    + marquee
+    + meter
+    + progress
+  - Frames and framesets
+  - Interactive media
+  - Print media
+  - Unstyled XML documents
 
 -->
 

diff --git a/sections/semantics-common-idioms.include b/sections/semantics-common-idioms.include
@@ -2,12 +2,12 @@
 
 <!--
 
-    COMMON IDIOMS
+    Common Idioms
 
   This source produces section 4.13: Common Idioms without Dedicated Elements
   https://w3c.github.io/html/common-idioms-without-dedicated-elements.html
 
-  It covers
+  It covers:
   - Subheadings and taglines
   - "breadcrumb" navigation information
   - Tag Clouds

diff --git a/sections/semantics-document-metadata.include b/sections/semantics-document-metadata.include
@@ -2,7 +2,7 @@
 
 <!--
 
-    DOCUMENT METADATA
+    Document Metadata
 
   This source produces section 4.2: Document Metadata
   https://w3c.github.io/html/document-metadata.html

diff --git a/sections/semantics-edits.include b/sections/semantics-edits.include
@@ -1,12 +1,15 @@
 <!--
 
-         Edits
-
-This source file produces section 4.6: Edits https://w3c.github.io/html/edits.html#edits
+    Edits
 
-It describes the ins and del elements, and how they span different kinds of content.
+  This source file produces section 4.6: Edits
+  https://w3c.github.io/html/edits.html#edits
+
+  It covers:
+  The ins and del elements, and how they span different kinds of content.
 
 -->
+
 <section>
   <h3 id="edits">Edits</h3>
 

diff --git a/sections/semantics-embedded-content.include b/sections/semantics-embedded-content.include
@@ -1,19 +1,22 @@
 <section>
+
 <!--
-     Embedded content
-
-This source produces section 4.7: Embedded Content https://w3c.github.io/html/semantics-embedded-content.html
 
-It covers 
+    Embedded content
+
+  This source produces section 4.7: Embedded Content
+  https://w3c.github.io/html/semantics-embedded-content.html
 
-- media elements:
-  + img, picture, source, and their attributes
-  + video, audio, track, and their attributes
-  + core APIs for playing media files
-- Image maps
-- Embedding SVG and MathML into HTML
+  It covers:
+  - media elements:
+    + img, picture, source, and their attributes
+    + video, audio, track, and their attributes
+    + core APIs for playing media files
+  - Image maps
+  - Embedding SVG and MathML into HTML
 
 -->
+
 <h3 id="semantics-embedded-content">Embedded content</h3>
 
 <h4 id="embedded-content-introduction">Introduction</h4>

diff --git a/sections/semantics-forms.include b/sections/semantics-forms.include
@@ -1,5 +1,33 @@
 <section>
 
+<!--
+
+    Forms
+
+  This source produces section 4.10: Forms
+  https://w3c.github.io/html/sec-forms.html
+
+  It covers:
+  - Introduction to forms including:
+    + Form's user interface
+    + Server and client side information
+    + Differences between field type, autofill name, and input modality
+    + Date, time, and number formats
+  - Categories
+  - Form Elements:
+    + form, label, input states and types, button, select, datalist,
+        optgroup, option, textarea, output, meter, fieldset, legend,
+        and progress
+  - Form control infrastructure
+  - Attributes common to form controls
+    + including name, dirname, disabled, etc.
+  - APIs for text field selections
+  - Constraints
+  - Form submission
+  - Resetting a form
+
+-->
+
 <h3 id="sec-forms"><dfn>Forms</dfn></h3>
 
 <h4 id="forms-introduction">Introduction</h4>
@@ -5686,7 +5714,7 @@ input { height: 75px; width: 49px; background: #D5CCBB; color: black; }
       <form action="products.cgi" method="post" enctype="multipart/form-data">
         <table>
           <tr>
-            <th>Product ID</th> <th>Product name</th> <th>Price</th> <th>Action</th> 
+            <th>Product ID</th> <th>Product name</th> <th>Price</th> <th>Action</th>
           </tr>
           <tr>
             <td> <input readonly="readonly" name="1.pid" value="H412"> </td>
@@ -7678,7 +7706,7 @@ You cannot submit this form when the field is incorrect.</samp></pre>
                 <optgroup label="8.01 Physics I: Classical Mechanics">
                   <option value="8.01.1">Lecture 01: Powers of Ten</option>
                   <option value="8.01.2">Lecture 02: 1D Kinematics</option>
-                  <option value="8.01.3">Lecture 03: Vectors</option> 
+                  <option value="8.01.3">Lecture 03: Vectors</option>
                 </optgroup>
 
                 <optgroup label="8.02 Electricity and Magnestism">

diff --git a/sections/semantics-grouping-content.include b/sections/semantics-grouping-content.include
@@ -1,5 +1,18 @@
 <section>
 
+<!--
+
+    Grouping Content
+
+  This source produces section 4.4: Grouping Content
+  https://w3c.github.io/html/grouping-content.html
+
+  It covers:
+  The p, address, hr, pre, blockquote, ol, ul, li,
+  dl, dt, dd, figure, figcaption, main, and div elements
+
+-->
+
 <h3 id="grouping-content">Grouping content</h3>
 
 <h4 id="the-p-element">The <dfn element><code>p</code></dfn> element</h4>

diff --git a/sections/semantics-interactive-elements.include b/sections/semantics-interactive-elements.include
@@ -1,5 +1,21 @@
 <section>
 
+<!--
+
+    Interactive elements
+
+  This source produces section 4.11: Interactive elements
+  https://w3c.github.io/html/interactive-elements.html
+
+  It covers:
+  - Details and summary elements
+  - Commands
+    + facets of commands
+    + defining commands with a, button, input, option, and accesskeys
+  - Dialog element
+
+-->
+
 <h3 id="interactive-elements">Interactive elements</h3>
 
 <h4 id="the-details-element">The <dfn element><code>details</code></dfn> element</h4>
@@ -107,7 +123,7 @@
   <div class="example">
     The following example shows the <{details}> element being used to hide technical
     details in a progress report.
-    
+
     <section class="progress window">
       <strong>Copying "Really Achieving Your Childhood Dreams"</strong>
       <details>

diff --git a/sections/semantics-root.include b/sections/semantics-root.include
@@ -1,5 +1,19 @@
 <section>
 
+<!--
+
+    Semantics: Root
+
+  This source produces section 4.1: The document Element
+  https://w3c.github.io/html/semantics.html#the-root-element
+
+  It covers:
+  - HTML element
+  - The manifest attribute, and its pending removal
+  - Note about keeping HTML attributes at a minimum to allow proper char encoding within 1024 bytes
+
+-->
+
 <h3 id="the-root-element">The document element</h3>
 
 <h4 id="the-html-element">The <dfn element><code>html</code></dfn> element</h4>

diff --git a/sections/semantics-scriptings.include b/sections/semantics-scriptings.include
@@ -1,5 +1,21 @@
 <section>
 
+<!--
+
+    Scripting
+
+  This source produces section 4.12: Scripting
+  https://w3c.github.io/html/semantics-scripting.html
+
+  It covers:
+  - Introduction to scripts and the following elements
+  - script
+  - noscript
+  - template
+  - canvas
+
+-->
+
 <h3 id="semantics-scripting">Scripting</h3>
 
   Scripts allow authors to add interactivity to their documents.

diff --git a/sections/semantics-sections.include b/sections/semantics-sections.include
@@ -2,20 +2,22 @@
 
 <!--
 
-  SECTIONS
+    Sections
 
-  This source produces section 4.3 Sections:
+  This source produces section 4.3: Sections
   https://w3c.github.io/html/sections.html
 
-It covers
-- elements used to create the sectioning root, content sections within the document outline, and headings:
-    body, article, section, nav, aside, h1-h6, header, footer
-- headings and sections and creating an outline
-- summary of usage for the above mentioned elements
+  It covers:
+  - elements used to create the sectioning root, content sections within the document outline,
+    and headings:
+      body, article, section, nav, aside, h1-h6, header, footer
+  - headings and sections and creating an outline
+  - summary of usage for the above mentioned elements
 
 -->
 
 <h3 id="sections">Sections</h3>
+
 <h4 id="the-body-element">The <dfn element><code>body</code></dfn> element</h4>
 
   <dl class="element">