Delete a number of unused files.
Signed-off-by: Bill Schmidt <wschmidt@linux.ibm.com>pull/69/head
parent
dd96775379
commit
0913542a05
@ -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><artifactId>workgroup-pom</artifactId></literal> declaration, expects its parent pom file to be in the
|
|
||||||
location defined by the <literal><relativePath>../Docs-Master/pom.xml</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 "</para>". -> [Help 1]
|
|
||||||
...</screen></para>
|
|
||||||
|
|
||||||
<para>Like validation errors, three key pieces of information are again provided:</para>
|
|
||||||
<orderedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>The full path and filename of our failure is
|
|
||||||
<literal>/home/user1/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 "</para>."</para>
|
|
||||||
</listitem>
|
|
||||||
</orderedlist>
|
|
||||||
|
|
||||||
<para>With these details in hand for either error, one simply locates the offending syntax and makes the appropriate
|
|
||||||
correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<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><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><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>
|
|
||||||
|
|
@ -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><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>
|
|
||||||
|
|
@ -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>
|
|
||||||
|
|
@ -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>
|
|
||||||
|
|
@ -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 <URL></userinput></screen></para>
|
|
||||||
<para>The <literal><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 <new_file></userinput></screen></para>
|
|
||||||
<para>The <literal><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 <file></userinput></screen></para>
|
|
||||||
<para>The <literal><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 <directory></userinput></screen></para>
|
|
||||||
<para>The <literal><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 <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 <source> <destination></userinput></screen></para>
|
|
||||||
<para>The <literal><source></literal> value must be a file or directory and may include the path to
|
|
||||||
the target file. The <literal><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 <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 <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 <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 -- <file></userinput></screen></para>
|
|
||||||
<para>The <literal><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 <file></userinput></screen></para>
|
|
||||||
<para>The <literal><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>
|
|
||||||
|
|
@ -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 <modules> and the </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 <modules> and the </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 <modules> and the </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><!-- 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><workProduct></literal>,
|
|
||||||
work flow status (<literal><documentStatus></literal>), and
|
|
||||||
security (<literal><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><webhelpDirname></literal>
|
|
||||||
and <literal><pdfFilenameBase></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/<webhelpDirname>/<pdfFilenameBase>.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 <file name></literal> command to
|
|
||||||
add new files to the git tree.</para></note>
|
|
||||||
|
|
||||||
</section>
|
|
||||||
|
|
||||||
</section>
|
|
||||||
|
|
@ -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 <your_email@domain.com></screen></para>
|
|
||||||
</listitem>
|
|
||||||
</orderedlist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</section>
|
|
@ -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><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><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><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><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>
|
|
||||||
|
|
@ -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>
|
|
||||||
|
|
@ -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><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><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><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>
|
|
||||||
|
|
Loading…
Reference in New Issue