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.
207 lines
14 KiB
XML
207 lines
14 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>
|
|
<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/template</userinput>
|
|
<prompt>Docs-Template/template$ </prompt></screen></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Build the document in Maven.<screen><prompt>Docs-Template/template$ </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
|
|
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
Parsing: /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html
|
|
...snip...
|
|
The created index files are located in /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/search/.js
|
|
[INFO] See /home/scheel/mydocs/Docs-Template/template/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/template$ </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/template$ </prompt><userinput>cd target/docbkx/webhelp/</userinput>
|
|
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>ls</userinput>
|
|
doc-devel-guide
|
|
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>cd doc-devel-guide</userinput>
|
|
<prompt>Docs-Template/template/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>
|
|
|