System Software WG Review Updates, prep for TSC Review

- Updated Revision to 0.9.3 for working copy
- Convert to plugin version 1.3
- Added section on git commands
- Added section on OPF document process and reference appropriately
- Added links in Overview to main sections
- General document cleanup
- Convert graphics to SVG to improve clarity of scaled image
- Add DCO information to README.md file
- Add copyright and license statements to source files

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
master
Jeff Scheel 8 years ago
parent 51a32f3077
commit 2843b3425c

@ -1,3 +1,19 @@
<!--
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.
-->
<?xml version="1.0" encoding="UTF-8"?>
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"

@ -1,13 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
status="draft"
xml:id="bk_main">

<!-- TODO: When ready to publish document, remove the 'status="draft"' statement from the book object above. -->

<!-- TODO: Pick a Title for the new document -->
<title>Master Template Guide</title>
<!-- TODO: Either add a subtitle or remove the following line -->
@ -41,8 +54,8 @@
"apache2" for an Apache V2 license or
"opfExternal" for an official OpenPOWER Foundation external license text.
If you don't know which one to select, leave as "apache2" -->
<legalnotice role="apache2">
<!--legalnotice role="opfExternal"-->
<!--legalnotice role="apache2"-->
<legalnotice role="opfExternal">

<annotation>
<remark>Copyright details are filled in by the template.</remark>

@ -1,3 +1,19 @@
<!--
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.
-->
<chapter 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_examples">

@ -1,8 +1,24 @@
<!--
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.
-->
<chapter 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">
<title>Template document overview</title>

<para>The OpenPOWER Foundation documentation template provides a framework for OpenPOWER public and private
documentation. The goal of the template and this writeup is to promote community contributions
to OpenPOWER documenation and to enable new contributions within a common look and feel. </para>

@ -1,4 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
@ -53,14 +69,12 @@
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
book/appendix nop
book/appendix nop
book/chapter nop
chapter toc,title
chapter/section nop
chapter/section nop
section toc
part toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
@ -75,25 +89,6 @@
<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>template-guide</pdfFilenameBase>

<!-- TODO: If the document is not yet public, uncomment one of the following statements to 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:

working = typically new document within a work group that has not yet been reviewed
and/or approved for internal or external use.
internal = document that has been previously approved by a workgroup for internal use.
review = document that is under review
writeronly = document that has been created solely for the purpose of the writer (not in IPR policy)

The appropriate starting security for a new document is "working".

Note, the value of "external" is the same as specifying no status. -->
<security>review</security>
<!-- security>working</security -->
<!-- security>internal</security -->
<!-- security>writeronly</security -->
<!-- security>external</security -->

<!-- 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.
@ -104,6 +99,44 @@
<!-- workProduct>candidateStandard</workProduct -->
<!-- workProduct>openpowerStandard</workProduct -->

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

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

</configuration>
</execution>
</executions>

@ -1,3 +1,19 @@
<!--
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">


@ -1,3 +1,19 @@
<!--
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">


@ -1,3 +1,19 @@
<!--
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">


@ -1,3 +1,19 @@
<!--
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">


@ -1,8 +1,24 @@
<!--
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 commands invocations. All commands shown, except
<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>

@ -1,3 +1,19 @@
<!--
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">

@ -144,8 +160,8 @@ Checking connectivity... done.
<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 accidentally get
included in your project. The command <userinput>rm -rf Docs-Template</userinput></para>
<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
@ -227,7 +243,7 @@ Checking connectivity... done.
<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 files will be controlled by entries near the
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"/>


@ -1,3 +1,19 @@
<!--
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">


@ -1,3 +1,19 @@
<!--
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">

@ -14,7 +30,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process">
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."</para>
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>

@ -1,3 +1,19 @@
<!--
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">


@ -1,3 +1,19 @@
<!--
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">

@ -28,11 +44,13 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure">
</mediaobject>
</figure>
<para>To create this structure, one would get the green directories and files by cloning <literal>Docs-Master</literal>, blue
directories and files by cloning <literal>Docs-Template</literal>, and the red files by cloning a hypothetical project
<literal>my_project</literal>.</para>
<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 directories, the most important directory and project is <literal>Docs-Master</literal>. Without this project
<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>
@ -52,7 +70,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure">
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 the parent, "Master POM" in the <literal>Docs-Master</literal>project directory
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

Loading…
Cancel
Save