Update comments in some source files (#1203)

* Update comments in some source files This covers some of list in #1201 * fix typo in dom.include
w3c · Feb 15, 2018 · 1d0adc9 · 1d0adc9
1 parent a8fb012
commit 1d0adc9
Show file tree

Hide file tree

Showing 9 changed files with 89 additions and 31 deletions.
diff --git a/sections/browsers.include b/sections/browsers.include
@@ -2,6 +2,14 @@
 <!--
 
              BROWSERS
+
+This source produces chapter 6: https://w3c.github.io/html/browsers.html
+
+It covers Window and WindowProxy objects, 
+concepts including Origin, Browsing Context, Navigating between pages
+  (and when it is allowed), the effect of sandboxing on navigating, and the like.
+
+@chaals is trying to maintain it.            
 
 -->
 

diff --git a/sections/dom.include b/sections/dom.include
@@ -1,14 +1,22 @@
 <section>
 <!--
-████████   ███████  ██     ██
-██     ██ ██     ██ ███   ███
-██     ██ ██     ██ ████ ████
-██     ██ ██     ██ ██ ███ ██
-██     ██ ██     ██ ██     ██
-██     ██ ██     ██ ██     ██
-████████   ███████  ██     ██
+       DOM
+
+This source produces chapter 3: "Semantics, structure, and APIs of HTML documents"
+  https://w3c.github.io/html/dom.html
+
+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
+- How elements and attributes are described in the spec
+- Content models - used in element descriptions
+- Global attributes
+- .innerText
+- Some requirements for the Bidi algorithm
+- Some requirements for the role and aria-* attributes
+
 -->
-<!-- This section ostensibly kept up to date by travil@microsoft.com -->
 
 <h2 id="dom">Semantics, structure, and APIs of HTML documents</h2>
 

diff --git a/sections/editing.include b/sections/editing.include
@@ -1,11 +1,13 @@
 <section>
 <!--
 
-Editing:
+     EDITING
+
+This source produces Chapter 5: "User Interaction" https://w3c.github.io/html/editing.html
 - "hidden" attribute
 - focus and focus changes
-- accesskey and user shortcuts
-- "contenteditable" (being redefined by the editing Task Force) and "designmode"
+- "accesskey" and user shortcuts
+- "contenteditable" (which is currently being redefined by the editing Task Force) and "designmode"
 - drag and drop
 
 -->

diff --git a/sections/iana.include b/sections/iana.include
@@ -1,13 +1,4 @@
 <section>
-<!--
-████    ███    ██    ██    ███
- ██    ██ ██   ███   ██   ██ ██
- ██   ██   ██  ████  ██  ██   ██
- ██  ██     ██ ██ ██ ██ ██     ██
- ██  █████████ ██  ████ █████████
- ██  ██     ██ ██   ███ ██     ██
-████ ██     ██ ██    ██ ██     ██
--->
 <h2 id="iana">IANA considerations</h2>
 
 <h3 id="text-html"><code>text/html</code></h3>

diff --git a/sections/infrastructure.include b/sections/infrastructure.include
@@ -1,7 +1,19 @@
 <section>
 <!--
 
-INFRASTRUCTURE
+         INFRASTRUCTURE
+
+This section produces chapter 2: Common Infrastructure https://w3c.github.io/html/infrastructure.html
+
+It covers
+- Terminology
+- How Conformance Requirements are described
+- Case sensitivity and comparing strings
+- Common "micro" syntaxes
+- URLs and Fetching resources, including referrer and nonce attributes
+- Reflection of attributes
+- DOM collections
+- De/serialising to pass structured objects
 
 -->
 

diff --git a/sections/obsolete.include b/sections/obsolete.include
@@ -1,14 +1,20 @@
 <section>
 <!--
- ███████  ████████   ██████   ███████  ██       ████████ ████████ ████████
-██     ██ ██     ██ ██    ██ ██     ██ ██       ██          ██    ██
-██     ██ ██     ██ ██       ██     ██ ██       ██          ██    ██
-██     ██ ████████   ██████  ██     ██ ██       ██████      ██    ██████
-██     ██ ██     ██       ██ ██     ██ ██       ██          ██    ██
-██     ██ ██     ██ ██    ██ ██     ██ ██       ██          ██    ██
- ███████  ████████   ██████   ███████  ████████ ████████    ██    ████████
+
+        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 legacty content using them.
+  Examples include
+  - appcache
+  - applet
+  - keygen
+  - marquee
+  - Plugins
+
 -->
-<!-- This section ostensibly kept up to date by arronei@microsoft.com -->
 
 <h2 id="obsolete">Obsolete features</h2>
 

diff --git a/sections/rendering.include b/sections/rendering.include
@@ -1,10 +1,9 @@
 <section>
 <!--
 
-RENDERING
+        RENDERING
 
 -->
-<!-- This section ostensibly kept up to date by **TBD** -->
 
 Rendering {#rendering}
 =========

diff --git a/sections/semantics-common-idioms.include b/sections/semantics-common-idioms.include
@@ -1,4 +1,20 @@
 <section>
+<!--
+
+         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
+- Subheadings and taglines
+- "breadcrumb" navigation information
+- Tag Clouds
+- Conversations
+- Footnotes
+
+-->
+
 
 <h3 id="common-idioms-without-dedicated-elements">Common idioms without dedicated elements</h3>
 

diff --git a/sections/semantics-document-metadata.include b/sections/semantics-document-metadata.include
@@ -1,4 +1,20 @@
 <section>
+<!--
+
+        DOCUMENT METADATA
+
+This source produces section 4.2: Document Metadata https://w3c.github.io/html/document-metadata.html
+
+It covers elements in the head of the document:
+- head
+- title
+- base
+- meta
+- link
+- style
+
+-->
+
 
 <h3 id="document-metadata">Document metadata</h3>