Make updates for comments received so far, including issue #4 and

issue #5.  XL bug report support for Linux is still pending.

Intrinsics_Reference/bk_main.xml

@@ -32,7 +32,7 @@
   xml:id="bk_main">
 
     <!-- TODO: Pick a Title for the new document -->
-    <title>POWER Vector Intrinsic Programming Reference</title>
+    <title>Power Vector Intrinsic Programming Reference</title>
     <!-- TODO: Either add a subtitle or remove the following line -->
     <!-- subtitle></subtitle -->
 

Intrinsics_Reference/ch_biendian.xml

@@ -110,6 +110,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="VIPR.biendian">
     </para>
     <programlisting>vector int x = (vector int) (4, -1, 3, 6);
 vector double g = (vector double) { 3.5, -24.6 };</programlisting>
+    <para>
+      Current C comiplers do not support literals for
+      <code>__int128</code> types.  When constructing a <code>vector
+      __int128</code> constant from smaller literals such as
+      <code>int</code> or <code>long long</code>, you must test for
+      endianness and reverse the order of the smaller literals for
+      little-endian mode.
+    </para>
   </section>
 
   <section xml:id="VIPR.ch-data-types">
@@ -584,6 +592,18 @@ register vector double vd = vec_splats(*double_ptr);</programlisting>
         </tbody>
       </tgroup>
     </informaltable>
+    <note>
+      <para>
+	Note that each element in a vector has the same representation
+	in both big- and little-endian element orders.  That is, an
+	<code>int</code> is always 32 bits, with the sign bit in the
+	high-order position.  Programmers must be aware of this when
+	programming with mixed data types, such as an instruction that
+	multiplies two <code>short</code> elements to produce an
+	<code>int</code> element.  Always access entire elements to
+	avoid potential endianness issues.
+      </para>
+    </note>
   </section>
 
   <section>
@@ -1174,7 +1194,9 @@ register vector double vd = vec_splats(*double_ptr);</programlisting>
 	reorder entire elements of a vector.  If you must use vec_perm
 	for another purpose, your code must include a test for
 	endianness and separate algorithms for big- and
-	little-endian.
+	little-endian.  Examples of this may be seen in the Power
+	Vector Library project (see <xref linkend="VIPR.intro.links"
+	/>).
       </para>
     </section>
   </section>

Intrinsics_Reference/ch_intro.xml

@@ -79,16 +79,23 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_intro">
       linkend="VIPR.intro.unified" />).  The VSRs can represent all
       the data types representable by the VRs, and can also be treated
       as containing two 64-bit integers or two 64-bit double-precision
-      floating-point values.  
+      floating-point values.  However, ISA support for two 64-bit
+      integers in VSRs was limited until Version 2.07 (POWER8) of the
+      Power ISA, and only the VRs are supported for these
+      instructions.
     </para>
     <para>
       Both the VMX and VSX instruction sets have been expanded for the
       POWER8 and POWER9 processor families.  Starting with POWER8,
       a VSR can now contain a single 128-bit integer; and starting
       with POWER9, a VSR can contain a single 128-bit floating-point
-      value.  The VMX and VSX instruction sets together may be
-      referred to as the Power SIMD (single-instruction,
-      multiple-data) instructions.
+      value.  Again, the ISA currently only supports 128-bit
+      operations on values in the VRs.
+    </para>
+    <para>
+      The VMX and VSX instruction sets together may be referred to as
+      the Power SIMD (single-instruction, multiple-data)
+      instructions.
     </para>
     <section>
       <title>Little-Endian Linux</title>
@@ -162,6 +169,50 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_intro">
     </figure>
   </section>
 
+  <section xml:id="VIPR.intro.reporting">
+    <title>Where to Report Bugs</title>
+    <para>
+      This reference provides guidance on using vector intrinsics that
+      are supported by all compatible compilers.  If you find a
+      problem when using one of the intrinsics with a compatible
+      compiler, please report a bug!  Bug reporting procedures differ
+      depending on which compiler you're using.
+    </para>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <emphasis role="underline">GCC</emphasis>.  The reporting
+	  procedure for bugs against the GNU Compiler Collection is
+	  described at <link
+	  xlink:href="https://gcc.gnu.org/bugs/">https://gcc.gnu.org/bugs/</link>.
+	  The GCC bugzilla tracker is located at <link
+	  xlink:href="https://gcc.gnu.org/bugzilla/">https://gcc.gnu.org/bugzilla/</link>.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <emphasis role="underline">Clang/LLVM</emphasis>.  The
+	  reporting procedure for bugs against the Clang compiler is
+	  described at <link
+	  xlink:href="https://llvm.org/docs/HowToSubmitABug.html">https://llvm.org/docs/HowToSubmitABug.html</link>.
+	  The LLVM bug tracking system is located at <link
+	  xlink:href="https://bugs.llvm.org/enter_bug.cgi">https://bugs.llvm.org/enter_bug.cgi</link>.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <emphasis role="underline">The XL compilers</emphasis>.
+	</para>
+	<note>
+	  <para>
+	    Reporting procedures for XL bugs on Linux are yet to be
+	    determined.
+	  </para>
+	</note>
+      </listitem>
+    </itemizedlist>
+  </section>
+
   <section xml:id="VIPR.intro.links">
     <title>Useful Links</title>
     <para>

Intrinsics_Reference/ch_techniques.xml

@@ -148,12 +148,19 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_techniques">
       described here, you should look for an equivalent one in this
       manual and change your code to use that.
     </para>
+    <para>
+      Where an intrinsic may not be available from all compilers or at
+      all ISA levels, this information is called out in the
+      description of the intrinsic in <xref
+      linkend="VIPR.reference.vecfns" >.
+    </para>
     <para>
       There are also other vector APIs that may be of use to you (see
       <xref linkend="VIPR.techniques.apis" />).  In particular, the
       Power Vector Library (see <xref
       linkend="VIPR.techniques.pveclib" />) provides additional
-      portability across compiler versions.
+      portability across compiler versions, as well as interfaces that
+      hide cases where assembly language is needed.
     </para>
   </section>
 

Intrinsics_Reference/ch_vec_reference.xml

@@ -123,7 +123,10 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="VIPR.vec-ref">
 	<para>
 	  <emphasis role="bold">ISA 3.0 or later</emphasis>.  This
 	  form is only available starting with PowerISA 3.0,
-	  corresponding to POWER9 servers.
+	  corresponding to POWER9 servers.  The Power Vector Library
+	  (see <xref linkend="VIPR.intro.links" /> provides equivalent
+	  POWER7/POWER8 implementations for many ISA 3.0 vector
+	  instructions, which may be preferred for portability.
 	</para>
       </listitem>
       <listitem>
@@ -150,7 +153,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="VIPR.vec-ref">
   </section>
 
   <?hard-pagebreak?>
-  <section>
+  <section xml:id="VIPR.reference.vecfns">
     <title>Built-In Vector Functions</title>
 
     <simplesect xml:id="vec_abs">