CAPI-SNAP-Doc/doc_dev_guide/sec_template_getting_started.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>
        <listitem>
          <para><xref linkend="section_building_first_doc" endterm="section_building_first_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 xml:id="section_building_first_doc">
      <title xml:id="section_building_first_doc_title">Building the first document</title>
      <para>The final step of setting up your environment to perform the first build.  The following steps are recommended:</para>
      <orderedlist>
        <listitem>
          <para>Clone the <citetitle>Documentation Development Guide</citetitle> (this document) as source from which to build.  
          To accomplish this, issue the following command in the same directory as as the master document clone from <xref linkend="section_cloning_master_doc" />.
          <screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
remote: Counting objects: 253, done.
remote: Total 253 (delta 0), reused 0 (delta 0), pack-reused 253
Receiving objects: 100% (253/253), 468.94 KiB | 0 bytes/s, done.
Resolving deltas: 100% (151/151), done.
Checking connectivity... done.
<prompt>$ </prompt></screen></para>
        </listitem>
        <listitem>
          <para>Change the working directory into the source directory for the <citetitle>Documentation Development Guide</citetitle>.
          <screen><prompt>$ </prompt><userinput>cd Docs-Template/doc_dev_guide</userinput>
<prompt>Docs-Template/doc_dev_guide$ </prompt></screen></para>
        </listitem>
        <listitem>
          <para>Build the document in Maven.<screen><prompt>Docs-Template/doc_dev_guide$ </prompt><userinput>mvn generate-sources</userinput>
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building Documentation Development Guide 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- openpowerdocs-maven-plugin:1.1.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---
[INFO] Processing input file: bk_main.xml
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure
INFO: Default page-height set to: 11in
Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure
 ...snip...
[INFO] Applying customization parameters

&lt;!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
Parsing: /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html
 ...snip...
The created index files are located in /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide/content/search/.js
[INFO] See /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/bk_main for generated file(s)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 31.547 s
[INFO] Finished at: 2018-02-27T11:43:45-06:00
[INFO] Final Memory: 83M/729M
[INFO] ------------------------------------------------------------------------
<prompt>Docs-Template/doc_dev_guide$ </prompt></screen></para>
          <note><para>The first time one builds in a Maven environment, the build time will be noticeably
          long due to JAR file downloads associated with the new Maven project types.  In future builds, these JAR files will 
          only be downloaded when they are updated.  As such, one should both allow for this extra time and not be discouraged 
          by the duration of the first build.</para></note>
        </listitem>
      </orderedlist>
      <para>Once complete, there should be a single directory in the <literal>target/docbkx/webhelp/</literal> directory. For the 
      Docs-Template project, that directory is <literal>doc-devel-guide</literal>.  Inside this directory will
      be both the PDF file and the <literal>index.html</literal> file for the HTML document.</para>
      <para>To verify this for the <citetitle>Documentation Development Guide</citetitle>, perform these commands:
      <screen><prompt>Docs-Template/doc_dev_guide$ </prompt><userinput>cd target/docbkx/webhelp/</userinput>
<prompt>Docs-Template/doc_dev_guide/target/docbkx/webhelp$ </prompt><userinput>ls</userinput>
doc-devel-guide
<prompt>Docs-Template/doc_dev_guide/target/docbkx/webhelp$ </prompt><userinput>cd doc-devel-guide</userinput>
<prompt>Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide$ </prompt><userinput>ls</userinput>
bookinfo.xml  common  content  doc-devel-guide-20180227.pdf  favicon.ico  index.html
webapp</screen></para>
      <para>Now, you are ready to begin working on your own document.  Useful information on how to proceed can
      be found in <xref linkend="section_template_new_document" /> and <xref linkend="section_template_existing_document" />.</para>
    </section>
</section>