Initial source priming
The OpenPOWER Foundation master template document is based loosely on the OpenStack Manuals project in GitHub at https://github.com/openstack/openstack-manuals Many of the examples in the documentation were created by another IBM employee, Jeff Brown (jeffdb@us.ibm.com). Reviews of the content have been handled by the OpenPOWER Foundation Technical Steering Committee and the System Software Work Group. While the format of the document is in good shape, the technical details remain to be verified and the Docbook source reviewed before publishing version 1.0. However, this is a good starting point. Signed-off-by: Jeff Scheel <scheel@us.ibm.com>master
Jeff Scheel
9 years ago
parent
45bc5cc263
commit
7f09435f1e
@ -0,0 +1,176 @@
|
|||||||
|
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
@ -1,2 +1,14 @@
|
|||||||
# master_template
|
# Master Template Document Project for OpenPOWER Foundation Documentation
|
||||||
This repository is for the development and maintenance of the Docbook common files and template used for OPF Workgroup documents
|
This repository hold the source for the master document template for
|
||||||
|
OpenPOWER Foundation. The PDF and HTML generated from the doc/template/
|
||||||
|
directory build a document that both describes how to build a new
|
||||||
|
document and contains examples and directions on how to do it.
|
||||||
|
|
||||||
|
The online version of the document can be found in the OpenPOWER Foundation
|
||||||
|
Document library at [TBD](http://openpowerfoundation.org/docs)
|
||||||
|
|
||||||
|
The project which control the look and feel of the document is the
|
||||||
|
[Docs-Maven-Plugin project](https://github.com/OpenPOWERFoundation/Docs-Maven-Plugin).
|
||||||
|
|
||||||
|
To contribute to the OpenPOWER Foundation template document project, contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or
|
||||||
|
Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\).
|
||||||
|
|||||||
@ -0,0 +1,136 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<appendix xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="app_opf_overview">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
<title>OpenPOWER Foundation overview</title>
|
||||||
|
<para>
|
||||||
|
The OpenPOWER Foundation was founded in 2013 as an open technical membership organization
|
||||||
|
that will enable data centers to rethink their approach to technology. Member companies
|
||||||
|
are enabled to customize POWER CPU processors and system platforms for optimization and
|
||||||
|
innovation for their business needs. These innovations include custom systems for large
|
||||||
|
or warehouse scale data centers, workload acceleration through GPU, FPGA or advanced I/O,
|
||||||
|
platform optimization for SW appliances, or advanced hardware technology exploitation.
|
||||||
|
OpenPOWER members are actively pursing all of these innovations and more and welcome
|
||||||
|
all parties to join in moving the state of the art of OpenPOWER systems design forward.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
To learn more about the OpenPOWER Foundation, visit the organization website at
|
||||||
|
<link xlink:href="http://openpowerfoundation.org">openpowerfoundation.org</link>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section xml:id="opf-documentation">
|
||||||
|
<title>Foundation documentation</title>
|
||||||
|
<para>Key foundation documents include:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://openpowerfoundation.org/wp-content/uploads/2014/07/OPF-Bylaws-0410.2014.pdf">
|
||||||
|
<citetitle>Bylaws of OpenPOWER Foundation</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://openpowerfoundation.org/wp-content/uploads/2015/02/OpenPOWER-IPR-Policy.1.15.2015.pdf">
|
||||||
|
<citetitle>OpenPOWER Foundation Intellectual Property Rights (IPR) Policy</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://openpowerfoundation.org/wp-content/uploads/2014/07/OpenPOWER-Membership-Agreement-04.2014.pdf">
|
||||||
|
<citetitle>OpenPOWER Foundation Membership Agreement</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<!-- link
|
||||||
|
xlink:href="http://openpowerfoundation.org/wp-content/uploads/TBD" -->
|
||||||
|
<citetitle>OpenPOWER Anti-Trust Guidelines (link TBD)</citetitle>
|
||||||
|
<!-- /link --></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>More information about the foundation governance can be found at
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/about-us/governance/">openpowerfoundation.org/about-us/governance</link>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="opf-resources">
|
||||||
|
<title>Technical resources</title>
|
||||||
|
<para>Development resouces fall into the following general categories:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/working-groups/">
|
||||||
|
Foundation work groups</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/technical-resources/development-environmentvm/">
|
||||||
|
Remote development environments (VMs)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/technical-resources/development-systems/">
|
||||||
|
Development systems</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/technical-resources/technical-specifications/">
|
||||||
|
Technical specifications</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/technical-resources/software/">
|
||||||
|
Software</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/technical-resources/openpower-developer-tools/">
|
||||||
|
Developer tools</link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>The complete list of technical resources are maintained on the foundation
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/technical/">Technical Resources</link> web page.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="opf-contact">
|
||||||
|
<title>Contact the foundation</title>
|
||||||
|
<para>To learn more about the OpenPOWER Foundation, please use the following contact points:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>General information -- <email>info@openpowerfoundation.org</email>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Membership -- <email>membership@openpowerfoundation.org</email>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Technical Work Groups and projects -- Jeff Brown, TSC Chair, <email>tsc-chair@openpowerfoundation.org</email>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Events and other activities -- Michelle Hunt, OpenPOWER ED, <email>m.hunt@ieee.org</email>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Press/Analysts -- <email>press@openpowerfoundation.org</email>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
More contact information the foundation governance can be found at
|
||||||
|
<link xlink:href="http://openpowerfoundation.org/get-involved/contact-us/">openpowerfoundation.org/get-involved/contact-us</link>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</appendix>
|
||||||
@ -0,0 +1,437 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<appendix xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="app_community_support">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
<title>Community support</title>
|
||||||
|
<para>The following resources are available to help you run and use
|
||||||
|
OpenStack. The OpenStack community constantly improves and
|
||||||
|
adds to the main features of OpenStack, but if you have
|
||||||
|
any questions, do not hesitate to ask. Use the
|
||||||
|
following resources to get OpenStack support,
|
||||||
|
and troubleshoot your installations.</para>
|
||||||
|
<section xml:id="support-documentation">
|
||||||
|
<title>Documentation</title>
|
||||||
|
<para>For the available OpenStack documentation, see <link
|
||||||
|
xlink:href="http://docs.openstack.org"
|
||||||
|
>docs.openstack.org</link>.</para>
|
||||||
|
<para>To provide feedback on documentation, join and use the
|
||||||
|
<email>openstack-docs@lists.openstack.org</email>
|
||||||
|
mailing list at <link
|
||||||
|
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs"
|
||||||
|
>OpenStack Documentation Mailing List</link>, or <link
|
||||||
|
xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug"
|
||||||
|
>report a bug</link>.</para>
|
||||||
|
<para>The following books explain how to install an OpenStack
|
||||||
|
cloud and its associated components:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/trunk/install-guide/install/apt-debian/content/">
|
||||||
|
<citetitle>Installation Guide for Debian
|
||||||
|
7.0</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/trunk/install-guide/install/zypper/content/">
|
||||||
|
<citetitle>Installation Guide for openSUSE and
|
||||||
|
SUSE Linux Enterprise Server</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/trunk/install-guide/install/yum/content/">
|
||||||
|
<citetitle>Installation Guide for Red Hat
|
||||||
|
Enterprise Linux, CentOS, and
|
||||||
|
Fedora</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/trunk/install-guide/install/apt/content/">
|
||||||
|
<citetitle>Installation Guide for Ubuntu 14.04
|
||||||
|
(LTS)</citetitle>
|
||||||
|
</link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>The following books explain how to configure and run an
|
||||||
|
OpenStack cloud:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/arch-design/content/"
|
||||||
|
><citetitle>Architecture Design
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/"
|
||||||
|
><citetitle>Cloud Administrator
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/trunk/config-reference/content/"
|
||||||
|
><citetitle>Configuration
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/ops/"
|
||||||
|
><citetitle>Operations
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/high-availability-guide/content/"
|
||||||
|
><citetitle>High Availability
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/sec/"
|
||||||
|
><citetitle>Security
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/image-guide/content/"
|
||||||
|
><citetitle>Virtual Machine Image
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>The following books explain how to use the OpenStack
|
||||||
|
dashboard and command-line clients:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/api/quick-start/content/"
|
||||||
|
><citetitle>API Quick
|
||||||
|
Start</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/user-guide/content/"
|
||||||
|
><citetitle>End User
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/user-guide-admin/content/"
|
||||||
|
><citetitle>Admin User
|
||||||
|
Guide</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<link
|
||||||
|
xlink:href="http://docs.openstack.org/cli-reference/content/"
|
||||||
|
><citetitle>Command-Line Interface
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>The following documentation provides reference and
|
||||||
|
guidance information for the OpenStack APIs:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://developer.openstack.org/api-ref.html"
|
||||||
|
>OpenStack API Complete
|
||||||
|
Reference (HTML)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://developer.openstack.org/api-ref-guides/bk-api-ref.pdf"
|
||||||
|
>API Complete Reference (PDF)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-block-storage/2.0/content/"
|
||||||
|
><citetitle>OpenStack Block Storage
|
||||||
|
Service API v2
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-compute/2/content/"
|
||||||
|
><citetitle>OpenStack Compute API v2 and
|
||||||
|
Extensions
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
|
||||||
|
><citetitle>OpenStack Identity Service API
|
||||||
|
v2.0 Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-image-service/2.0/content/"
|
||||||
|
><citetitle>OpenStack Image Service API v2
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-network/2.0/content/"
|
||||||
|
><citetitle>OpenStack Networking API v2.0
|
||||||
|
Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="http://docs.openstack.org/api/openstack-object-storage/1.0/content/"
|
||||||
|
><citetitle>OpenStack Object Storage API
|
||||||
|
v1 Reference</citetitle></link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>The <link
|
||||||
|
xlink:href="http://docs.openstack.org/training-guides/content/"
|
||||||
|
><citetitle>Training Guides</citetitle></link>
|
||||||
|
offer software training for cloud administration and
|
||||||
|
management.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-ask_openstack">
|
||||||
|
<title>ask.openstack.org</title>
|
||||||
|
<para>During the set up or testing of OpenStack, you might
|
||||||
|
have questions about how a specific task is completed or
|
||||||
|
be in a situation where a feature does not work correctly.
|
||||||
|
Use the <link xlink:href="http://ask.openstack.org"
|
||||||
|
>ask.openstack.org</link> site to ask questions and
|
||||||
|
get answers. When you visit the <link
|
||||||
|
xlink:href="http://ask.openstack.org"
|
||||||
|
>http://ask.openstack.org</link> site, scan the
|
||||||
|
recently asked questions to see whether your question has
|
||||||
|
already been answered. If not, ask a new question. Be sure
|
||||||
|
to give a clear, concise summary in the title and provide
|
||||||
|
as much detail as possible in the description. Paste in
|
||||||
|
your command output or stack traces, links to screen
|
||||||
|
shots, and any other information which
|
||||||
|
might be useful.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-mailing-lists">
|
||||||
|
<title>OpenStack mailing lists</title>
|
||||||
|
<para>A great way to get answers and insights is to post your
|
||||||
|
question or problematic scenario to the OpenStack mailing
|
||||||
|
list. You can learn from and help others who might have
|
||||||
|
similar issues. To subscribe or view the archives, go to
|
||||||
|
<link
|
||||||
|
xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack"
|
||||||
|
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack</link>.
|
||||||
|
You might be interested in the other mailing lists for
|
||||||
|
specific projects or development, which you can find <link
|
||||||
|
xlink:href="http://wiki.openstack.org/MailingLists">on
|
||||||
|
the wiki</link>. A description of all mailing lists is
|
||||||
|
available at <link
|
||||||
|
xlink:href="http://wiki.openstack.org/MailingLists"
|
||||||
|
>http://wiki.openstack.org/MailingLists</link>.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-wiki">
|
||||||
|
<title>The OpenStack wiki</title>
|
||||||
|
<para>The <link xlink:href="http://wiki.openstack.org/">OpenStack
|
||||||
|
wiki</link> contains a broad range of topics but some of the
|
||||||
|
information can be difficult to find or is a few pages deep.
|
||||||
|
Fortunately, the wiki search feature enables you to search by title
|
||||||
|
or content. If you search for specific information, such as about
|
||||||
|
networking or nova, you can find a large amount of relevant
|
||||||
|
material. More is being added all the time, so be sure to check back
|
||||||
|
often. You can find the search box in the upper-right corner of any
|
||||||
|
OpenStack wiki page.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-bugs-area">
|
||||||
|
<title>The Launchpad Bugs area</title>
|
||||||
|
<para>The OpenStack community values your set up and testing efforts and
|
||||||
|
wants your feedback. To log a bug, you must sign up for a Launchpad
|
||||||
|
account at <link xlink:href="https://launchpad.net/+login"
|
||||||
|
>https://launchpad.net/+login</link>. You can view existing bugs
|
||||||
|
and report bugs in the Launchpad Bugs area. Use the search feature
|
||||||
|
to determine whether the bug has already been reported or already
|
||||||
|
been fixed. If it still seems like your bug is unreported, fill out
|
||||||
|
a bug report.</para>
|
||||||
|
<para>Some tips:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Give a clear, concise summary.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Provide as much detail as possible in the
|
||||||
|
description. Paste in your command output or stack
|
||||||
|
traces, links to screen shots, and any
|
||||||
|
other information which might be useful.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Be sure to include the software and package
|
||||||
|
versions that you are using, especially if you are
|
||||||
|
using a development branch, such as,
|
||||||
|
<literal>"Juno release" vs git commit
|
||||||
|
bc79c3ecc55929bac585d04a03475b72e06a3208</literal>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Any deployment-specific information is helpful, such as
|
||||||
|
whether you are using Ubuntu 14.04 or are performing a
|
||||||
|
multi-node installation.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
<para>The following Launchpad Bugs areas are available:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<!-- Core projects, sorted alphabetically -->
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/nova"
|
||||||
|
>Bugs: OpenStack Block Storage
|
||||||
|
(cinder)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/nova"
|
||||||
|
>Bugs: OpenStack Compute (nova)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/horizon"
|
||||||
|
>Bugs: OpenStack Dashboard
|
||||||
|
(horizon)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/keystone"
|
||||||
|
>Bugs: OpenStack Identity
|
||||||
|
(keystone)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/glance"
|
||||||
|
>Bugs: OpenStack Image Service
|
||||||
|
(glance)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/neutron"
|
||||||
|
>Bugs: OpenStack Networking
|
||||||
|
(neutron)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/swift"
|
||||||
|
>Bugs: OpenStack Object Storage
|
||||||
|
(swift)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<!-- Modules, sorted alphabetically -->
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/ironic"
|
||||||
|
>Bugs: Bare Metal (ironic)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/sahara"
|
||||||
|
>Bugs: Data Processing Service
|
||||||
|
(sahara)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/trove"
|
||||||
|
>Bugs: Database Service (trove)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/heat"
|
||||||
|
>Bugs: Orchestration (heat)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/ceilometer"
|
||||||
|
>Bugs: Telemetry (ceilometer)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/marconi"
|
||||||
|
>Bugs: Queue Service (marconi)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<!-- Programs, sorted alphabetically -->
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/openstack-api-site"
|
||||||
|
>Bugs: OpenStack API Documentation
|
||||||
|
(developer.openstack.org)</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><link
|
||||||
|
xlink:href="https://bugs.launchpad.net/openstack-manuals"
|
||||||
|
>Bugs: OpenStack Documentation
|
||||||
|
(docs.openstack.org)</link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-irc-channel">
|
||||||
|
<title>The OpenStack IRC channel</title>
|
||||||
|
<para>The OpenStack community lives in the #openstack IRC channel on the
|
||||||
|
Freenode network. You can hang out, ask questions, or get immediate
|
||||||
|
feedback for urgent and pressing issues. To install an IRC client or
|
||||||
|
use a browser-based client, go to <link
|
||||||
|
xlink:href="http://webchat.freenode.net"
|
||||||
|
>http://webchat.freenode.net/</link>. You can also use Colloquy
|
||||||
|
(Mac OS X, <link xlink:href="http://colloquy.info/"
|
||||||
|
>http://colloquy.info/</link>), mIRC (Windows, <link
|
||||||
|
xlink:href="http://www.mirc.com/">http://www.mirc.com/</link>),
|
||||||
|
or XChat (Linux). When you are in the IRC channel and want to share
|
||||||
|
code or command output, the generally accepted method is to use a
|
||||||
|
Paste Bin. The OpenStack project has one at <link
|
||||||
|
xlink:href="http://paste.openstack.org"
|
||||||
|
>http://paste.openstack.org</link>. Just paste your longer
|
||||||
|
amounts of text or logs in the web form and you get a URL that you
|
||||||
|
can paste into the channel. The OpenStack IRC channel is
|
||||||
|
<literal>#openstack</literal> on
|
||||||
|
<literal>irc.freenode.net</literal>. You can find a list of all
|
||||||
|
OpenStack IRC channels at <link
|
||||||
|
xlink:href="https://wiki.openstack.org/wiki/IRC"
|
||||||
|
>https://wiki.openstack.org/wiki/IRC</link>.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="support-documentation-feedback">
|
||||||
|
<title>Documentation feedback</title>
|
||||||
|
<para>To provide feedback on documentation, join and use the
|
||||||
|
<email>openstack-docs@lists.openstack.org</email> mailing list at
|
||||||
|
<link xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">OpenStack
|
||||||
|
Documentation Mailing List</link>, or <link xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug">report a bug</link>.</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="distro-support">
|
||||||
|
<title>OpenStack distribution packages</title>
|
||||||
|
<para>The following Linux distributions provide
|
||||||
|
community-supported packages for OpenStack:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="bold">Debian:</emphasis>
|
||||||
|
<link
|
||||||
|
xlink:href="http://wiki.debian.org/OpenStack"
|
||||||
|
>http://wiki.debian.org/OpenStack</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="bold">CentOS, Fedora, and Red
|
||||||
|
Hat Enterprise Linux:</emphasis>
|
||||||
|
<link xlink:href="http://openstack.redhat.com/"
|
||||||
|
>http://openstack.redhat.com/</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="bold">openSUSE and SUSE Linux
|
||||||
|
Enterprise Server:</emphasis>
|
||||||
|
<link
|
||||||
|
xlink:href="http://en.opensuse.org/Portal:OpenStack"
|
||||||
|
>http://en.opensuse.org/Portal:OpenStack</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="bold">Ubuntu:</emphasis>
|
||||||
|
<link
|
||||||
|
xlink:href="https://wiki.ubuntu.com/ServerTeam/CloudArchive"
|
||||||
|
>https://wiki.ubuntu.com/ServerTeam/CloudArchive</link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
</appendix>
|
||||||
@ -0,0 +1,12 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<preface xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="ch_preface">
|
||||||
|
<title>Preface</title>
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
|
||||||
|
<xi:include href="sec_conventions.xml"/>
|
||||||
|
<xi:include href="sec_dochistory.xml"/>
|
||||||
|
</preface>
|
||||||
@ -0,0 +1,40 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="section_conventions">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
<title>Conventions</title>
|
||||||
|
<para>The OpenPOWER Foundation documentation uses several typesetting conventions.</para>
|
||||||
|
<simplesect xml:id="conventions-admonitions">
|
||||||
|
<title>Notices</title>
|
||||||
|
<para>Notices take these forms:</para>
|
||||||
|
<note>
|
||||||
|
<para>A handy tip or reminder.</para>
|
||||||
|
</note>
|
||||||
|
<important>
|
||||||
|
<para>Something you must be aware of before proceeding.</para>
|
||||||
|
</important>
|
||||||
|
<warning>
|
||||||
|
<para>Critical information about the risk of data loss or security issues.</para>
|
||||||
|
</warning>
|
||||||
|
</simplesect>
|
||||||
|
<simplesect xml:id="conventions-prompts">
|
||||||
|
<title>Command prompts</title>
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis role="bold"><prompt>$</prompt> prompt</emphasis></term>
|
||||||
|
<listitem>
|
||||||
|
<para>Any user, including the <literal>root</literal> user, can run commands that are
|
||||||
|
prefixed with the <prompt>$</prompt> prompt.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis role="bold"><prompt>#</prompt> prompt</emphasis></term>
|
||||||
|
<listitem>
|
||||||
|
<para>The <literal>root</literal> user must run commands that are prefixed with the
|
||||||
|
<prompt>#</prompt> prompt. You can also prefix these commands with the
|
||||||
|
<command>sudo</command> command, if available, to run them.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</simplesect>
|
||||||
|
</section>
|
||||||
@ -0,0 +1,13 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<section xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="doc_change_history">
|
||||||
|
<title>Document change history</title>
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
<para>This version of the guide replaces and obsoletes all earlier versions.</para>
|
||||||
|
<para>The following table describes the most recent changes:</para>
|
||||||
|
<?rax revhistory?>
|
||||||
|
<!-- Table generated in output from revision element in the book element -->
|
||||||
|
</section>
|
||||||
@ -0,0 +1,51 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||||
|
<modelVersion>4.0.0</modelVersion>
|
||||||
|
|
||||||
|
<groupId>org.openpowerfoundation.docs</groupId>
|
||||||
|
|
||||||
|
<artifactId>parent-pom</artifactId>
|
||||||
|
<version>1.0.0-SNAPSHOT</version>
|
||||||
|
<packaging>pom</packaging>
|
||||||
|
|
||||||
|
<modules>
|
||||||
|
<module>template</module>
|
||||||
|
</modules>
|
||||||
|
<profiles>
|
||||||
|
<profile>
|
||||||
|
<id>OpenPOWER Foundation Repositories</id>
|
||||||
|
<activation>
|
||||||
|
<activeByDefault>true</activeByDefault>
|
||||||
|
</activation>
|
||||||
|
<repositories>
|
||||||
|
<repository>
|
||||||
|
<id>openpower-foundation</id>
|
||||||
|
<name>OpenPOWER Foundation Repository</name>
|
||||||
|
<url>http://rchgsa.ibm.com/gsa/rchgsa/home/s/c/scheel/web/public/repo.openpowerfoundation.org/</url>
|
||||||
|
<!-- url>http://openpowerfoundation.org/repo.openpowerfoundation.org/</url -->
|
||||||
|
</repository>
|
||||||
|
</repositories>
|
||||||
|
<pluginRepositories>
|
||||||
|
<pluginRepository>
|
||||||
|
<id>openpower-foundation</id>
|
||||||
|
<name>OpenPOWER Foundation Repository</name>
|
||||||
|
<url>http://rchgsa.ibm.com/gsa/rchgsa/home/s/c/scheel/web/public/repo.openpowerfoundation.org/</url>
|
||||||
|
<!-- url>http://openpowerfoundation.org/repo.openpowerfoundation.org/</url -->
|
||||||
|
</pluginRepository>
|
||||||
|
</pluginRepositories>
|
||||||
|
</profile>
|
||||||
|
</profiles>
|
||||||
|
<build>
|
||||||
|
<plugins>
|
||||||
|
<plugin>
|
||||||
|
|
||||||
|
<groupId>org.openpowerfoundation.docs</groupId>
|
||||||
|
|
||||||
|
<artifactId>openpowerdocs-maven-plugin</artifactId>
|
||||||
|
<version>1.0.1</version>
|
||||||
|
</plugin>
|
||||||
|
</plugins>
|
||||||
|
</build>
|
||||||
|
</project>
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<appendix xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
xml:id="app_template">
|
||||||
|
<?dbhtml stop-chunking?>
|
||||||
|
<title>Appendix template</title>
|
||||||
|
<para>This is the first paragraph of a new appendix...</para>
|
||||||
|
<section xml:id="sample-app-section">
|
||||||
|
<title>Section title</title>
|
||||||
|
<para>Section text...</para>
|
||||||
|
</section>
|
||||||
|
</appendix>
|
||||||
@ -0,0 +1,88 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<book xmlns="http://docbook.org/ns/docbook"
|
||||||
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
version="5.0"
|
||||||
|
status="draft"
|
||||||
|
xml:id="bk_main">
|
||||||
|
|
||||||
|
<!-- TODO: When ready to publish document, remove the 'status="draft"' statement from the book object above. -->
|
||||||
|
|
||||||
|
<!-- TODO: Pick a Title for the new document -->
|
||||||
|
<title>Template Guide</title>
|
||||||
|
<!-- TODO: Either add a subtitle or remove the following line -->
|
||||||
|
<subtitle>A quick start template</subtitle>
|
||||||
|
|
||||||
|
<info>
|
||||||
|
<author>
|
||||||
|
<personname>
|
||||||
|
<!-- TODO: Insert appropriate firstname and surnames -->
|
||||||
|
<firstname>Firstname</firstname>
|
||||||
|
<surname>Lastname</surname>
|
||||||
|
</personname>
|
||||||
|
<!-- TODO: Set correct email address of document author -->
|
||||||
|
<email>Email@domain</email>
|
||||||
|
<affiliation>
|
||||||
|
<!-- TODO: Insert appropriate orgname -->
|
||||||
|
<orgname>Company</orgname>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<copyright>
|
||||||
|
<!-- TODO: Set copyright year -->
|
||||||
|
<year>2015</year>
|
||||||
|
<holder>OpenPOWER Foundation</holder>
|
||||||
|
</copyright>
|
||||||
|
<!-- TODO: Set the correct document releaseinfo -->
|
||||||
|
<releaseinfo>Revision 0.9</releaseinfo>
|
||||||
|
<productname>OpenPOWER</productname>
|
||||||
|
<pubdate/>
|
||||||
|
|
||||||
|
<!-- TODO: Select one of the two following legalnotice role= values:
|
||||||
|
"apache2" for an Apache V2 license or
|
||||||
|
"opfExternal" for an official OpenPOWER Foundation external license text.
|
||||||
|
If you don't know which one to select, leave as "apache2" -->
|
||||||
|
<legalnotice role="apache2">
|
||||||
|
<!--legalnotice role="opfExternal"-->
|
||||||
|
|
||||||
|
<annotation>
|
||||||
|
<remark>Copyright details are filled in by the template.</remark>
|
||||||
|
</annotation>
|
||||||
|
</legalnotice>
|
||||||
|
<!-- TODO: Decide whether you want any text inserted before the author listing.
|
||||||
|
If you do, undelete the comment and adjust text between the paragraph tags below. -->
|
||||||
|
<!--
|
||||||
|
<abstract>
|
||||||
|
<para>Abstract text</para>
|
||||||
|
</abstract>
|
||||||
|
-->
|
||||||
|
|
||||||
|
<revhistory>
|
||||||
|
<revision>
|
||||||
|
<!-- TODO: Set the initial version information -->
|
||||||
|
<date>2014-09-03</date>
|
||||||
|
<revdescription>
|
||||||
|
<itemizedlist spacing="compact">
|
||||||
|
<listitem>
|
||||||
|
<para>Creation based on OpenStack documentation</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</revdescription>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</info>
|
||||||
|
|
||||||
|
<!-- The ch_preface.xml file is required by all documents -->
|
||||||
|
<xi:include href="../common/ch_preface.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: Add your chapter heading files here. Remove both files and insert your own. -->
|
||||||
|
<!-- See the template document for naming conventions and location of files. -->
|
||||||
|
<xi:include href="ch_template_overview.xml"/>
|
||||||
|
<xi:include href="ch_example.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: The following appendices are optional but highly recommended. You may add others as needed. -->
|
||||||
|
<xi:include href="../common/app_foundation.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: The following template document may be modified to create additional appendices -->
|
||||||
|
<xi:include href="app_template.xml"/>
|
||||||
|
|
||||||
|
</book>
|
||||||
@ -0,0 +1,202 @@
|
|||||||
|
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_examples">
|
||||||
|
|
||||||
|
<!-- Chapter Title goes here. -->
|
||||||
|
<title>Documentation examples</title>
|
||||||
|
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Section Title goes here</title>
|
||||||
|
<para>This Section covers something of interest to a limited number of people and shows a 1st level section</para>
|
||||||
|
|
||||||
|
<section xml:id="list_example_label">
|
||||||
|
<title>Example Itemized List</title>
|
||||||
|
<para>
|
||||||
|
Here's an example of an itemized list</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Item you don't care about</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Item you might care about </para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Item you do care about </para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</section>
|
||||||
|
<section>
|
||||||
|
<title>Example ordered list</title>
|
||||||
|
<para>
|
||||||
|
All good documents need ordered lists.</para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>First item</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Second item</para>
|
||||||
|
<orderedlist numeration="loweralpha">
|
||||||
|
<listitem>
|
||||||
|
<para>first indented item</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para> second indented item</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Third item</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Example figure with embedded graphic</title>
|
||||||
|
<para>
|
||||||
|
Here is how you embed a graphic.</para>
|
||||||
|
<figure pgwide="1" xml:id="figure_label">
|
||||||
|
<title>Example figure</title>
|
||||||
|
<mediaobject>
|
||||||
|
<imageobject>
|
||||||
|
<imagedata fileref="figures/example_graphic.bmp" format="GIF" scalefit="1" width="100%" />
|
||||||
|
</imageobject>
|
||||||
|
</mediaobject>
|
||||||
|
</figure>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Example table</title>
|
||||||
|
<para>Of course all good documents need tables. Here's how you build a basic table.</para>
|
||||||
|
|
||||||
|
<table frame="all" pgwide="1" xml:id="table_label">
|
||||||
|
<title>Example Table Title</title>
|
||||||
|
<tgroup cols="4">
|
||||||
|
<colspec colname="c1" colwidth="25*" />
|
||||||
|
<colspec colname="c2" colwidth="25*" />
|
||||||
|
<colspec colname="c3" colwidth="25*" />
|
||||||
|
<colspec colname="c4" colwidth="25*" />
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>
|
||||||
|
<para>
|
||||||
|
<emphasis role="bold">1st Column Heading</emphasis>
|
||||||
|
</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>
|
||||||
|
<emphasis role="bold">2nd Column Heading</emphasis>
|
||||||
|
</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>
|
||||||
|
<emphasis role="bold">3rd Column Heading</emphasis>
|
||||||
|
</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>
|
||||||
|
<emphasis role="bold">4th Column Heading</emphasis>
|
||||||
|
</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>
|
||||||
|
<para>Yes</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para><phrase role="red">Red</phrase></para>
|
||||||
|
<para><phrase role="green">Green</phrase></para>
|
||||||
|
<para><phrase role="blue">Blue</phrase></para>
|
||||||
|
<para><phrase role="#FFBF00">Custom (Amber)</phrase></para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>MAIN_Junk</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>More_Junk</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry namest='c1' nameend='c3' align='center'>
|
||||||
|
<para>merged cells horizontal</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>cell_stuff</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry morerows='1'>
|
||||||
|
<para>Merge cells vertical</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>filler</para>
|
||||||
|
</entry>
|
||||||
|
<entry namest='c3' nameend='c4' morerows='1' align='center'>
|
||||||
|
<para>merge cells both ways</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>
|
||||||
|
<para>filler 2</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
<row>
|
||||||
|
<entry>
|
||||||
|
<para>How about we put a list in the table cell</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>item 1</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>item 2</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>item 2</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>Another Cell</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>Yet Another Cell</para>
|
||||||
|
</entry>
|
||||||
|
<entry>
|
||||||
|
<para>Finally the last cell</para>
|
||||||
|
</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
</section>
|
||||||
|
<section>
|
||||||
|
<title>Example of crossreferences and footnotes</title>
|
||||||
|
<para>To reference another section or table is pretty easy. For example: see <xref linkend="table_label" /> for how tables look.</para>
|
||||||
|
<para>Lists are shown in <xref linkend="list_example_label" /> and if you need to make a footnote
|
||||||
|
<footnote xml:id="foot_id"><para>The footnote text goes here and can reference something like <xref linkend="figure_label" /> for additional explanation.</para></footnote>
|
||||||
|
For clarification that is easy. Of course you might want an additional reference to the footnote <footnoteref linkend="foot_id"/> which can also be done easily.</para>
|
||||||
|
<para>Lastly you probably want to mark text by making it <emphasis>italic text example</emphasis> or <emphasis role='bold'>Bold Text Example</emphasis>.</para>
|
||||||
|
</section>
|
||||||
|
<section>
|
||||||
|
<title>Example of code citations and user input</title>
|
||||||
|
<para>When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
|
||||||
|
<screen><prompt>$</prompt><userinput>echo "Hello world"</userinput>
|
||||||
|
Hello world
|
||||||
|
<prompt>$</prompt></screen>
|
||||||
|
</para>
|
||||||
|
<para>Docbook also allows for formatting and display of common languages, allowing for whitespace
|
||||||
|
and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:<programlisting linenumbering="numbered"><![CDATA[#include<stdio.h>
|
||||||
|
main()
|
||||||
|
{
|
||||||
|
printf("Hello world\n");
|
||||||
|
}]]></programlisting></para>
|
||||||
|
<para>If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: <literal>This is my literal
|
||||||
|
text. It ignores whitespace.</literal></para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
</chapter>
|
||||||
@ -0,0 +1,55 @@
|
|||||||
|
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||||
|
|
||||||
|
<title>Template document overview</title>
|
||||||
|
|
||||||
|
<para>The OpenPOWER Foundation documentation template provides a framework for OpenPOWER public and private
|
||||||
|
documentation. The goal of the template and this writeup is to promote community contributions
|
||||||
|
to OpenPOWER documenation and to enable new contributions within a common look and feel. </para>
|
||||||
|
|
||||||
|
<para>The major sections of this document addresses the following topics:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Getting started: This section details tools and commands used to contribute to OpenPOWER documentation.
|
||||||
|
All users who are new to OpenPOWER Foundation documentation should start here.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Creating a new document: This section provides step-by-step instructions on how to create a new document
|
||||||
|
from scratch. Use this section to start a new documentation project.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Modifying an existing document: This section highlights common steps in editing an existing OpenPOWER
|
||||||
|
Foundation document. Use this section as a guideline for contributing to an existing document.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Debugging build failures: This section provides examples of the two most common types of build failures
|
||||||
|
and helps users find the relevant failure information.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Policies and conventions: This secion contains
|
||||||
|
the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference
|
||||||
|
for documentation style beyond template provided features.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Frequently asked questions: This section answers common questions. Use this section when the other sections
|
||||||
|
do not answer your questions.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Where to find more information: This section provides pointers to on-line information about XML, Docbook,
|
||||||
|
Maven, and other relevant references.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>In addition to OpenPOWER Foundation specific topics, <xref linkend="section_template_examples"/>
|
||||||
|
provides examples of common documenation constructs in XML.</para>
|
||||||
|
|
||||||
|
<xi:include href="sec_template_getting_started.xml"/>
|
||||||
|
<xi:include href="sec_template_new_document.xml"/>
|
||||||
|
<xi:include href="sec_template_existing_document.xml"/>
|
||||||
|
<xi:include href="sec_template_debugging.xml"/>
|
||||||
|
<xi:include href="sec_template_policies.xml"/>
|
||||||
|
<xi:include href="sec_template_faq.xml"/>
|
||||||
|
<xi:include href="sec_template_references.xml"/>
|
||||||
|
|
||||||
|
|
||||||
|
</chapter>
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 648 KiB |
Binary file not shown.
@ -0,0 +1,128 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||||
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
|
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||||
|
<parent>
|
||||||
|
|
||||||
|
<groupId>org.openpowerfoundation.docs</groupId>
|
||||||
|
<artifactId>parent-pom</artifactId>
|
||||||
|
<version>1.0.0-SNAPSHOT</version>
|
||||||
|
<relativePath>../pom.xml</relativePath>
|
||||||
|
</parent>
|
||||||
|
<modelVersion>4.0.0</modelVersion>
|
||||||
|
|
||||||
|
<!-- TODO: Rename the artifactID field to some appropriate for your new document -->
|
||||||
|
<artifactId>openpower-template-guide</artifactId>
|
||||||
|
|
||||||
|
<packaging>jar</packaging>
|
||||||
|
|
||||||
|
<!-- TODO: Rename the name field to some appropriate for your new document -->
|
||||||
|
<name>OpenPOWER Template Guide</name>
|
||||||
|
|
||||||
|
<properties>
|
||||||
|
<!-- This is set by Jenkins according to the branch. -->
|
||||||
|
<release.path.name></release.path.name>
|
||||||
|
<comments.enabled>0</comments.enabled>
|
||||||
|
</properties>
|
||||||
|
<!-- ################################################ -->
|
||||||
|
<!-- USE "mvn clean generate-sources" to run this POM -->
|
||||||
|
<!-- ################################################ -->
|
||||||
|
<build>
|
||||||
|
<plugins>
|
||||||
|
<plugin>
|
||||||
|
|
||||||
|
<groupId>org.openpowerfoundation.docs</groupId>
|
||||||
|
|
||||||
|
<artifactId>openpowerdocs-maven-plugin</artifactId>
|
||||||
|
<!-- version set in ../pom.xml -->
|
||||||
|
<executions>
|
||||||
|
<execution>
|
||||||
|
<id>generate-webhelp</id>
|
||||||
|
<goals>
|
||||||
|
<goal>generate-webhelp</goal>
|
||||||
|
</goals>
|
||||||
|
<phase>generate-sources</phase>
|
||||||
|
<configuration>
|
||||||
|
<!-- These parameters only apply to webhelp -->
|
||||||
|
<enableDisqus>${comments.enabled}</enableDisqus>
|
||||||
|
<disqusShortname>openpower-template-guide</disqusShortname>
|
||||||
|
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||||
|
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
|
||||||
|
<generateToc>
|
||||||
|
appendix toc,title
|
||||||
|
article/appendix nop
|
||||||
|
article toc,title
|
||||||
|
book toc,title,figure,table,example,equation
|
||||||
|
book/appendix nop
|
||||||
|
book/chapter nop
|
||||||
|
chapter toc,title
|
||||||
|
chapter/section nop
|
||||||
|
section toc
|
||||||
|
part toc,title
|
||||||
|
qandadiv toc
|
||||||
|
qandaset toc
|
||||||
|
reference toc,title
|
||||||
|
set toc,title
|
||||||
|
</generateToc>
|
||||||
|
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||||
|
<sectionAutolabel>1</sectionAutolabel>
|
||||||
|
<tocSectionDepth>1</tocSectionDepth>
|
||||||
|
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>
|
||||||
|
|
||||||
|
<!-- TODO: Rename the webhelpDirname field to the new directory for new document -->
|
||||||
|
<webhelpDirname>template-guide</webhelpDirname>
|
||||||
|
|
||||||
|
<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
|
||||||
|
<pdfFilenameBase>template-guide</pdfFilenameBase>
|
||||||
|
|
||||||
|
<!-- TODO: If the document is not yet public, uncomment one of the following statements to create
|
||||||
|
a vertical running ribbon on the internal margin of the security status in all CAPS.
|
||||||
|
Values and definitions are formally defined by the IPR policy. A layman's definition follows:
|
||||||
|
|
||||||
|
working = typically new document within a work group that has not yet been reviewed
|
||||||
|
and/or approved for internal or external use.
|
||||||
|
internal = document that has been previously approved by a workgroup for internal use.
|
||||||
|
review = document that is under review
|
||||||
|
writeronly = document that has been created solely for the purpose of the writer (not in IPR policy)
|
||||||
|
|
||||||
|
The appropriate starting security for a new document is "working".
|
||||||
|
|
||||||
|
Note, the value of "external" is the same as specifying no status. -->
|
||||||
|
<security>review</security>
|
||||||
|
<!-- security>working</security -->
|
||||||
|
<!-- security>internal</security -->
|
||||||
|
<!-- security>writeronly</security -->
|
||||||
|
<!-- security>external</security -->
|
||||||
|
|
||||||
|
<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
|
||||||
|
Consult with the Work Group Chair or a Technical Steering Committee member if you have
|
||||||
|
questions about which value to select.
|
||||||
|
|
||||||
|
If no value is provided below, the document will default to "Work Group Notes".-->
|
||||||
|
<workProduct>workgroupNotes</workProduct>
|
||||||
|
<!-- workProduct>workgroupSpecification</workProduct -->
|
||||||
|
<!-- workProduct>candidateStandard</workProduct -->
|
||||||
|
<!-- workProduct>openpowerStandard</workProduct -->
|
||||||
|
|
||||||
|
</configuration>
|
||||||
|
</execution>
|
||||||
|
</executions>
|
||||||
|
<configuration>
|
||||||
|
<!-- These parameters apply to pdf and webhelp -->
|
||||||
|
<xincludeSupported>true</xincludeSupported>
|
||||||
|
<sourceDirectory>.</sourceDirectory>
|
||||||
|
<includes>
|
||||||
|
<!-- TODO: If you desire, you may change the following filename to something more appropriate for the new document -->
|
||||||
|
bk_main.xml
|
||||||
|
</includes>
|
||||||
|
|
||||||
|
<!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
|
||||||
|
<!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
|
||||||
|
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
|
||||||
|
<includeCoverLogo>1</includeCoverLogo>
|
||||||
|
<coverUrl>www.openpowerfoundation.org</coverUrl>
|
||||||
|
</configuration>
|
||||||
|
</plugin>
|
||||||
|
</plugins>
|
||||||
|
</build>
|
||||||
|
</project>
|
||||||
@ -0,0 +1,66 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug">
|
||||||
|
|
||||||
|
<title>Debugging build failures</title>
|
||||||
|
<para>Maven/docbkx failures generally fall into one of two categories, validation errors or build failures. Correcting the document begins with understanding which type of failure has occurred and understanding where to look in your document source.</para>
|
||||||
|
<para>Validation errors are generally indicated in the build output with text like the following:
|
||||||
|
<screen>...
|
||||||
|
@@@@@@@@@@@@@@@@@@@@@@
|
||||||
|
!!!VALIDATION ERRORS!!
|
||||||
|
!!!!!!!!!!!!!!!!!!!!!!
|
||||||
|
|
||||||
|
Note: Open the temporary file:
|
||||||
|
|
||||||
|
file:/home/user1/openpower-foundation-docbkx-framework/doc/template/target//bk_main.xml-invalid.xml
|
||||||
|
|
||||||
|
to see all the errors in context.
|
||||||
|
You must correct the errors in the original
|
||||||
|
source DocBook or wadl files however.
|
||||||
|
|
||||||
|
You can control whether build fails or not by
|
||||||
|
setting failOnValidationError to no in your pom.
|
||||||
|
|
||||||
|
lineNumber: 272; columnNumber: 70; text not allowed here; expected element "address", ...
|
||||||
|
</screen></para>
|
||||||
|
<para>This error message contains three key pieces of information:</para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>The full path and filename that contains the context for the failure. In the message above, this is
|
||||||
|
<literal>/home/user1/openpower-foundation-docbkx-framework/doc/template/target//bk_main.xml-invalid.xml</literal>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>The location within the file of the syntax error. For the above example, the key information is "<literal>lineNumber: 272; columnNumber: 70</literal>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
<para>Build errors are easily identified as well. Below is an example:
|
||||||
|
<screen>...
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] BUILD FAILURE
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Total time: 4.827s
|
||||||
|
[INFO] Finished at: Wed Jul 29 14:55:33 CDT 2015
|
||||||
|
[INFO] Final Memory: 17M/171M
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1]...
|
||||||
|
</screen></para>
|
||||||
|
<para>Like validation errors, three key pieces of information are again provided:</para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>The full path and filename of our failure is
|
||||||
|
<literal>/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml</literal>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>The location within the file of the error is "<literal>lineNumber: 55; columnNumber: 17</literal>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>An explanation of the failure begins with the text, "The element type "para" must be terminated by the matching end-tag "</para>."</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
<para>With these details in hand for either error, one simply locates the offending syntax and makes the appropriate correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
|
||||||
|
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,54 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_existing_document">
|
||||||
|
|
||||||
|
<title>Modifying an existing document</title>
|
||||||
|
<para>To obtain a copy of the existing template document framework and all public documents from the
|
||||||
|
public OpenPOWER git repository, simply clone the project using this command:<screen><prompt>$</prompt><userinput>git clone https://github.com/open-power/openpower-foundation-docbkx-framework.git</userinput>
|
||||||
|
Cloning into 'openpower-foundation-docbkx-framework'...
|
||||||
|
remote: Counting objects: 288, done.
|
||||||
|
remote: Compressing objects: 100% (157/157), done.
|
||||||
|
remote: Total 288 (delta 121), reused 288 (delta 121)
|
||||||
|
Receiving objects: 100% (288/288), 12.41 MiB | 8.04 MiB/s, done.
|
||||||
|
Resolving deltas: 100% (121/121), done.
|
||||||
|
Checking connectivity... done.
|
||||||
|
<prompt>~$</prompt></screen></para>
|
||||||
|
|
||||||
|
<para>To build a document such as the template guide, follow these steps from the directory where you just cloned:<screen><prompt>$</prompt><userinput>cd openpower-foundation-docbkx-framework/doc/template</userinput>
|
||||||
|
<prompt>$</prompt><userinput>mvn clean</userinput>
|
||||||
|
[INFO] Scanning for projects...
|
||||||
|
[INFO]
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO]
|
||||||
|
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide ---
|
||||||
|
[INFO] Deleting ~/openpower-foundation-docbkx-framework/doc/template/target
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] BUILD SUCCESS
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Total time: 0.353s
|
||||||
|
[INFO] Finished at: Wed Feb 25 12:54:47 CST 2015
|
||||||
|
[INFO] Final Memory: 3M/7M
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
<prompt>$</prompt><userinput>mvn generate-sources</userinput>
|
||||||
|
[INFO] Scanning for projects...
|
||||||
|
[INFO]
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO]
|
||||||
|
[INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---
|
||||||
|
[INFO] Processing input file: bk_main.xml
|
||||||
|
...
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] BUILD SUCCESS
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Total time: 20.361s
|
||||||
|
[INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015
|
||||||
|
[INFO] Final Memory: 30M/390M
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
<prompt>$</prompt></screen></para>
|
||||||
|
<para>If all goes well, the generated pdf should be available in <literal>~/openpower-foundation-docbkx-framework/doc/template/target/docbkx/webhelp/template-guide/</literal>.</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,18 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_faq">
|
||||||
|
|
||||||
|
<title>Frequently asked questions</title>
|
||||||
|
<para>The list of questions and answers may be helpful to first time document writers:</para>
|
||||||
|
<qandaset defaultlabel="qanda"><?dbhtml toc="0" ?>
|
||||||
|
<qandaentry>
|
||||||
|
<question><para>Do I have to follow the guidelines in <xref linkend="section_template_policies"/> of this guide?</para></question>
|
||||||
|
<answer><para>No. <emphasis>HOWEVER</emphasis>, doing so makes it simpler for all community members to participate in maintaining your document.</para></answer>
|
||||||
|
</qandaentry>
|
||||||
|
<qandaentry>
|
||||||
|
<question><para>Question 2...</para></question>
|
||||||
|
<answer><para>Answer 2...</para></answer>
|
||||||
|
</qandaentry>
|
||||||
|
</qandaset>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,61 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_started">
|
||||||
|
|
||||||
|
<title>Getting started</title>
|
||||||
|
<para>To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Install tools</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Create accounts</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Once complete, you can proceed to either <xref linkend="section_template_new_document"/> or
|
||||||
|
<xref linkend="section_template_existing_document"/> as needed.</para>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Installing tools</title>
|
||||||
|
<para>Only two tools are required to update documentation, git and maven. Git manages the documentation
|
||||||
|
source and maven provides the build framework to create the published content in PDF and html form.
|
||||||
|
Installation steps for these tools varies by operating system.</para>
|
||||||
|
<para>On Debian-based Linux operating systems (Ubuntu and Debian), install maven and git as follows:
|
||||||
|
<screen><prompt>$</prompt><userinput>sudo apt-get install git</userinput>
|
||||||
|
<prompt>$</prompt><userinput>sudo apt-get install maven</userinput></screen></para>
|
||||||
|
<para>On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows:
|
||||||
|
<screen><prompt>$</prompt><userinput>sudo yum install git</userinput>
|
||||||
|
<prompt>$</prompt><userinput>sudo yum install maven</userinput></screen></para>
|
||||||
|
<para>On Mac OS X, use Macports to install maven and git as follows:
|
||||||
|
<screen><prompt>$</prompt><userinput>sudo port install git</userinput>
|
||||||
|
<prompt>$</prompt><userinput>sudo port install maven3</userinput></screen></para>
|
||||||
|
<para>or use Homebrew to install maven and git as follows:
|
||||||
|
<screen><prompt>$</prompt><userinput>brew install git</userinput>
|
||||||
|
<prompt>$</prompt><userinput>brew install maven</userinput></screen></para>
|
||||||
|
<para>For information on how to setup the environment on Windows, see the following websites:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>git for Windows - <link xlink:href="http://msysgit.github.io/">http://msysgit.github.io/</link></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Maven on Windows - <link xlink:href="http://maven.apache.org/guides/getting-started/windows-prerequisites.html">
|
||||||
|
http://maven.apache.org/guides/getting-started/windows-prerequisites.html</link></para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Creating accounts</title>
|
||||||
|
<para>All OpenPOWER project documentation is maintained in GitHub trees, public and private. To join the GitHub community,
|
||||||
|
apply at <link xlink:href="https://github.com/join">https://github.com/join</link>.</para>
|
||||||
|
<para>If you will be participating in private OpenPOWER Foundation trees, you will need to visit the OpenPOWER Foundation Members
|
||||||
|
Area wiki to find administrators for the appropriate git tree.</para>
|
||||||
|
<para>To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at
|
||||||
|
<link xlink:href="https://help.github.com/articles/good-resources-for-learning-git-and-github/">
|
||||||
|
https://help.github.com/articles/good-resources-for-learning-git-and-github/</link>.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,122 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_new_document">
|
||||||
|
|
||||||
|
<title>Creating a new document</title>
|
||||||
|
<para>Creating a new document from scratch follows four simple steps:</para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Clone the appropriate template document framework.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Copy the template directory into a new project directory.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Modify core project files.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Begin adding document content, either from scratch or from another document.</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Cloning the base document framework</title>
|
||||||
|
<para>All new projects need to begin by cloning the appropriate documentation template. The template document project resides at <link xlink:href="https://github.com/open-power/openpower-foundation-docbkx-framework.git">https://github.com/open-power/openpower-foundation-docbkx-framework.git</link>. This template should be used for both private and public OpenPOWER Foundation documents.</para>
|
||||||
|
<para>To clone the existing template document framework use the clone git command:<screen><prompt>$</prompt><userinput>git clone https://github.com/open-power/openpower-foundation-docbkx-framework.git</userinput>
|
||||||
|
Cloning into 'openpower-foundation-docbkx-framework'...
|
||||||
|
remote: Counting objects: 288, done.
|
||||||
|
remote: Compressing objects: 100% (157/157), done.
|
||||||
|
remote: Total 288 (delta 121), reused 288 (delta 121)
|
||||||
|
Receiving objects: 100% (288/288), 12.41 MiB | 8.04 MiB/s, done.
|
||||||
|
Resolving deltas: 100% (121/121), done.
|
||||||
|
Checking connectivity... done.
|
||||||
|
<prompt>$</prompt></screen></para>
|
||||||
|
<para>This command clones the head of the git tree into your current working directory. If successful, the contents of the current directory should now include a new <literal>openpower-foundation-docbkx-framework</literal> directory.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Copying the template directory into a new project directory</title>
|
||||||
|
<para>To create a new document directory, follow these steps:</para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>Navigate down to the <literal>doc</literal> sub-directory. On Linux and Mac OS command lines, this can be achieved using the <literal>cd</literal> command:
|
||||||
|
<screen><prompt>$</prompt><userinput>cd /openpower-foundation-docbkx-framework/doc</userinput>
|
||||||
|
<prompt>$</prompt></screen></para>
|
||||||
|
<para>This directory should contain at least two directories, one named <literal>doc</literal> and another <literal>template</literal>, as well as a <literal>pom.xml</literal> file.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>To create a new project directory, simply create a new directory and copy the contents of the <literal>template</literal> directory. If creating a new project named <literal>my_proj</literal> via a command line in Linux or Mac OS, the command sequence would look like this:
|
||||||
|
<screen><prompt>$</prompt><userinput>mkdir my_proj</userinput>
|
||||||
|
<prompt>$</prompt><userinput>cp -r template/* my_proj</userinput>
|
||||||
|
<prompt>$</prompt></screen></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Finally, make sure to add the new directory to the git repository.
|
||||||
|
<screen><prompt>$</prompt><userinput>git add my_proj</userinput></screen></para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Modifying core project files</title>
|
||||||
|
<para>The first step to customizing a new project is to modify two core project files--<literal>pom.xml</literal> and <literal>bk_main.xml</literal>. Within these two files are XML comment tags that begin "<literal><!-- TODO:</literal>" to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how it may be changed. Simply work through each item, making updates as requested.</para>
|
||||||
|
<note><para>Be sure to remember two key values you used in the <literal>pom.xml</literal> file, <literal><webhelpDirname></literal> and <literal><pdfFilenameBase></literal>, as these will be used to locate your generated document.</para></note>
|
||||||
|
<para>When complete, be sure to build your new document using standard maven commands like this:<screen><prompt>$</prompt><userinput>cd openpower-foundation-docbkx-framework/doc/template</userinput>
|
||||||
|
<prompt>$</prompt><userinput>mvn clean</userinput>
|
||||||
|
[INFO] Scanning for projects...
|
||||||
|
[INFO]
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO]
|
||||||
|
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide ---
|
||||||
|
[INFO] Deleting ~/openpower-foundation-docbkx-framework/doc/my_proj/target
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] BUILD SUCCESS
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Total time: 0.353s
|
||||||
|
[INFO] Finished at: Wed Feb 25 12:54:47 CST 2015
|
||||||
|
[INFO] Final Memory: 3M/7M
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
<prompt>$</prompt><userinput>mvn generate-sources</userinput>
|
||||||
|
[INFO] Scanning for projects...
|
||||||
|
[INFO]
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO]
|
||||||
|
[INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---
|
||||||
|
[INFO] Processing input file: bk_main.xml
|
||||||
|
...
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] BUILD SUCCESS
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
[INFO] Total time: 20.361s
|
||||||
|
[INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015
|
||||||
|
[INFO] Final Memory: 30M/390M
|
||||||
|
[INFO] ------------------------------------------------------------------------
|
||||||
|
<prompt>$</prompt></screen></para>
|
||||||
|
<para>If all goes well, the new generated pdf should be available in <literal>target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf</literal>.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Adding new content</title>
|
||||||
|
<para>The starting point for book content is the <literal>bk_main.xml</literal> file (or whatever to which it was renamed in the previous step). Removal and additions of the main chapter files files will be controlled by entries near the end of that file which appear as follows:<programlisting><![CDATA[ <!-- The ch_preface.xml file is required by all documents -->
|
||||||
|
<xi:include href="../common/ch_preface.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: Add your chapter heading files here. Remove both files and insert your own. -->
|
||||||
|
<!-- See the template document for naming conventions and location of files. -->
|
||||||
|
<xi:include href="ch_template_overview.xml"/>
|
||||||
|
<xi:include href="ch_example.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: The following appendices are optional but highly recommended. You may add others as needed. -->
|
||||||
|
<xi:include href="../common/app_foundation.xml"/>
|
||||||
|
|
||||||
|
<!-- TODO: The following template document may be modified to create additional appendices -->
|
||||||
|
<xi:include href="app_template.xml"/>
|
||||||
|
]]></programlisting></para>
|
||||||
|
<para>Copying and modifying existing files from the template or other documents is a great way to get started. When creating whole new chapter or appendix files from scratch, the <literal>ch_example.xml</literal> and <literal>app_template.xml</literal> files may serve as excellent starting points. For XML examples of various document structures, please see <xref linkend="section_template_examples"/> and its supporting source files in this document. Online resources such as those listed in <xref linkend="section_template_references"/> may also be helpful.</para>
|
||||||
|
<note><para>When creating new files for the project, remember to use the <literal>git add <file name></literal> command to add new files to the git tree.</para></note>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,30 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies">
|
||||||
|
|
||||||
|
<title>Policies and conventions</title>
|
||||||
|
<para>Most document style policies are established simply by using the template documentation framework. However, by applying some conventions to the document source structure, community members will be able to work across more documentation projects.</para>
|
||||||
|
<para>The recommended documentation structure guidelines are as follows:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>The head book file should be named with the prefix "bk_".</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>The document versioning as defined by the <literal>releaseinfo</literal> tag in the main book file <literal>bk_xxx</literal> should be named "Revision N.N", not "Version N.N" or simply "N.N"</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Chapters files should be named with the prefix "ch_".</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Section and sub-section files should be named with the prefix "sec_".</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Appendix files should be named with the prefix "app_".</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Figures source and images should be placed in the <literal>figures</literal> sub-directory for the document.</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
@ -0,0 +1,22 @@
|
|||||||
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_references">
|
||||||
|
|
||||||
|
<title>Where to find more information</title>
|
||||||
|
<para>The following lists of references may be helpful in learning about XML, Docbook, and/or Maven:</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para><citetitle>XML In a Nutshell</citetitle> by Elliotte Rusy Harold and W. Scott Means. Online at <link xlink:href="http://docstore.mik.ua/orelly/xml/xmlnut/index.htm">http://docstore.mik.ua/orelly/xml/xmlnut/index.htm</link>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><citetitle>DocBook 5: The Definitive Guide</citetitle> by Normal Walsh. Online at <link xlink:href="https://www.safaribooksonline.com/library/view/docbook-5-the/9781449380243/">https://www.safaribooksonline.com/library/view/docbook-5-the/9781449380243/</link>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><citetitle>DocBook XSL: The Complete Guide</citetitle> by Bob Stayton. Online at <link xlink:href="http://www.sagehill.net/docbookxsl/">http://www.sagehill.net/docbookxsl/</link>.</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><citetitle>Maven: The Complete Reference</citetitle> by Tim O'Brien, Manfred Moser, John Casey, Brian Fox, Jason Van Zyl, Eric Redmond, and Larry Shatzer. Online at <link xlink:href="http://books.sonatype.com/mvnref-book/reference/index.html">http://books.sonatype.com/mvnref-book/reference/index.html</link>.</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
Loading…
Reference in New Issue