319 lines
11 KiB
XML
319 lines
11 KiB
XML
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg"
|
|
xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT">
|
|
<title>Maven Example Documentation</title>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>Badges! We don't need any stinking badges!</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<copyright>
|
|
<year>2011</year>
|
|
<holder>Timothy D. Witham</holder>
|
|
</copyright>
|
|
<releaseinfo>Example v0.1</releaseinfo>
|
|
<productname>Product Name Doesn't Exist - it's an example!™</productname>
|
|
<pubdate>2011-01-01</pubdate>
|
|
<legalnotice role="rs-api">
|
|
<annotation>
|
|
<remark>Copyright details are filled in by the template. Change the value of the role
|
|
attribute on the legalnotice element to change the license. </remark>
|
|
</annotation>
|
|
</legalnotice>
|
|
<abstract>
|
|
<para> This document is intended for individuals who whish to produce documentation using Maven and having
|
|
the same "feel" as the documentation that is produced by the mainline OpenStack projects.
|
|
</para>
|
|
</abstract>
|
|
<cover>
|
|
<para>this is a placeholder for the front cover</para>
|
|
</cover>
|
|
<cover>
|
|
<para>this is a placeholder for the back cover</para>
|
|
</cover>
|
|
</info>
|
|
<chapter>
|
|
<title>Overview</title>
|
|
<para>Welcome to the getting started with Maven documentation. Congratulations you have
|
|
successfully downloaded and built the example.
|
|
</para>
|
|
<para>For more details on the Product Name service, please refer to <link
|
|
xlink:href="http://www.rackspacecloud.com/cloud_hosting_products/files"
|
|
>http://www.rackspacecloud.com/cloud_hosting_products/product name</link>
|
|
</para>
|
|
<para>We welcome feedback, comments, and bug reports at <link
|
|
xlink:href="mailto:support@rackspacecloud.com">support@rackspacecloud.com</link>. </para>
|
|
<section>
|
|
<title>Intended Audience</title>
|
|
<para>This guide is intended to individuals who want to develop standalone documentation
|
|
to use within an OpenStack deployment. Using this tool chain will give you the look and
|
|
feel of the mainline OpenStack documentation.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Document Change History</title>
|
|
<para>This version of the Maven Getting Started Guide replaces and obsoletes all previous versions. The
|
|
most recent changes are described in the table below:</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<td align="center" colspan="1">Revision Date</td>
|
|
<td align="center" colspan="4">Summary of Changes</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1" align="center">July. 14, 2011</td>
|
|
<td colspan="4">
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial document creation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
</section>
|
|
<section>
|
|
<title>Additional Resources</title>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<link xlink:href="http://www.openstack.org">
|
|
Openstack - Cloud Software
|
|
</link>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link xlink:href="http://www.docbook.org">
|
|
Docbook Main Web Site
|
|
</link>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<link xlink:href="http://docbook.org/tdg/en/html/quickref.html">
|
|
Docbook Quick Reference
|
|
</link>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Concepts</title>
|
|
<para>
|
|
Need to put something here.
|
|
</para>
|
|
</chapter>
|
|
<chapter>
|
|
<title>How do I?</title>
|
|
|
|
<section>
|
|
<title>Notes and including images</title>
|
|
<para>So I want an note and an image in this section ...</para>
|
|
<note>
|
|
<para>This is an example of a note. </para>
|
|
</note>
|
|
|
|
<para>Here's a sample figure in svg and png formats:</para>
|
|
<figure xml:id="CFinterfaces">
|
|
<title>Sample Image</title>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata fileref="figures/example.svg" contentwidth="5in"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata fileref="figures/example.png"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</figure>
|
|
</section>
|
|
<section>
|
|
<title>Multiple Related Documents</title>
|
|
<para>
|
|
What you need to do in order to have multiple documents fit within the
|
|
build structure.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Using multiple files for a document</title>
|
|
<para>
|
|
What you need to do in order to have a single document that is made up of multiple
|
|
files.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Who, What, Where, When and Why of pom.xml</title>
|
|
<para>
|
|
You will of noticed the <emphasis>pom.xml</emphasis> file at the root directory.
|
|
This file is used to set the project parameters for the documentation. Including
|
|
what type of documentation to produce and any post processing that needs to happen.
|
|
If you want to know more about
|
|
<link
|
|
xlink:href="http://www.openstack.org">
|
|
pom.xml - need a link
|
|
</link>
|
|
then follow the link.
|
|
</para>
|
|
<para> For the <emphasis>pom.xml</emphasis>file that was included in this distribution we will
|
|
parse the individual lines and explaine the meaning.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"> <xi:include href="../../pom.xml" parse="text" /></programlisting>
|
|
</para>
|
|
<section>
|
|
<title> <project> </title>
|
|
<para>
|
|
What is all of this stuff and why is it important?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <modelVersion> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <groupId> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <artifactId> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <version> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <packaging> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <name> </title>
|
|
<para>
|
|
Name of your document.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <build> </title>
|
|
<para>
|
|
Make some documents.
|
|
</para>
|
|
<section>
|
|
<title> <plugin(s)> </title>
|
|
<para>
|
|
What does this do and why?
|
|
</para>
|
|
<section>
|
|
<title> <groupId> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <artifactId> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <execution(s)> </title>
|
|
<para>
|
|
What goes in here and why?
|
|
</para>
|
|
<section>
|
|
<title> <goal(s)> </title>
|
|
<para>
|
|
Different types of goals and why you use them.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <phase> </title>
|
|
<para>
|
|
What does this section do? What phases can you specify.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title> <configuration> </title>
|
|
<para>
|
|
What does this section do?
|
|
</para>
|
|
<section>
|
|
<title> <xincludeSupported> </title>
|
|
<para>
|
|
What does this do and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <chunkSectionDepth> </title>
|
|
<para>
|
|
What does this do and why?
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title> <postprocess> </title>
|
|
<para>
|
|
What does this section do? What are possible pieces?
|
|
</para>
|
|
<section>
|
|
<title> <copy> </title>
|
|
<para>
|
|
What does this section do? What are possible pieces?
|
|
</para>
|
|
<section>
|
|
<title> <fileset> </title>
|
|
<para>
|
|
What does this section do? What are possible pieces?
|
|
</para>
|
|
<section>
|
|
<title> <include> </title>
|
|
<para>
|
|
What does this section do? What are possible pieces?
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Who, What, Where, When and Why of build.xml</title>
|
|
<para>
|
|
You will of noticed the <emphasis>build.xml</emphasis> file at the root directory.
|
|
This file is used to set the project parameters for the documentation. Including
|
|
what type of documentation to produce and any post processing that needs to happen.
|
|
If you want to know more about
|
|
<link
|
|
xlink:href="http://www.openstack.org">
|
|
pom.xml - need a link
|
|
</link>
|
|
then follow the link.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Troubleshooting</title>
|
|
<para>Sometimes things go wrong...</para>
|
|
</chapter>
|
|
</book>
|