systemsoftware
/
Programming-Guides
34
1
Fork 0
Code Issues 17 Pull Requests Projects Releases Wiki Activity

Delete a number of unused files.

Browse Source 
Signed-off-by: Bill Schmidt <wschmidt@linux.ibm.com>
pull/30/head
Bill Schmidt 7 years ago
parent 3e314a6241
commit ee6fa970de
10 changed files with 0 additions and 1272 deletions
Show Stats Download Patch File Download Diff File

228
Intrinsics_Reference/sec_template_debugging.xml
Unescape Escape View File

@ -1,228 +0,0 @@
<!--
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_debug">

<title xml:id="section_template_debug_title">Debugging build failures</title>
<para>Maven/docbkx failures generally fall into these categories:</para>
<itemizedlist>
<listitem><para><xref linkend="section_template_debug_structure_error" endterm="section_template_debug_structure_error_title"/></para></listitem>
<listitem><para><xref linkend="section_template_debug_docbook_validation_error" endterm="section_template_debug_docbook_validation_error_title"/></para></listitem>
<listitem><para><xref linkend="section_template_debug_build_failure" endterm="section_template_debug_build_failure_title"/></para></listitem>
<listitem><para><xref linkend="section_template_debug_fo_validation_error" endterm="section_template_debug_fo_validation_error_title"/></para></listitem>
</itemizedlist>
<para>Correcting the document errors starts with understanding which type of failure has occurred and
understanding where to look in your document source.</para>
<section xml:id="section_template_debug_structure_error">
<title xml:id="section_template_debug_structure_error_title">Project structure errors</title>
<para>Because the OpenPOWER Foundation documentation projects are not self-contained in the
GitHub repositories, forgetting to clone the <literal>Docs-Master</literal> project in addition
to the document project or cloning it in the wrong location is a common problem. Failures of this kind
produce the following error:</para>
<screen>...
[INFO] Scanning for projects...
[ERROR] The build could not read 1 project -> [Help 1]
[ERROR]
[ERROR] The project org.openpowerfoundation.docs:workgroup-pom:1.0.0-SNAPSHOT (/home/scheel/Docs-Template/pom.xml) has 1 error
[ERROR] Non-resolvable parent POM: Could not find artifact org.openpowerfoundation.docs:master-pom:pom:1.0.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM @ line 6, column 11 -> [Help 2]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException
[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/UnresolvableModelException
...</screen>
<para>The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the
<literal>pom.xml</literal> file in the documentation project, called the "workgroup-pom" because of a project
<literal>&lt;artifactId>workgroup-pom&lt;/artifactId></literal> declaration, expects its parent pom file to be in the
location defined by the <literal>&lt;relativePath>../Docs-Master/pom.xml&lt;/relativePath></literal>, up one directory and
then in the <literal>Docs-Master</literal> director.
</para>
<para>So, if you see the message "Non-resolvable parent POM", ensure that the <literal>Docs-Master</literal> project
and your project have been cloned
into the same parent directory. See <xref linkend="section_cloning_master_doc"/> for detailed directions on how to do this.</para>
</section>

<section xml:id="section_template_debug_docbook_validation_error">
<title xml:id="section_template_debug_docbook_validation_error_title">Docbook validation errors</title>
<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/Docs-Template/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/Docs-Template/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>
</section>

<section xml:id="section_template_debug_build_failure">
<title xml:id="section_template_debug_build_failure_title">Build failures</title>
<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 "&lt;/para&gt;". -> [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/Docs-Template/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 "&lt;/para&gt;."</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>

<section xml:id="section_template_debug_fo_validation_error">
<title xml:id="section_template_debug_fo_validation_error_title">FO validation failures</title>
<para>FO (formatting objects) validation failures are a slight bit more difficult to identify and require more effort to correct. A sample appears as follows:
<screen>...
Error
SXCH0003: org.apache.fop.fo.ValidationException:
"{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!
(See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not
a valid child of "fo:list-block"! (See position 70:-1)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 35.900s
[INFO] Finished at: Sat Mar 19 15:54:34 CDT 2016
[INFO] Final Memory: 107M/256M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.3:generate-webhelp (generate-webhelp) on project hwarch-caia-spec: Failed to transform to PDF: org.apache.fop.fo.ValidationException: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1) -> [Help 1]
...</screen></para>

<para>The "<literal>org.apache.fop.fo.ValidationException</literal>" text indicates that this error was during FO validation. The key pieces of information are as follows:</para>
<orderedlist>
<listitem>
<para>The error type is indicated in the text following the exception indictor. In our case, the error statement is:
<literal>"{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!</literal>. This error clearly
has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement.</para>
</listitem>
<listitem>
<para>The location of the validation error is given in the statement
"<literal>See position 70:-1</literal>". These two values are the line number and character number of the error. So, our sample
error occurs on line 70, but the character number
of <literal>-1</literal> is an indication that the line is too long to effectively point.</para>
</listitem>
</orderedlist>

<para>What this information fails to detail is which file has the problem. To find the particular offending file, one must understand
the Docbook build process. This process begins by collecting all XML into a working copy of the main book file. The build failure error
in <xref linkend="section_template_debug_docbook_validation_error"/> includes a reference to this file which will be found in the
<literal>.../target/</literal> directory. It generally has the same name as the main book file of the document, which if copied
from the <citetitle>Master Template Guide</citetitle> project, will be <literal>bk_main.xml</literal>. When in doubt about
this file name, you will find it in the <literal>&lt;includes></literal> tag in the <literal>pom.xml</literal> file.</para>
<para>Once all information has been pulled into the working XML file, the XML statements are transformed into FO statements
in preparation for building the PDF. This step generates a <literal>.fo</literal>
file which can be found in the <literal>.../target/docbkx/autopdf/</literal> directory and typically has the same base file name as
the target PDF file. Again, the <literal>pom.xml</literal> file will clarify this name with the <literal>&lt;pdfFilenameBase></literal>
variable.</para>
<para>If one locates and opens the .fo file, it becomes obvious that it was intended as a working file and is not readily readable. Therefore, the first
step to understanding this error is to make the FO file more readable.
The <literal>xmllint</literal> tool can be used to create a more readable FO file. Assuming you have been
working in the document directory, the follow steps can be used to produce a more readable XML file:
<screen><prompt>$ </prompt><userinput>cd target/docbkx/autopdf</userinput>
<prompt>$ </prompt><userinput>xmllint --nonet --noent --nowarning --version --timing --format -o outfile infile</userinput>
xmllint: using libxml version 20901
compiled with: Threads Tree Output Push Reader Patterns Writer SAXv1 FTP HTTP DTDValid HTML Legacy C14N Catalog XPath XPointer XInclude Iconv ISO8859X Unicode Regexps Automata Expr Schemas Schematron Modules Debug Zlib Lzma
Parsing took 63 ms
Saving took 39 ms
Freeing took 9 ms
<prompt>$</prompt></screen></para>

<para>For your invocation of <literal>xmllint</literal>, substitute <literal>infile</literal> with the name of the Maven-generated
.fo file for your new project and pick a new <literal>outfile</literal> for the new .fo file.</para>

<note><para>The <literal>xmllint</literal> utility may need to be loaded on your system. On an Ubuntu Linux system,
this utility is provided in the <literal>libxml2-utils</literal> package. To locate the proper package for your system,
you may need to reference Google.</para></note>

<para>Now, with a nicely formatted FO file, we can re-invoke the FO Processor (FOP) directly and achieve a more readable error. To do this, invoke
<literal>fop</literal> as follows:<screen><prompt>$ </prompt><userinput>fop -fo fofile and -pdf pdffile</userinput>
Rendered page #1.
Rendered page #2.
Rendered page #3.
Rendered page #4.
Rendered page #5.
Rendered page #6.
Rendered page #7.
Exception
javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: "fo:block" is not a valid child of "fo:list-block"! (See position 7830:112)
<prompt>$</prompt></screen></para>

<para>As expected, the FOP again reports an exception. However, this time the position information appears more complete. With this new information
and a nicely formatted .fo file, one can find the format statements in error, find the context for the error, and then locate the correct source
DocBook (XML) file. With this information, one can inspect the document source to decide if the error is bad DocBook syntax or a tooling bug. If the latter,
please save the newly formatted .fo file and include it in the bug writeup.</para>
<note><para>Fully understanding the error, may require knowing more about XSL FO syntax. Many such web sites exist for this, but
the <citetitle>XSL Formatting Objects Summary</citetitle> from W3C (World Wide Web Consortium) provides a good starting reference online at
<link xlink:href="https://www.w3.org/2002/08/XSLFOsummary.html">https://www.w3.org/2002/08/XSLFOsummary.html</link>.</para></note>

</section>
</section>

95
Intrinsics_Reference/sec_template_existing_document.xml
Unescape Escape View File

@ -1,95 +0,0 @@
<!--
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_existing_document">

<title xml:id="section_template_existing_document_title">Modifying an existing document</title>

<para>To begin editing an existing document, you must first clone two projects -- the master document framework project and
the specific document project. Begin by cloning the master document as described in <xref linkend="section_cloning_master_doc"/>.</para>
<para>Once complete, obtain a copy of the desired document by cloning its project. For example, to clone this document,
<citetitle>Master Template Guide</citetitle>, from the
public OpenPOWER Foundation git repository, use this
command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
Username for 'https://github.com': <userinput>my_userid</userinput>
Password for 'https://my_userid@github.com': <userinput>my_password</userinput>
remote: Counting objects: 62, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52
Unpacking objects: 100% (62/62), done.
Checking connectivity... done.
<prompt>$ </prompt></screen></para>

<para>To build a specific document such as the template guide, follow these steps from the directory where
you just cloned:<screen><prompt>$ </prompt><userinput>cd Docs-Template/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 ~/Docs-Template/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>

<note><para>The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order
in which one wishes to execute them. Thus, the command <literal>mvn clean generate-sources</literal> would accomplish the
same thing as the above sequence of commands.</para></note>

<para>If all goes well, the generated pdf should be available in <literal>~/Docs-Template/template/target/docbkx/webhelp/template-guide/</literal>.</para>

<para>For assistance correcting commmon build failures, see <xref linkend="section_template_debug"/>.</para>

<note><para>Projects may contain multiple documents. While specific documents can be built by executing a
<literal>mvn clean generate-sources</literal> in the specific document directory, executing this command in
the base project directory will build all projects identified in the <literal>&lt;module></literal> list in the
top-level <literal>pom.xml</literal> file, known as the "workgroup-pom".</para></note>
<para>You are now ready to begin making updates. Before diving deeply into new text,
you may want to review
<xref linkend="section_template_process"/> to ensure that proper Work Product,
Work Process, and security values are selected for your document.</para>
</section>

34
Intrinsics_Reference/sec_template_faq.xml
Unescape Escape View File

@ -1,34 +0,0 @@
<!--
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_faq">

<title 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>

105
Intrinsics_Reference/sec_template_getting_started.xml
Unescape Escape View File

@ -1,105 +0,0 @@
<!--
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>Installing tools</para>
</listitem>
<listitem>
<para>Creating accounts</para>
</listitem>
<listitem>
<para>Cloning master document information</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>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_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>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 master template 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>

182
Intrinsics_Reference/sec_template_git_commands.xml
Unescape Escape View File

@ -1,182 +0,0 @@
<!--
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_git_commands">

<title xml:id="section_template_git_commands_title">Common git commands</title>
<para>This section provides a list of commonly used git command invocations. All commands shown, except
the first one (<literal>git clone</literal> must be issued from within the project directory.</para>

<itemizedlist>

<listitem>
<para>To clone a git tree for first time or temporary use via http,
use:<screen><prompt>$ </prompt><userinput>git clone &lt;URL></userinput></screen></para>
<para>The <literal>&lt;URL></literal> value for OpenPOWER Foundation GitHub projects can be found on the project web pages.
They generally take the form of <literal>https://github.com/OpenPOWERFoundation/project_name</literal> where the
<literal>project_name</literal> can be found on the OpenPOWER Foundation Git Hub community page at
<link xlink:href="https://github.com/OpenPOWERFoundation">https://github.com/OpenPOWERFoundation</link>. The result of this
command will be a new directory with the same name as the project and in which will be the project files.</para>
<note><para>Trees can only be cloned once. To update a tree, use a <literal>git pull</literal> or <literal>git merge</literal>
command.</para></note>
<note><para>When cloning from a private tree, you will be prompted for your GitHub userid and password.</para></note>
</listitem>

<listitem>
<para>To update a git tree with new files from the remote repository,
use:<screen><prompt>$ </prompt><userinput>git pull</userinput></screen></para>
<para>This command assumes that the local tree has not been updated since the clone or last pull. If updates have been made to
the local tree, the command will fail. Use the <literal>git status</literal> command to see what has changed in a local tree.</para>
<note><para>When pulling from a private tree, you will be prompted for your GitHub userid and password.</para></note>
</listitem>

<listitem>
<para>To see the status of the local repository,
use:<screen><prompt>$ </prompt><userinput>git status</userinput></screen></para>
<para>This command identifies files which have changed in the local repository and provides suggestions on how to handle.</para>
<note><para>Adding the <literal>-s</literal> parameter to the end of the command will provide a simplified view in which changed files
are listed with flags such as <literal>M</literal> for modified files, <literal>A</literal> for newly added files,
and <literal>??</literal> for new or unknown files. This parameter also suppresses suggested action information for the files.</para></note>
</listitem>

<listitem>
<para>To add a new file or directory to a git tree,
use:<screen><prompt>$ </prompt><userinput>git add &lt;new_file></userinput></screen></para>
<para>The <literal>&lt;new_file></literal> value can be either a file or a whole directory and may include the path to
the target file or directory. This command will convert the status of file in the <literal>git status -s</literal>
command from <literal>??</literal> to <literal>A</literal> or move it from the "Untracked files" section to the
"Changes to be committed" section of the <literal>git status</literal> command.</para>
</listitem>

<listitem>
<para>To remove a file from a git tree,
use:<screen><prompt>$ </prompt><userinput>git rm &lt;file></userinput></screen></para>
<para>The <literal>&lt;file></literal> value must be a file and may include wildcard characters or the path to
the target file. This command will both remove the file(s) from the directory and the git tree. Removed files will show in
a status modifier of <literal>D</literal> in the <literal>git status -s</literal>
command and be reflected in the "Changes not staged for commit" section of the<literal>git status</literal> command
with a "deleted:" status.</para>
</listitem>

<listitem>
<para>To remove a directory from a git tree,
use:<screen><prompt>$ </prompt><userinput>git rm -rf &lt;directory></userinput></screen></para>
<para>The <literal>&lt;directory></literal> value must be a directory name and may include wildcard characters or the path to
the target directory. This command will remove all files in the directory from the git tree, but will not remove the directory locally.
Standard operating system commands such as the Linux <literal>rmdir &lt;directory></literal> command must be issued separately to
remove the local directory. All removed files will show in
a status modifier of <literal>D</literal> in the <literal>git status -s</literal>
command and be reflected in the "Changes not staged for commit" section of the<literal>git status</literal> command with a
"deleted:" status. Because git does not
track directories, they will not be reflected in status.</para>
</listitem>

<listitem>
<para>To move or rename a file or directory in a git tree,
use:<screen><prompt>$ </prompt><userinput>git mv &lt;source> &lt;destination></userinput></screen></para>
<para>The <literal>&lt;source></literal> value must be a file or directory and may include the path to
the target file. The <literal>&lt;destination></literal> value may be a file (if renaming a file) or a directory
if moving a file or directory.
This command will move or rename the file(s) in both the local and remote the git trees.</para>
</listitem>

<listitem>
<para>To commit all local changes to the staging area for a git tree,
use:<screen><prompt>$ </prompt><userinput>git commit -a</userinput></screen></para>
<para>This command will invoke an editor for a commit message. A well-formatted commit message includes a
title on the first line, a blank line, one or more lines of details describing the changes, and a Developer's
Certificate of Orig (DCO) Sign-off statement at the end. <screen>Signed-off-by: Your name &lt;your_email@domain.com></screen></para>
<para>For information on the DCO, see <citetitle>Developer Certificate Of Origin</citetitle> at
<link xlink:href="http://elinux.org/Developer_Certificate_Of_Origin">http://elinux.org/Developer_Certificate_Of_Origin</link>.</para>
</listitem>

<listitem>
<para>To push all locally staged changes to the remote git tree,
use:<screen><prompt>$ </prompt><userinput>git push</userinput></screen></para>
<note><para>When pushing to a private tree, you will be prompted for your GitHub userid and password.</para></note>
</listitem>

<listitem>
<para>To see what tags exist in a git tree,
use:<screen><prompt>$ </prompt><userinput>git tag</userinput></screen></para>
</listitem>

<listitem>
<para>To create a new tag locally,
use:<screen><prompt>$ </prompt><userinput>git tag -a &lt;tag_name> -m"text"</userinput></screen></para>
<para>The <literal>tag_name</literal> represents the simple value of the tag. The <literal>text</literal> string
provides more description of the tag for readibility.</para>
<note><para>This command simply tags locally. See the next command for how to push the tag to the remote repository.</para></note>
</listitem>

<listitem>
<para>To push a new tag from the local tree to the remote tree,
use:<screen><prompt>$ </prompt><userinput>git push origin &lt;tag_name></userinput></screen></para>
<para>This commands assumes the <literal>git tag</literal> command has been run on the local tree.</para>
</listitem>

<listitem>
<para>To discard changes from a locally changed file and return to the last copy,
use:<screen><prompt>$ </prompt><userinput>git checkout -- &lt;file></userinput></screen></para>
<para>The <literal>&lt;file></literal> value must be a file and may include wildcard characters or the path to
the target file.</para>
</listitem>

<listitem>
<para>To identify what changes have been made locally to a file
use:<screen><prompt>$ </prompt><userinput>git diff &lt;file></userinput></screen></para>
<para>The <literal>&lt;file></literal> value must be a file and may include wildcard characters or the path to
the target file. The output will be in format similar to the standalone <literal>diff</literal> command.</para>
</listitem>

</itemizedlist>

<para>Additional resources about git can be found online at the following locations:</para>

<itemizedlist>

<listitem>
<para>The <citetitle>GitHub Glossary</citetitle> at
<link xlink:href="https://help.github.com/articles/github-glossary/">https://help.github.com/articles/github-glossary/</link>.
This site provides a list of common terms associated with git and GitHub.</para>
</listitem>

<listitem>
<para>The GitHub <citetitle>Git Cheat Sheet</citetitle> at
<link xlink:href="https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf">
https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf</link>.
This two page pdf provides a quick summary of many common commands.</para>
</listitem>


<listitem>
<para>The <citetitle>Git Reference</citetitle> at
<link xlink:href="http://gitref.org/">http://gitref.org/</link>. This is a deeper and more comprehensive reference of important commands.</para>
</listitem>

<listitem>
<para>The git-scm.com <citetitle>Documentation</citetitle> library at
<link xlink:href="http://git-scm.com/doc">http://git-scm.com/doc</link>. This site provides education in the form of books, videos,
and other tutorials for common git activities.</para>
</listitem>

</itemizedlist>
</section>

274
Intrinsics_Reference/sec_template_new_document.xml
Unescape Escape View File

@ -1,274 +0,0 @@
<!--
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_new_document">

<title 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>Cloning the project source.</para>
</listitem>
<listitem>
<para>Finding a document framework.</para>
</listitem>
<listitem>
<para>Modifying core project files.</para>
</listitem>
<listitem>
<para>Adding new document content.</para>
</listitem>
</orderedlist>

<section>
<title>Clone the project source.</title>
<para>All documentation projects reside in a project directory maintained in GitHub, just like the
<literal>Docs-Master</literal> framework described in <xref linkend="section_cloning_master_doc"/>. In the same directory
where the <literal>Docs-Master</literal> project has been cloned, you will need to
clone the documentation source for your project. A list of the OpenPOWER Foundation projects can be found at
<link xlink:href="https://github.com/OpenPOWERFoundation/">https://github.com/OpenPOWERFoundation/</link>. Select
the project from this list.</para>
<note><para>If you do not see the project for which you are looking, you may not be authorized to it. See
<xref linkend="section_creating_accounts"/> for details about joining the OpenPOWER Foundation private projects. If you
feel that you need a new GitHub project, work with the
Technical Steering Committee Chair, <email>tsc-chair@openpowerfoundation.org</email>, to request and get this setup.</para></note>
<para>To clone an OpenPOWER Foundation project like <literal>Docs-Template</literal> issue the following
command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
Username for 'https://github.com': <userinput>my_userid</userinput>
Password for 'https://my_userid@github.com': <userinput>my_password</userinput>
remote: Counting objects: 62, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52
Unpacking objects: 100% (62/62), done.
Checking connectivity... done.
<prompt>$ </prompt></screen> The results should look roughly something like above with actual numbers of objects, files, etc. varying
for different projects.</para>

<note><para>Private projects prompt for a GitHub userid and and password. When cloning public projects, these prompts
are skipped.</para></note>
<para>The base project has now been cloned.</para>
</section>
<section>
<title>Finding a document framework</title>
<para>If this is your first document, in a brand new project (git tree), you have the fewest number of steps
to perform because your project should have been primed with a single project based on <literal>Docs-Template</literal>.
You can verify this by inspecting
the files in your project directory. A new project will contain a <literal>template</literal> directory, a <literal>pom.xml
</literal> file, a <literal>LICENSE</literal> file, and a <literal>README.md</literal> file. If this is the case, you simply
need to perform the following three steps:</para>
<orderedlist>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example. This can be achieved
using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain the <literal>template</literal> folder used to prime the project.</para>
</listitem>
<listitem>
<para>Rename the <literal>template</literal> document directory to something new like <literal>my_doc</literal>.
To accomplish this, use the <literal>mv</literal> command::
<screen><prompt>$ </prompt><userinput>mv template/ my_doc</userinput></screen></para>
</listitem>
<listitem>
<para>Change the project name in the workgroup POM.xml file. Using your editor, change this line
between the &lt;modules> and the &lt;/modules> tags near the top of the
file:<programlisting><![CDATA[<module>template</module>
]]></programlisting> to read like this:<programlisting><![CDATA[<module>my_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>
<para>If this is not the first document in the project, then you can either begin by copying an existing document or by cloning the
<literal>Docs-Template</literal> project. To copy an existing project, follow these steps:</para>
<orderedlist>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example.
This can be achieved using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain the folder name of the document wishing to be copied, called <literal>source_doc</literal>
for clarity in these directions.</para>
</listitem>
<listitem>
<para>To create a new document directory, simply create a new directory and copy the contents of the <literal>source_doc</literal>
directory. If creating a new directory named <literal>my_doc</literal> via a command line, the command
sequence would look like this:
<screen><prompt>$ </prompt><userinput>mkdir my_doc</userinput>
<prompt>$ </prompt><userinput>cp -r source_doc/* my_doc</userinput>
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<para>Add the new project to the workgroup POM.xml file. Using your editor, add the following lines
between the &lt;modules> and the &lt;/modules> tags near the top of the file:<programlisting><![CDATA[<module>my_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>
<para>Instead of copying an existing document, you may want to start with the template document source. The steps to do this
are similar to those above, but with a few more commands. The following commands will create a new document based on the
the master template:</para>
<orderedlist>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example.
This can be achieved using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain any existing document folders along with at least a <literal>pom.xml</literal> file, a
<literal>LICENSE</literal> file, and a <literal>README.md</literal> file.</para>
</listitem>
<listitem>
<para>Clone the the template project into your working directory with this
command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
Username for 'https://github.com': <userinput>my_userid</userinput>
Password for 'https://my_userid@github.com': <userinput>my_password</userinput>
remote: Counting objects: 62, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52
Unpacking objects: 100% (62/62), done.
Checking connectivity... done.
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<para>To create a new project directory, simply create a new directory and copy the contents of the <literal>Docs-Template/template</literal>
directory. If creating a new project named <literal>my_doc</literal> via a command line, the command
sequence would look like this:
<screen><prompt>$ </prompt><userinput>mkdir my_doc</userinput>
<prompt>$ </prompt><userinput>cp -r Docs-Template/template/* my_doc</userinput>
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<para>Once copied, the Docs-Template directory and all its contents should be removed from your project so that it does not
accidentally get included in your project. The command <userinput>rm -rf Docs-Template</userinput></para>
</listitem>
<listitem>
<para>Finally, add the new project to the workgroup POM.xml file. Using your editor, add the following lines
between the &lt;modules> and the &lt;/modules> tags near the top of the file:<programlisting><![CDATA[<module>my_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>

<note><para>Before committing the project back to git, you will need to add the new directory to the git repository. This can
be performed using the <literal>git add my_doc/</literal> command on the whole directory.</para></note>

<warning><para></para></warning>
<para>You are now ready to begin making updates to your new document. The next section will provided detailed steps of where to
get started.</para>
</section>

<section xml:id="section_modifying_project">
<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>&lt;!-- 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>
<para>Pick your setting for document work product type (<literal>&lt;workProduct></literal>,
work flow status (<literal>&lt;documentStatus></literal>), and
security (<literal>&lt;security></literal>)
carefully. <xref linkend="section_template_process"/> provides an overview of the process
and details the various settings needed in the document core project files. If you still have
questions after reading this section, consult with your Technical Steering Committee
representative.</para>
<note><para>Be sure to remember two key values you used in the <literal>pom.xml</literal> file, <literal>&lt;webhelpDirname&gt;</literal>
and <literal>&lt;pdfFilenameBase&gt;</literal>, as these will be used to locate your generated document.</para></note>
<para>When ready, build your new document using standard maven commands like
this:<screen><prompt>$ </prompt><userinput>cd my_proj/my_doc</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 ~/my_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/&lt;webhelpDirname&gt;/&lt;pdfFilenameBase&gt;.pdf</literal>.</para>
<para>For assistance correcting commmon build failures, see <xref linkend="section_template_debug"/>.</para>
<note><para>The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order
in which one wishes to execute them. Thus, the command <literal>mvn clean generate-sources</literal> would accomplish the
same thing as the above sequence of commands.</para></note>
</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 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="../../Docs-Master/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"/>

<!-- The app_foundation.xml appendix file is required by all documents. -->
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>

<!-- TODO: The following template document may be modified to create additional appendices as needed. -->
<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 &lt;file name&gt;</literal> command to
add new files to the git tree.</para></note>

</section>

</section>

59
Intrinsics_Reference/sec_template_policies.xml
Unescape Escape View File

@ -1,59 +0,0 @@
<!--
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_policies">

<title 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 d
ocumentation 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>
<para>In addition to documentation structure, general community/project guidelines are as follows:
<orderedlist>
<listitem>
<para>Contributions to the documentation projects should conform to the <citetitle>Developer Certificate
Of Origin</citetitle> as defined at <link xlink:href="http://elinux.org/Developer_Certificate_Of_Origin">
http://elinux.org/Developer_Certificate_Of_Origin</link>. Commits to the GitHub project need
to contain the following line to indicate the submitter accepts the
DCO:<screen>Signed-off-by: Your name &lt;your_email@domain.com></screen></para>
</listitem>
</orderedlist>
</para>

</section>

169
Intrinsics_Reference/sec_template_process.xml
Unescape Escape View File

@ -1,169 +0,0 @@
<!--
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_process">

<title xml:id="section_template_process_title">Publishing OpenPOWER Documents</title>
<para>The <citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document
found in the OpenPOWER Foundation Members Community documents is the definitive guide for understanding
OpenPOWER Foundation documents and their work flow. The section strives to
provide an overview to help writers understand enough of the basics to know how to prepare their
document and what to expect as they proceed through various stages of document development from first
draft to specification publish.</para>
<para>The first key concept to understand about OpenPOWER Foundation documents and the first
decision to make when creating a new document is available document types or "Work Products".
These fall into one of two categories -- Standards Track or Non-standards Track -- with the simple
distinguishing factor being use. If the purpose of a document is to define a specification or standard
for hardware or software, then the document is "Standards Track". Everything else is "Non-standards
Track." For example, this document is a non-stardard work product.</para>
<para>Standards Track Work Products begin their life as Work Group Specification and may ultimately
become an OpenPOWER Standard. Their document lifecycle is defined in the following illustration:</para>

<figure pgwide="1" xml:id="project_process_std_track_label">
<title>Document work flow for Standard Track Work Products</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_process_std_track_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>

<para>Standard Track Work Products begin their lives as Work Group Specifications and have security classifications
of Public (non-confidental),
Members-only (OpenPOWER Foundation Confidental), or Work Group-only (OpenPOWER Work Group Confidential).
The security classification impacts the review type -- either public or internal to the Foundation -- as appropriate.
Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential
documents will remain Work Group Specifications.</para>
<para>Non-standard Track Work Products exist simply as Work Group Notes. Their document
lifecycle follows this simplified workflow:</para>
<figure pgwide="1" xml:id="project_process_non-std_track_label">
<title>Document work flow for Non-standard Track Work Products</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_process_non-std_track_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>

<para>Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. Like
Standard Track Work Products, they may have security classifications as Public (non-confidential), Members-only
(OpenPOWER Foundation Confidential), or Work-Group only (OpenPOWER Work Group Confidential) which will
in turn dictate the review context (public or private).</para>
<para>Once these decisions have been made, then they can be reflected into the document in the following ways:</para>
<orderedlist>

<listitem>
<para>The document Work Product type is defined in the document <literal>pom.xml</literal> file with the
<literal>&lt;workProduct></literal> variable. Valid settings are <literal>workgroupNotes</literal>,
<literal>workgroupSpecification</literal>, <literal>candidateStandard</literal>, and <literal>openpowerStandard</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- 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 -->]]></programlisting></para>
</listitem>

<listitem>
<para>The document security is set in the document <literal>pom.xml</literal> file with the
<literal>&lt;security></literal> variable. Valid settings are <literal>public</literal>,
<literal>foundationConfidential</literal>, and <literal>workgroupConfidential</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- TODO: Set the appropriate security policy for the document. For documents
which are not "public" this will affect the document title page and
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:

public = this document may be shared outside the
foundation and thus this setting must be
used only when completely sure it allowed
foundationConfidential = this document may be shared freely with
OpenPOWER Foundation members but may not be
shared publicly
workgroupConfidential = this document may only be shared within the
work group and should not be shared with
other Foundation members or the public

The appropriate starting security for a new document is "workgroupConfidential". -->
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->]]></programlisting></para>
</listitem>

<listitem>
<para>The document work flow status is set in the document <literal>pom.xml</literal> file with the
<literal>&lt;documentStatus></literal> variable. Valid settings are <literal>draft</literal>,
<literal>review</literal>, and <literal>published</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and 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:

published = this document has completed all reviews and has
been published
draft = this document is actively being updated and has
not yet been reviewed
review = this document is presently being reviewed

The appropriate starting security for a new document is "draft". -->
<documentStatus>draft</documentStatus>
<!-- documentStatus>review</documentStatus -->
<!-- documentStatus>publish</documentStatus -->]]></programlisting></para>
</listitem>

<listitem>
<para>The final place to make updates to a new document is in the <literal>&lt;abstract></literal> section of
the <literal>bk_main.xml</literal> file for the document. This section needs to be updated with the appropriate
work group information and document information. Typical text appears as follows:
<programlisting><![CDATA[<!-- TODO: Update the following text with the correct document description (first
paragraph), Work Group name, and Work Product track (both in second
paragraph). -->
<abstract>
<para>The purpose of the Master Template Guide document is to provide a guide
for OpenPOWER documentation writers. As such, it provides directions, policies,
references, and examples of the XML Docbook environment. It is intended to be
used both in final product form (PDF and html) as a document and in source form
as a template for new documents.</para>
<para>This document is a Non-standard Track, Work Group Note work product
owned by the System Software Workgroup and handled in compliance with the
requirements outlined in the <citetitle>OpenPOWER Foundation Work Group (WG)
Process</citetitle> document.</para>
</abstract>]]></programlisting></para>
<para>As stated in the comment text of the book file, the first paragraph provides a typical abstract
statement about your particular document. The second paragraph provides more structured
text which should be updated with the appropriate Work Group name, Work Product type,
and Work Product process. The rest of the information in this paragraph should remain as-is.</para>
</listitem>

</orderedlist>

</section>

38
Intrinsics_Reference/sec_template_references.xml
Unescape Escape View File

@ -1,38 +0,0 @@
<!--
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_references">

<title xml:id="section_template_references_title">Finding 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>

88
Intrinsics_Reference/sec_template_structure.xml
Unescape Escape View File

@ -1,88 +0,0 @@
<!--
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_structure">

<title xml:id="section_template_structure_title">Understanding the project structure</title>
<para>The OpenPOWER Foundation documentation build process involves dependency on a common
framework and shared files. As such a deeper explanation about the relationships of key projects and their
components may be helpful to prevent and diagnose documentation build problems. This section
provides a pictorial layout of key files and explains their roles and relationships.</para>

<para>As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation
document requires two things:</para>
<orderedlist>
<listitem><para>The cloning of the <literal>Docs-Master</literal> project.</para></listitem>
<listitem><para>The cloning of the specific documentation project into the same parent directory as the
<literal>Docs-Master</literal> project.</para></listitem>
</orderedlist>
<para>To begin to understand why, let us use a picture. The following graphic illustrates
the directory structure of three projects -- two
<literal>Docs-Master</literal> and <literal>Docs-Template</literal>, both existing OpenPOWER Foundation GitHub projects and a
hypothetical new project named <literal>my_project</literal>.</para>
<figure pgwide="1" xml:id="project_structure_label">
<title>Directory structure and key files in the OpenPOWER Foundation Docbook projects</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_structure_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>To create this structure, one would clone the <literal>Docs-Master</literal> project to
get the <literal>Docs-Master</literal> directory and all its contents (shown above in green),
clone the <literal>Docs-Template</literal> project to get the <literal>Docs-Template</literal> directory
and all its contents (shown in blue), and clone <literal>my_project</literal> project to get the
<literal>my_project</literal> directory and all its contents (shown in red).</para>
<para>Among these projects, the most important directory and project is <literal>Docs-Master</literal>. Without this project
and associated directory, no document will build. As depicted in the above figure, the <literal>Docs-Master</literal> directory
must sit at a level equal to all other project directories. Details on how to install this project can be found in the
<xref linkend="section_cloning_master_doc"/> section.</para>
<para>Inside the <literal>Docs-Master</literal>project directory, the two most important pieces are a
<literal>commmon</literal> directory
and a <literal>pom.xml</literal> file. The directory contains common files used by all projects such as the common preface
(<literal>ch_preface.xml</literal>) and the common appendix (<literal>app_foundation.xml</literal>. The <literal>pom.xml</literal> file
in this directory serves as the "Master POM" for all builds. This file references the OpenPOWER Maven Plugin JAR
(found in the OpenPOWER Foundation Repository at
<link xlink:href="http://openpowerfoundation.org/repo.openpowerfoundation.org/">http://openpowerfoundation.org/repo.openpowerfoundation.org/</link>)
used to control the OpenPOWER
Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. </para>

<para>The <literal>Docs-Template</literal> project and directory are depicted in blue in the above figure. The top level of the
project <literal>Docs-Template</literal> must be cloned into the same parent directory as the <literal>Docs-Master</literal>
for Maven builds to complete successfully.
At the top level of the <literal>Docs-Template</literal> project
are a <literal>pom.xml</literal> referred to as the "Workgroup POM" and a single document directory (<literal>template</literal>).
The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the <literal>Docs-Master</literal>project directory
with a <literal>&lt;relativePath></literal> definition of <literal>../Docs-Master/pom.xml</literal>.
The document directory contains the unique files used to create the document. The two most important files in the
<literal>Docs-Template/template</literal> directory(and in any project) are the <literal>pom.xml</literal> or "Document POM" which describes
how to build the document and which points to the main document file, the <literal>bk_main.xml</literal> file. This book file
contains all the Docbook source, directly or through include statements (<literal>&lt;xi:include href="..."</literal>),
to build the document.</para>
<para>For completeness of understanding, a hypothetical project <literal>my_project</literal> is also depected in red. Like all
OpenPOWER Foundation projects, it is cloned at the correct level, equal to <literal>Docs-Master</literal>. Like the
<literal>Docs-Template</literal> project, it has a "Workgroup POM" which will differ only in the <literal>&lt;modules></literal>
section where it will describe two document projects, <literal>my_doc_1</literal> and <literal>my_doc_2</literal>. But, each
document directory has similar contents to <literal>Docs-Template/template</literal> -- a "Document POM" (<literal>pom.xml</literal>)
and a "Main book file" (<literal>bk_main.xml</literal>).</para>
</section>
Write Preview
Loading…
Cancel
Save