Merge pull request itanium-cxx-abi#36 from zygoloid/period-suffix

Update name mangling description to explicitly condone the practice o…

Author: rjmccall

abi.html

@@ -4052,8 +4052,9 @@ <h4><a href="#mangling-general"> 5.1.1 General </a></h4>
 or <code>Type?</code> for an unknown data type.
 
 <p>
-Grammar productions beginning with '$' are reserved for private implementation
-use.  Names produced using such extensions are inherently non-portable.
+Mangled names containing '<tt>$</tt>' or '<tt>.</tt>' are reserved for
+private implementation use. Names produced using such extensions are
+inherently non-portable and should be given internal linkage where possible.
 
 <p>
 <a name="mangling-structure">
@@ -4064,6 +4065,7 @@ <h4><a href="#mangling-structure"> 5.1.2 General Structure </a></h4>
 Mangled names have the general structure:
 <pre><font color=blue><code>
     &lt;<a name="mangle.mangled-name">mangled-name</a>&gt; ::= _Z &lt;<a href="#mangle.encoding">encoding</a>&gt;
+                   ::= _Z &lt;<a href="#mangle.encoding">encoding</a>&gt; . &lt;vendor-specific suffix&gt;
     &lt;<a name="mangle.encoding">encoding</a>&gt; ::= &lt;<i>function</i> <a href="#mangle.name">name</a>&gt; &lt;<a href="#mangle.bare-function-type">bare-function-type</a>&gt;
 	       ::= &lt;<i>data</i> <a href="#mangle.name">name</a>&gt;
 	       ::= &lt;<a href="#mangle.special-name">special-name</a>&gt;
@@ -4081,6 +4083,13 @@ <h4><a href="#mangling-structure"> 5.1.2 General Structure </a></h4>
 parameters).
 The type is omitted for variables and static data members.
 
+<p>
+A <code>&lt;<a href="#mangle.mangled-name">mangled-name</a>&gt;</code>
+containing a period represents a vendor-specific version or portion
+of the entity named by the <code>&lt;<a href="#mangle.encoding">encoding</a>&gt;</code>
+prior to the first period. There is no restriction on the characters
+that may be used in the suffix following the period.
+
 <a name="mangle.anonymous">
 <h5><a href="#mangling.anonymous">Anonymous entities</a></h5>
 
@@ -5167,7 +5176,7 @@ <h4><a href="#expressions">5.1.6 Expressions</a></h4>
                  ::= L &lt;<i>nullptr</i> <a href="#mangle.type">type</a>&gt; E                                 # nullptr literal (i.e., "LDnE")
                  ::= L &lt;<i>pointer</i> <a href="#mangle.type">type</a>&gt; 0 E                               # null pointer template argument
 		 ::= L &lt;<a href="#mangle.type">type</a>&gt; &lt;<i>real-part</i> <a href="#mangle.float">float</a>&gt; _ &lt;<i>imag-part</i> <a href="#mangle.float">float</a>&gt; E   # complex floating point literal (C 2000)
-                 ::= L &lt;<a href="#mangle.mangled-name">mangled-name</a>&gt; E                                 # external name
+                 ::= L _Z &lt;<a href="#mangle.encoding">encoding</a>&gt; E                                  # external name
 
   &lt;<a name="mangle.braced-expression">braced-expression</a>&gt; ::= &lt;<a href="#mangle.expression">expression</a>&gt;
                       ::= di &lt;<i>field</i> <a href="#mangle.source-name">source-name</a>&gt; &lt;<a href="#mangle.braced-expression">braced-expression</a>&gt;    # .name = expr
@@ -5253,7 +5262,7 @@ <h5><a href="#mangling.declaration-reference">5.1.6.2 References to declared ent
 <p>
 When encoding template signatures, a name appearing in the source code
 cannot always be resolved to a specific entity: In such cases the
-<code>&lt;<a href="#mangle.mangled-name">mangled-name</a>&gt;</code> production (via 
+<code>&lt;<a href="#mangle.encoding">encoding</a>&gt;</code> production (via
 <code>&lt;<a href="#mangle.expr-primary">expr-primary</a>&gt;</code>) does not apply, and instead the
 <code>&lt;<a href="#mangle.unresolved-name">unresolved-name</a>&gt;</code> encoding is used.  For example:
 <code><pre>