Apply to the Library Fundamentals TS Working Paper the Proposed Wording from N3916, "Polymorphic Memory Resources"

This includes a big update to the html-doc-framework to support the changes.

Author: jyasskin

Diff for: PooledResourcesImage.png

@@ -12,11 +12,11 @@
   "dependencies": {
     "polymer-ajax": "Polymer/polymer-ajax#0.2.0"
   },
-  "_release": "7a8c0684ad",
+  "_release": "23c55aa6ee",
   "_resolution": {
     "type": "branch",
     "branch": "master",
-    "commit": "7a8c0684ad9796ff5da2b83f89cdc8379dcb12fa"
+    "commit": "23c55aa6eec38c9796de104237bbf809cad95080"
   },
   "_source": "git://github.com/cplusplus/html-doc-framework.git",
   "_target": "*",

Diff for: bower_components/cxx-html-doc-framework/.bower.json

@@ -19,6 +19,20 @@ Contributor License Agreement at https://developers.google.com/open-source/cla/i
 Custom C++-specific elements
 ----------------------------
 
+Some of these elements define a `checkInvariants()` method, so you can run:
+
+    document.querySelectorAll('*').array().forEach(
+        function(node){ if (node.checkInvariants) node.checkInvariants(); });
+
+to see if you've gotten anything wrong.
+
+### `<cxx-include href="other.html">`
+
+This one isn't really C++-specific: it allows partitioning a main document
+into multiple pieces. `other.html`'s body will be copied in place of the
+`<cxx-include>` element.
+
+
 ### `<cxx-clause>` and `<cxx-section>`
 
 These automatically number clauses and sections, fill in

Diff for: bower_components/cxx-html-doc-framework/README.md

@@ -16,18 +16,21 @@
 <polymer-element name="cxx-clause" extends="cxx-section">
   <script>
     (function() {
-      var clause_num = 1;
+      function updateTocClauses() {
+        this.super();
+        var toc = document.querySelector('cxx-toc');
+        if (toc) {
+          toc.clauses = document.querySelectorAll('cxx-clause');
+        }
+      }
       Polymer('cxx-clause', {
-        attached: function() {
-          this.super();
-          var my_clause_num = clause_num++;
-
-          this.async(function() {
-            // async() lets the descendant elements upgrade; after which we
-            // need to traverse them to collect section numbers.
-            this.update_sec_nums(my_clause_num);
-          });
+        // Convenience function at the clause level, which gets called from <cxx-toc>.
+        set_clause_num: function(clause_num) {
+          this.update_sec_nums(clause_num);
         },
+
+        attached: updateTocClauses,
+        detached: updateTocClauses,
       });
     })();
   </script>

Diff for: bower_components/cxx-html-doc-framework/clause.html

@@ -0,0 +1,47 @@
+<!-- Copyright 2014 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<!--
+    Uses the HTML <figure> content model, but automatically adds a number to
+    the <figcaption>.
+-->
+<polymer-element name="cxx-figure" constructor="CxxFigureElement">
+  <template>
+    <style>
+      :host { margin-left: auto; margin-right: auto; }
+      figcaption { white-space: nowrap; text-align: center; }
+      /* @polyfill figcaption figcaption */
+      ::content figcaption { display: inline; }
+
+    </style>
+    <figure>
+      <figcaption>Figure {{figure_num}} — <wbr><content select="figcaption"></content></figcaption>
+      <content></content>
+    </figure>
+  </template>
+  <script>
+    (function() {
+      function renumberFigures() {
+        document.querySelectorAll('cxx-figure').array().forEach(function(figure, index) {
+          figure.figure_num = index + 1;
+        });
+      }
+      Polymer('cxx-figure', {
+        attached: renumberFigures,
+        detached: renumberFigures,
+      });
+    })();
+  </script>
+</polymer-element>

Diff for: bower_components/cxx-html-doc-framework/figure.html

@@ -22,11 +22,13 @@
 <link rel="import" href="section.html"/>
 <link rel="import" href="clause.html"/>
 <link rel="import" href="table.html"/>
+<link rel="import" href="figure.html"/>
 <link rel="import" href="definition-section.html"/>
 <link rel="import" href="toc.html"/>
 <link rel="import" href="ref.html"/>
 <link rel="import" href="foreign-index.html"/>
 <link rel="import" href="titlepage.html"/>
+<script src="include.js"></script>
 <link rel="import" href="email.html"/>
 <link rel="import" href="ednote.html"/>
 <link rel="import" href="note.html"/>

Diff for: bower_components/cxx-html-doc-framework/framework.html

@@ -62,6 +62,14 @@
     });
   </script>
 </polymer-element>
+<polymer-element name="cxx-preconditions" extends="cxx-attribute">
+  <!-- This extension was introduced by N3916. -->
+  <script>
+    Polymer('cxx-preconditions', {
+      heading: 'Preconditions',
+    });
+  </script>
+</polymer-element>
 <polymer-element name="cxx-effects" extends="cxx-attribute">
   <script>
     Polymer('cxx-effects', {

Diff for: bower_components/cxx-html-doc-framework/function.html

@@ -0,0 +1,43 @@
+/* Copyright 2014 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/* The <cxx-include href> element replaces itself with the contents at
+ * 'href'. It doesn't use a shadow root so that the other document
+ * acts exactly as part of the current document. */
+
+(function() {
+    "use strict";
+    var includeProto = Object.create(HTMLElement.prototype);
+    includeProto.attachedCallback = function() {
+        this.link = document.createElement('link');
+        this.link.setAttribute('rel', 'import');
+        this.link.setAttribute('href', this.getAttribute('href'));
+        this.link.onload = this.loaded.bind(this);
+        this.link.onerror = function(e) {
+            console.error(e);
+        }
+        document.head.appendChild(this.link);
+    };
+    includeProto.loaded = function(e) {
+        var imported = this.link.import;
+        this.link.parentNode.removeChild(this.link);
+        var parent = this.parentNode;
+        for (var elem = imported.body.firstChild; elem; elem = elem.nextSibling) {
+            parent.insertBefore(elem.cloneNode(true), this);
+        }
+        parent.removeChild(this);
+    };
+    document.registerElement('cxx-include', {prototype: includeProto});
+})();

Diff for: bower_components/cxx-html-doc-framework/include.js

@@ -60,7 +60,24 @@ limitations under the License.
         });
     }
 
+    function inlineImages(images) {
+        Array.prototype.forEach.call(images,
+            function(image) {
+                if (image.naturalWidth == 0)
+                    console.error(image, "hasn't loaded yet.");
+                var canvas = document.createElement('canvas');
+                canvas.width = image.naturalWidth;
+                canvas.height = image.naturalHeight;
+                canvas.getContext('2d').drawImage(image, 0, 0, canvas.width, canvas.height);
+                image.src = canvas.toDataURL();
+            });
+    }
+
     function cloneStaticAndInline(doc) {
+        // Inline the images on the source document instead of the copy
+        // because the copy doesn't have time to load the images.
+        inlineImages(doc.getElementsByTagName('img'));
+
         var copy = doc.cloneNode(true);
         function removeAll(nodes) {
             forEach(nodes, function(node) {

Diff for: bower_components/cxx-html-doc-framework/publish.js

@@ -13,6 +13,8 @@
 limitations under the License.
 -->
 
+<link rel="import" href="util/get-element-by-id.html"/>
+
 <!--
     The 'to' attribute is the id of a <cxx-section> or <cxx-table> element (or subclass).
 
@@ -27,13 +29,16 @@
 
 <polymer-element name="cxx-ref" attributes="to insynopsis in">
   <template
+      ><cxx-get-element-by-id elemId="{{in}}" elem="{{inElem}}"></cxx-get-element-by-id
+      ><template if="{{!in}}"><cxx-get-element-by-id elemId="{{to}}" elem="{{toElem}}"></cxx-get-element-by-id></template
       ><template id="target_num"
-                 ><template if="{{in_elem.index}}">{{in_elem.name}} &#xa7;{{in_elem.index[to]}}</template
-                 ><template if="{{!in}}"><a href="#{{to}}"
-                   ><template if="{{to_elem.sec_num}}">{{to_elem.sec_num}}</template
-                   ><template if="{{to_elem.table_num}}">Table {{to_elem.table_num}}</template></a></template
+                 ><template if="{{inElem.index}}">{{inElem.name}} <span title="{{to}}">&#xa7;{{inElem.index[to]}}</span></template
+                 ><template if="{{!in}}"><a title="{{to}}" href="#{{to}}"
+                   ><template if="{{toElem.sec_num}}">{{toElem.sec_num}}</template
+                   ><template if="{{toElem.table_num}}">Table {{toElem.table_num}}</template
+                   ><template if="{{toElem.figure_num}}">Figure {{toElem.figure_num}}</template></a></template
       ></template
-      ><template if="{{insynopsis}}">// <i><template bind="" ref="target_num"></template>, {{to_elem.title_element.textContent}}</i></template
+      ><template if="{{insynopsis}}">// <i><template bind="" ref="target_num"></template>, {{toElem.title_element.textContent}}</i></template
       ><template if="{{!insynopsis}}"><template bind="" ref="target_num"></template></template
   ></template>
   <script src="ref.js"></script>

Diff for: bower_components/cxx-html-doc-framework/ref.html

@@ -19,42 +19,53 @@ limitations under the License.
         insynopsis: false,
 
         observe: {
-            'in_elem.index': 'indexChanged'
+            'inElem.index': 'indexChanged'
         },
         applyAuthorStyles: true,
 
-        inChanged: function() {
-            this.in_elem = document.getElementById(this.in);
-            if (this.in &&
-                !(this.in_elem &&
-                  this.in_elem.tagName.toUpperCase() == 'CXX-FOREIGN-INDEX')) {
+        checkInvariants: function() {
+            if (this.in) {
+                if (!this.inElem) {
+                    console.error(this, '.in (', this.in,
+                                  ') must refer to a <cxx-foreign-index> element.');
+                }
+            } else {
+                if (!this.to) {
+                    console.error('<cxx-ref>', this,
+                                  'must have an `in` or `to` attribute.');
+                } else if (!this.toElem) {
+                    console.error(this, '.to (', this.to,
+                                  ') must refer to the ID of another element.');
+                }
+            }
+        },
+
+        inElemChanged: function() {
+            if (this.inElem &&
+                this.inElem.tagName.toUpperCase() != 'CXX-FOREIGN-INDEX') {
                 console.error('<cxx-ref>.in (', this.in,
                               ') must be a <cxx-foreign-index>; was',
-                              this.in_elem);
+                              this.inElem);
             }
         },
-        toChanged: function() {
-            if (!this.in) {
-                this.to_elem = document.getElementById(this.to);
-                if (!this.to_elem) {
-                    console.error("Broken link", this.to, "from", this);
-                    return;
-                }
+        toElemChanged: function() {
+            if (this.toElem) {
                 this.async(function() {
-                    // Async makes sure the to_elem is upgraded.
-                    if (!(this.to_elem instanceof CxxSectionElement ||
-                          this.to_elem instanceof CxxTableElement)) {
+                    // Async makes sure the toElem is upgraded.
+                    if (!(this.toElem instanceof CxxSectionElement ||
+                          this.toElem instanceof CxxTableElement ||
+                          this.toElem instanceof CxxFigureElement)) {
                         console.error("Reference from", this,
-                                      "refers to non-section, non-table element",
-                                      this.to_elem);
+                                      "refers to non-section, non-table, non-figure element",
+                                      this.toElem);
                     }
                 });
             }
         },
 
         indexChanged: function() {
-            if (!(this.to in this.in_elem.index)) {
-                console.error(this.to, 'not found in', this.in_elem);
+            if (!(this.to in this.inElem.index)) {
+                console.error(this.to, 'not found in', this.inElem);
             }
         }
     });

Diff for: bower_components/cxx-html-doc-framework/ref.js

@@ -20,6 +20,12 @@ limitations under the License.
 
         applyAuthorStyles: true,
 
+        checkInvariants: function() {
+            if (!this.id) {
+                console.error(this, 'is missing an id.');
+            }
+        },
+
         update_sec_nums: function(sec_num) {
             this.sec_num = sec_num + '';
             var child_index = 1;

Diff for: bower_components/cxx-html-doc-framework/section.js

@@ -40,11 +40,14 @@
   </template>
   <script>
     (function() {
-      var next_table_num = 1;
+      function renumberTables() {
+        document.querySelectorAll('[is=cxx-table]').array().forEach(function(table, index) {
+          table.table_num = index + 1;
+        });
+      }
       Polymer('cxx-table', {
-        created: function() {
-          this.table_num = next_table_num++;
-        }
+        attached: renumberTables,
+        detached: renumberTables,
       });
     })();
   </script>

Diff for: bower_components/cxx-html-doc-framework/table.html

@@ -15,10 +15,12 @@ limitations under the License.
 
 (function() {
     Polymer('cxx-toc', {
-        // Hierarchy :: [{ elem: Element, sections: Hierarchy }]
+        // Hierarchy :: [{ elem: Element, title: H1, sections: Hierarchy }]
         sections: [],
 
-        applyAuthorStyles: true,
+        // Updated with the list of <cxx-clause> elements in the document each
+        // time such an element is attached or detached.
+        clauses: [],
 
         collectSections: function(root) {
             var sections = [];
@@ -33,9 +35,15 @@ limitations under the License.
                     sections: sections};
         },
 
-        created: function() {
-            var clauses = window.document.querySelectorAll('cxx-clause');
-            this.sections = clauses.array().map(this.collectSections, this);
+        clausesChanged: function() {
+            this.sections = this.clauses.array().map(function(clause, index) {
+                clause.set_clause_num(index + 1);
+                return this.collectSections(clause);
+            }, this);
+        },
+
+        attached: function() {
+            this.clauses = document.querySelectorAll('cxx-clause');
         }
     })
 })();