Updated to 1.8.0 to add permalinks and jump menu to api-ref page

bug: #980228
bug: #1039163

Change-Id: I6a6d14c06ac1873303a5b6892d0923d36ff02a4b
author: Diane Fleming

api-ref/pom.xml

@@ -10,7 +10,7 @@
   <name>OpenStack API Page Project</name>
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <doctools.version>1.7.2</doctools.version>
+    <doctools.version>1.8.0</doctools.version>
   </properties>
   <build>
     <plugins>

api-ref/src/docbkx/api-ref.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book[
+<!-- Some useful entities borrowed from HTML -->
+<!ENTITY ndash  "&#x2013;">
+<!ENTITY mdash  "&#x2014;">
+<!ENTITY hellip "&#x2026;">
+<!ENTITY plusmn "&#xB1;">
+<!ENTITY nbsp "&#160;">
 <!-- Useful for describing APIs -->
 <!ENTITY GET    '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
 <!ENTITY PUT    '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
@@ -25,19 +31,25 @@
   <preface xml:id="Overview">
     <title>OpenStack API Reference</title>
     <para>Use the following OpenStack APIs in your OpenStack cloud:
-      Identity Service, Compute, Compute extensions, Image Service,
-      Block Storage Service, and Object Storage. You must install the packages
+      <link xlink:href="#identity">Identity Service API v2.0</link>, 
+      <link xlink:href="#compute">Compute API v2</link>, 
+      <link xlink:href="#compute-ext">Compute API v2 extensions</link>, 
+      <link xlink:href="#os-images-1.0">Image Service API v1</link>,
+      <link xlink:href="#volumes-api">Block Storage Service API v2</link>, and 
+      <link xlink:href="#os-object-api-1.0">Object Storage API v1</link>. 
+      You must install the packages
       for each API separately. After you authenticate through the
-      Identity service API, you can use the other APIs and extensions
+      Identity Service API, you can use the other APIs and extensions
       to launch server instances, create images, assign metadata to
       instances and images, create containers and objects, and
       complete other actions in your OpenStack cloud. </para>
     <para>To get started with the APIs, see the <link
         xlink:href="http://docs.openstack.org/api/quick-start/content/"
-          ><citetitle>OpenStack API Quick Start</citetitle></link>.
+          >OpenStack API Quick Start</link>.
       For detailed information, <link
         xlink:href="http://docs.openstack.org/api/api-specs.html">read
-        descriptions or specifications</link> for each API. </para>
+        the specifications</link> for each API. </para>
+    <para>&nbsp;</para>
   </preface>
   <chapter xml:id="identity" xlink:href="#identity">
     <title>Identity Service API v2.0</title>
@@ -79,7 +91,7 @@
         xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
     <section xml:id="ext-os-agents">
-      <title>Agents</title>
+      <title>Guest Agents</title>
       <para>Creates, updates, and deletes guest agents. Use guest
         agents to access files on the disk, configure networking, or
         run other applications or scripts in the guest while it runs.
@@ -439,14 +451,14 @@
       xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
   </chapter>
   <chapter xml:id="volumes-api">
-    <title>Block Storage Service API v2.0</title>
+    <title>Block Storage Service API v2</title>
     <para>Manages volumes and snapshots for use with the Volume API
       (cinder services).</para>
     <wadl:resources href="../wadls/volume-api/src/v2/volume-api.wadl"
       xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
   </chapter>
   <chapter xml:id="os-object-api-1.0">
-    <title>Object Storage API v1.0</title>
+    <title>Object Storage API v1</title>
     <para>Manages the accounts, containers, and objects in the object
       storage system.</para>
     <wadl:resources