You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
128 lines
8.7 KiB
XML
128 lines
8.7 KiB
XML
<!--
|
|
Copyright (c) 2016 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<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 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><xref linkend="section_installing_tools" endterm="section_installing_tools_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_installing_fonts" endterm="section_installing_fonts_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_creating_accounts" endterm="section_creating_accounts_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_cloning_master_doc" endterm="section_cloning_master_doc_title"/></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 xml:id="section_installing_tools">
|
|
<title xml:id="section_installing_tools_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>apt-get install git</userinput>
|
|
<prompt># </prompt><userinput>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>yum install git</userinput>
|
|
<prompt># </prompt><userinput>yum install maven</userinput></screen></para>
|
|
<para>On Mac OS X, use Macports to install maven and git as follows:
|
|
<screen><prompt># </prompt><userinput>port install git</userinput>
|
|
<prompt># </prompt><userinput>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>
|
|
<note><para>Modification of documentation source files requires a text editor. While standard editors like vim, emacs, or gedit can be used,
|
|
it is highly recommended that an editor be used which highlights XML or Docbook syntax. If your favorite editor does not include an
|
|
extension or plugin to accomplish this, you might consider using Bluefish to edit your docbook files. Details on this editor
|
|
can be found at <link xlink:href="http://bluefish.openoffice.nl/index.html">http://bluefish.openoffice.nl/index.html</link>.</para></note>
|
|
</section>
|
|
|
|
<section xml:id="section_installing_fonts">
|
|
<title xml:id="section_installing_fonts_title">Installing fonts</title>
|
|
<para>The OpenPOWER Foundation documentation utilizes opensource fonts known as the
|
|
<emphasis role="bold">Chrome OS core fonts</emphasis> or <emphasis role="bold">Croscore fonts</emphasis>.
|
|
The three TrueType fonts (TTFs) in this family Arimo (sans-serif), Tinos (serif), and Cousine (monospace). While
|
|
not strictly required to have these fonts on your system, it can be helpful when designing graphics and
|
|
other images to have them installed on your development system.</para>
|
|
<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 Croscore fonts as follows:
|
|
<screen><prompt># </prompt><userinput>apt-get install fonts-croscore</userinput></screen></para>
|
|
<para>On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install Croscore fonts as follows:
|
|
<screen><prompt># </prompt><userinput>yum install google-croscore-fonts</userinput></screen></para>
|
|
<para>On Mac OS X and Windows systems, use a font website to download and install the Croscore fonts individually. Most of
|
|
these sites provide directions for Mac OS and Windows.</para>
|
|
</section>
|
|
|
|
<section xml:id="section_creating_accounts">
|
|
<title xml:id="section_creating_accounts_title">Creating accounts</title>
|
|
<para>All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first
|
|
step to creating documentation will be joining the GitHub community.</para>
|
|
<para>To join the GitHub community,
|
|
apply at <link xlink:href="https://github.com/join">https://github.com/join</link>.</para>
|
|
<para>The OpenPOWER Foundation documentation trees are grouped in the OpenPOWER Foundation project at
|
|
<link xlink:href="https://github.com/OpenPOWERFoundation">https://github.com/OpenPOWERFoundation</link>.
|
|
Everyone should be able to see and access public trees like Docs-Master. However,
|
|
if you will be participating in private OpenPOWER Foundation trees, you will need to request access from the
|
|
Technical Steering Committee Chair, <email>tsc-chair@openpowerfoundation.org</email>.</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 xml:id="section_cloning_master_doc">
|
|
<title xml:id="section_cloning_master_doc_title">Cloning master document information</title>
|
|
<para>To successfully build OpenPOWER Foundation documents, common document files must be in place in addition to the specific
|
|
document files. These common files are obtained by cloning the OpenPOWER Foundation public project <literal>Docs-Master</literal>.</para>
|
|
<para>To clone the OpenPOWER Foundation master document framework,
|
|
use the clone git command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Master.git</userinput>
|
|
Cloning into 'Docs-Master'...
|
|
remote: Counting objects: 24, done.
|
|
remote: Compressing objects: 100% (18/18), done.
|
|
remote: Total 24 (delta 6), reused 20 (delta 5), pack-reused 0
|
|
Unpacking objects: 100% (24/24), done.
|
|
Checking connectivity... done.
|
|
<prompt>$ </prompt></screen></para>
|
|
<para>More information can be found about the Docs-Master project online at <link xlink:href="https://github.com/OpenPOWERFoundation/Docs-Master">
|
|
https://github.com/OpenPOWERFoundation/Docs-Master</link>. Additional details about the OpenPOWER Foundation documentation structure
|
|
are explained in <xref linkend="section_template_structure"/> of this document.</para>
|
|
</section>
|
|
</section>
|
|
|