From 3136f7755eaea41eaa8f1a50f8160c242ae90fff Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Tue, 15 Mar 2016 13:59:59 -0500 Subject: [PATCH] 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 --- template/app_template.xml | 16 +++++ template/bk_main.xml | 23 ++++-- template/ch_example.xml | 16 +++++ template/ch_template_overview.xml | 18 ++++- template/pom.xml | 79 +++++++++++++++------ template/sec_template_debugging.xml | 16 +++++ template/sec_template_existing_document.xml | 16 +++++ template/sec_template_faq.xml | 16 +++++ template/sec_template_getting_started.xml | 16 +++++ template/sec_template_git_commands.xml | 18 ++++- template/sec_template_new_document.xml | 22 +++++- template/sec_template_policies.xml | 16 +++++ template/sec_template_process.xml | 18 ++++- template/sec_template_references.xml | 16 +++++ template/sec_template_structure.xml | 28 ++++++-- 15 files changed, 295 insertions(+), 39 deletions(-) diff --git a/template/app_template.xml b/template/app_template.xml index 3dcf89e..7d53c3d 100644 --- a/template/app_template.xml +++ b/template/app_template.xml @@ -1,3 +1,19 @@ + + - - Master Template Guide @@ -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" --> - - + + Copyright details are filled in by the template. diff --git a/template/ch_example.xml b/template/ch_example.xml index 352c126..98fbf6d 100644 --- a/template/ch_example.xml +++ b/template/ch_example.xml @@ -1,3 +1,19 @@ + diff --git a/template/ch_template_overview.xml b/template/ch_template_overview.xml index 2b42e11..51c05bc 100644 --- a/template/ch_template_overview.xml +++ b/template/ch_template_overview.xml @@ -1,8 +1,24 @@ + Template document overview - + 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. diff --git a/template/pom.xml b/template/pom.xml index b32d788..dacd6d9 100644 --- a/template/pom.xml +++ b/template/pom.xml @@ -1,4 +1,20 @@ + @@ -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 @@ -75,25 +89,6 @@ template-guide - - review - - - - - + + + foundationConfidential + + + + + review + + diff --git a/template/sec_template_debugging.xml b/template/sec_template_debugging.xml index d8fa277..dcd90cf 100644 --- a/template/sec_template_debugging.xml +++ b/template/sec_template_debugging.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_existing_document.xml b/template/sec_template_existing_document.xml index 7e561c1..b21896d 100644 --- a/template/sec_template_existing_document.xml +++ b/template/sec_template_existing_document.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_faq.xml b/template/sec_template_faq.xml index 06b1800..019963c 100644 --- a/template/sec_template_faq.xml +++ b/template/sec_template_faq.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_getting_started.xml b/template/sec_template_getting_started.xml index c4f828c..7d38fe0 100644 --- a/template/sec_template_getting_started.xml +++ b/template/sec_template_getting_started.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_git_commands.xml b/template/sec_template_git_commands.xml index d971d20..c66c351 100644 --- a/template/sec_template_git_commands.xml +++ b/template/sec_template_git_commands.xml @@ -1,8 +1,24 @@ +
Common git commands - This section provides a list of commonly used git commands invocations. All commands shown, except + This section provides a list of commonly used git command invocations. All commands shown, except the first one (git clone must be issued from within the project directory. diff --git a/template/sec_template_new_document.xml b/template/sec_template_new_document.xml index 6cefc66..b76a836 100644 --- a/template/sec_template_new_document.xml +++ b/template/sec_template_new_document.xml @@ -1,3 +1,19 @@ +
@@ -144,8 +160,8 @@ Checking connectivity... done. $ - 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 rm -rf Docs-Template + 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 rm -rf Docs-Template 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. Adding new content The starting point for book content is the bk_main.xml 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: diff --git a/template/sec_template_policies.xml b/template/sec_template_policies.xml index 93d6262..ff8f382 100644 --- a/template/sec_template_policies.xml +++ b/template/sec_template_policies.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_process.xml b/template/sec_template_process.xml index 68e5726..88f8391 100644 --- a/template/sec_template_process.xml +++ b/template/sec_template_process.xml @@ -1,3 +1,19 @@ +
@@ -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." + Track." For example, this document is a non-stardard work product. 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: diff --git a/template/sec_template_references.xml b/template/sec_template_references.xml index fa18a1f..96a7344 100644 --- a/template/sec_template_references.xml +++ b/template/sec_template_references.xml @@ -1,3 +1,19 @@ +
diff --git a/template/sec_template_structure.xml b/template/sec_template_structure.xml index 50fad8a..67c8570 100644 --- a/template/sec_template_structure.xml +++ b/template/sec_template_structure.xml @@ -1,3 +1,19 @@ +
@@ -28,11 +44,13 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> - To create this structure, one would get the green directories and files by cloning Docs-Master, blue - directories and files by cloning Docs-Template, and the red files by cloning a hypothetical project - my_project. + To create this structure, one would clone the Docs-Master project to + get the Docs-Master directory and all its contents (shown above in green), + clone the Docs-Template project to get the Docs-Template directory + and all its contents (shown in blue), and clone my_project project to get the + my_project directory and all its contents (shown in red). - Among these directories, the most important directory and project is Docs-Master. Without this project + Among these projects, the most important directory and project is Docs-Master. Without this project and associated directory, no document will build. As depicted in the above figure, the Docs-Master directory must sit at a level equal to all other project directories. Details on how to install this project can be found in the section. @@ -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 Docs-Template project are a pom.xml referred to as the "Workgroup POM" and a single document directory (template). - The "Workgroup POM" is a minimal POM file that locates the the parent, "Master POM" in the Docs-Masterproject directory + The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the Docs-Masterproject directory with a <relativePath> definition of ../Docs-Master/pom.xml. The document directory contains the unique files used to create the document. The two most important files in the Docs-Template/template directory(and in any project) are the pom.xml or "Document POM" which describes