From 3a93fc1eaddbdc990429c3cfb8f2babe29a5d1ab Mon Sep 17 00:00:00 2001
From: chaals <chaals@yandex-team.ru>
Date: Sat, 10 Feb 2018 10:47:53 +0100
Subject: [PATCH 1/2] Update comments in some source files

This covers some of list in #1201
---
 sections/browsers.include                    |  8 +++++++
 sections/dom.include                         | 25 +++++++++++++-------
 sections/editing.include                     |  8 ++++---
 sections/iana.include                        |  9 -------
 sections/infrastructure.include              | 14 ++++++++++-
 sections/obsolete.include                    | 22 ++++++++++-------
 sections/rendering.include                   |  3 +--
 sections/semantics-common-idioms.include     | 16 +++++++++++++
 sections/semantics-document-metadata.include | 16 +++++++++++++
 9 files changed, 90 insertions(+), 31 deletions(-)

diff --git a/sections/browsers.include b/sections/browsers.include
index b13dbf5f18..fa908b08d1 100644
--- 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
index b69bf016dc..1b0069d188 100644
--- a/sections/dom.include
+++ b/sections/dom.include
@@ -1,14 +1,23 @@
 <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
index 162196f38b..6bb57cd3ec 100644
--- 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
index ece3a504e7..fd0b33f926 100644
--- 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
index 7c83912942..17b8c166ea 100644
--- 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
index 5f70ca0d7a..df1836b9e7 100644
--- 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
index 2b8cf67503..743e01586c 100644
--- 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
index e8216a09b9..139c0b80e4 100644
--- 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
index 61a22653a3..ef2967df3a 100644
--- 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>
 

From 4bef6b255bee7c74518efbf47d1e1266dd987f9f Mon Sep 17 00:00:00 2001
From: Scott O'Hara <scottaohara@gmail.com>
Date: Sat, 10 Feb 2018 09:00:43 -0500
Subject: [PATCH 2/2] fix typo in dom.include

---
 sections/dom.include | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/sections/dom.include b/sections/dom.include
index 1b0069d188..a1b5b97c22 100644
--- a/sections/dom.include
+++ b/sections/dom.include
@@ -14,8 +14,7 @@ It covers
 - Global attributes
 - .innerText
 - Some requirements for the Bidi algorithm
-- SOme requirements for the role and aria-* attributes
-
+- Some requirements for the role and aria-* attributes
 
 -->