From b74af890cffaa4c61b5f5430fbbe8154b4136216 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Fri, 6 Apr 2018 16:39:42 -0500 Subject: [PATCH] Multiple updates as follows: - Start 1.2 release (_pre1) - Add subsection in Getting Started to include first build - Add subsection in OpenPOWER Documentation Process on document packaging Signed-off-by: Jeff Scheel --- template/bk_main.xml | 18 +++++- template/sec_template_getting_started.xml | 79 +++++++++++++++++++++++ template/sec_template_process.xml | 40 ++++++++++++ 3 files changed, 135 insertions(+), 2 deletions(-) diff --git a/template/bk_main.xml b/template/bk_main.xml index ca95e32..c3ada60 100644 --- a/template/bk_main.xml +++ b/template/bk_main.xml @@ -50,11 +50,11 @@ - 2015, 2016, 2017 + 2015, 2016, 2017, 2018 OpenPOWER Foundation - Revision 1.1.0 + Revision 1.2_pre1 OpenPOWER @@ -90,6 +90,20 @@ + + 2018-04-07 + + Version 1.2 updates: + + + Extend the Getting Started section to include a first document build. + + + Add a section on document packaging for publish in the Publishing OpenPOWER Documents section. + + + + 2017-02-17 diff --git a/template/sec_template_getting_started.xml b/template/sec_template_getting_started.xml index 8319ac4..7b9aeb5 100644 --- a/template/sec_template_getting_started.xml +++ b/template/sec_template_getting_started.xml @@ -32,6 +32,9 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star + + + @@ -123,5 +126,81 @@ Checking connectivity... done. https://github.com/OpenPOWERFoundation/Docs-Master. Additional details about the OpenPOWER Foundation documentation structure are explained in of this document. + +
+ Building the first document + The final step of setting up your environment to perform the first build. The following steps are recommended: + + + Clone the Documentation Development Guide (this document) as source from which to build. + To accomplish this, issue the following command in the same directory as as the master document clone from . + $ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git +Cloning into 'Docs-Template'... +remote: Counting objects: 253, done. +remote: Total 253 (delta 0), reused 0 (delta 0), pack-reused 253 +Receiving objects: 100% (253/253), 468.94 KiB | 0 bytes/s, done. +Resolving deltas: 100% (151/151), done. +Checking connectivity... done. +$ + + + Change the working directory into the source directory for the Documentation Development Guide. + $ cd Docs-Template/template +Docs-Template/template$ + + + Build the document in Maven.Docs-Template/template$ mvn generate-sources +[INFO] Scanning for projects... +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building Documentation Development Guide 1.0.0-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- openpowerdocs-maven-plugin:1.1.0:generate-webhelp (generate-webhelp) @ openpower-template-guide --- +[INFO] Processing input file: bk_main.xml +[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo +[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo +[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo +[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo +Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure +INFO: Default page-height set to: 11in +Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure + ...snip... +[INFO] Applying customization parameters + +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +Parsing: /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html + ...snip... +The created index files are located in /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/search/.js +[INFO] See /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/bk_main for generated file(s) +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 31.547 s +[INFO] Finished at: 2018-02-27T11:43:45-06:00 +[INFO] Final Memory: 83M/729M +[INFO] ------------------------------------------------------------------------ +Docs-Template/template$ + The first time one builds in a Maven environment, the build time will be noticeably + long due to JAR file downloads associated with the new Maven project types. In future builds, these JAR files will + only be downloaded when they are updated. As such, one should both allow for this extra time and not be discouraged + by the duration of the first build. + + + Once complete, there should be a single directory in the target/docbkx/webhelp/ directory. For the + Docs-Template project, that directory is doc-devel-guide. Inside this directory will + be both the PDF file and the index.html file for the HTML document. + To verify this for the Documentation Development Guide, perform these commands: + Docs-Template/template$ cd target/docbkx/webhelp/ +Docs-Template/template/target/docbkx/webhelp$ ls +doc-devel-guide +Docs-Template/template/target/docbkx/webhelp$ cd doc-devel-guide +Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ ls +bookinfo.xml common content doc-devel-guide-20180227.pdf favicon.ico index.html +webapp + Now, you are ready to begin working on your own document. Useful information on how to proceed can + be found in and . +
diff --git a/template/sec_template_process.xml b/template/sec_template_process.xml index 1c0c652..8d60c0f 100644 --- a/template/sec_template_process.xml +++ b/template/sec_template_process.xml @@ -420,6 +420,46 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process"> Following this approval, the document POM (pom.xml) variable <workProduct> should be set to openpowerStandard. + +
+ Packaging the document for publish + + The OpenPOWER Foundation process for publishing documents from WordPress in the + Resource Catalog on openpowerfoundatoin.org website has the following requirements: + + + The PDF and all HTML source must be bundled in a self-contained zip file. + + + The zip file is expected to contain a single directory in which the document PDF and index.html file are found. + + + The filename of the zip file must be the same name as the contained directory. + + + + To create this package for the Documentation Development Guide, one would perform the following commands + in Linux from the document source directory (.../Docs-Template/template/): + Docs-Template/template$ cd target/docbkx/webhelp/ +Docs-Template/template/target/docbkx/webhelp$ ls +doc-devel-guide +Docs-Template/template/target/docbkx/webhelp$ zip -rv doc-devel-guide.zip doc-devel-guide/ + adding: doc-devel-guide/ (in=0) (out=0) (stored 0%) + adding: doc-devel-guide/favicon.ico (in=806) (out=806) (stored 0%) + adding: doc-devel-guide/index.html (in=654) (out=385) (deflated 41%) + ...snip... + adding: doc-devel-guide/doc-devel-guide-20180406.pdf (in=413655) (out=305492) (deflated 26%) + ...snip... + adding: doc-devel-guide/common/ (in=0) (out=0) (stored 0%) + adding: doc-devel-guide/common/main.js (in=5674) (out=2119) (deflated 63%) + ...snip... + adding: doc-devel-guide/common/jquery/jquery-ui-1.8.2.custom.min.js (in=87032) (out=22729) (deflated 74%) +total bytes=3342807, compressed=1332882 -> 60% savings +Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ ls +doc-devel-guide doc-devel-guide.zip + For MacOS and Windows, the steps will be similar with slight variations on the command to create the zip file. + This zip file can be sent to the person managing the documents in the OpenPOWER Resource Catalog. +