diff --git a/README.md b/README.md index 1386e52..5f0b007 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # OpenPOWER Foundation Documentation Development Guide -This repository holds the source for the documentation development guide +This repository holds the source for the *Documentation Development Guide* (formerly *Master Template Document*) for -OpenPOWER Foundation. The PDF and HTML generated from the doc/template/ +OpenPOWER Foundation. The PDF and HTML generated from the ``doc_dev_guide`` directory build a document that both describes how to build a new document and contains examples and directions on how to do it. @@ -33,8 +33,11 @@ Document library at [OpenPOWER Foundation Documentation Development Guide](http: The project which controls the look and feel of the document is the [Docs-Maven-Plugin project](https://github.com/OpenPOWERFoundation/Docs-Maven-Plugin), an OpenPOWER Foundation private project on GitHub. To obtain access to the Maven Plugin project, -contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or -Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\). +contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\). + +Additional sub-directories of interest in this project are: +- ``doc_template``: provides a template for new specifications from scratch +- ``errata_template``: provide a template for errata documents ## License This project is licensed under the Apache V2 license. More information diff --git a/template/app_template.xml b/doc_dev_guide/app_template.xml similarity index 100% rename from template/app_template.xml rename to doc_dev_guide/app_template.xml diff --git a/template/bk_main.xml b/doc_dev_guide/bk_main.xml similarity index 92% rename from template/bk_main.xml rename to doc_dev_guide/bk_main.xml index c3ada60..d4c15a2 100644 --- a/template/bk_main.xml +++ b/doc_dev_guide/bk_main.xml @@ -54,7 +54,7 @@ OpenPOWER Foundation - Revision 1.2_pre1 + Revision 1.2_pre5 OpenPOWER @@ -91,16 +91,28 @@ - 2018-04-07 + 2018-08-27 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. + + Add a section on circumventing Java AWT exception. + + + Add information on key document tags which need update for new documents. + + + Extend information on modifying an existing document to include a step-by-step description of how to get started. + + + Rename the template directory to doc_dev_guide. + diff --git a/template/ch_example.xml b/doc_dev_guide/ch_example.xml similarity index 100% rename from template/ch_example.xml rename to doc_dev_guide/ch_example.xml diff --git a/template/ch_template_overview.xml b/doc_dev_guide/ch_template_overview.xml similarity index 100% rename from template/ch_template_overview.xml rename to doc_dev_guide/ch_template_overview.xml diff --git a/template/figures/example_graphic.bmp b/doc_dev_guide/figures/example_graphic.bmp similarity index 100% rename from template/figures/example_graphic.bmp rename to doc_dev_guide/figures/example_graphic.bmp diff --git a/template/figures/example_graphic.odg b/doc_dev_guide/figures/example_graphic.odg similarity index 100% rename from template/figures/example_graphic.odg rename to doc_dev_guide/figures/example_graphic.odg diff --git a/template/figures/project_process_non-std_track_doc_variables_graphic.odg b/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.odg similarity index 100% rename from template/figures/project_process_non-std_track_doc_variables_graphic.odg rename to doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.odg diff --git a/template/figures/project_process_non-std_track_doc_variables_graphic.svg b/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.svg similarity index 100% rename from template/figures/project_process_non-std_track_doc_variables_graphic.svg rename to doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.svg diff --git a/template/figures/project_process_non-std_track_graphic.odg b/doc_dev_guide/figures/project_process_non-std_track_graphic.odg similarity index 100% rename from template/figures/project_process_non-std_track_graphic.odg rename to doc_dev_guide/figures/project_process_non-std_track_graphic.odg diff --git a/template/figures/project_process_non-std_track_graphic.svg b/doc_dev_guide/figures/project_process_non-std_track_graphic.svg similarity index 100% rename from template/figures/project_process_non-std_track_graphic.svg rename to doc_dev_guide/figures/project_process_non-std_track_graphic.svg diff --git a/template/figures/project_process_std_track_doc_variables_candidate_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_candidate_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.odg diff --git a/template/figures/project_process_std_track_doc_variables_candidate_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_candidate_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.svg diff --git a/template/figures/project_process_std_track_doc_variables_draft_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_draft_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.odg diff --git a/template/figures/project_process_std_track_doc_variables_draft_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_draft_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.svg diff --git a/template/figures/project_process_std_track_doc_variables_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.odg diff --git a/template/figures/project_process_std_track_doc_variables_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.svg diff --git a/template/figures/project_process_std_track_doc_variables_review_draft_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_review_draft_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.odg diff --git a/template/figures/project_process_std_track_doc_variables_review_draft_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_review_draft_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.svg diff --git a/template/figures/project_process_std_track_doc_variables_specification_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_specification_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.odg diff --git a/template/figures/project_process_std_track_doc_variables_specification_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_doc_variables_specification_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.svg diff --git a/template/figures/project_process_std_track_graphic.odg b/doc_dev_guide/figures/project_process_std_track_graphic.odg similarity index 100% rename from template/figures/project_process_std_track_graphic.odg rename to doc_dev_guide/figures/project_process_std_track_graphic.odg diff --git a/template/figures/project_process_std_track_graphic.svg b/doc_dev_guide/figures/project_process_std_track_graphic.svg similarity index 100% rename from template/figures/project_process_std_track_graphic.svg rename to doc_dev_guide/figures/project_process_std_track_graphic.svg diff --git a/doc_dev_guide/figures/project_structure_graphic.odg b/doc_dev_guide/figures/project_structure_graphic.odg new file mode 100644 index 0000000..20348a2 Binary files /dev/null and b/doc_dev_guide/figures/project_structure_graphic.odg differ diff --git a/template/figures/project_structure_graphic.svg b/doc_dev_guide/figures/project_structure_graphic.svg similarity index 77% rename from template/figures/project_structure_graphic.svg rename to doc_dev_guide/figures/project_structure_graphic.svg index 9818b05..efb8827 100644 --- a/template/figures/project_structure_graphic.svg +++ b/doc_dev_guide/figures/project_structure_graphic.svg @@ -1,6 +1,6 @@ - - + + @@ -8,10 +8,11 @@ - + + @@ -25,11 +26,12 @@ - + + - + @@ -44,30 +46,30 @@ - + - + - - + + - - + + - + @@ -126,322 +128,386 @@ - ... + + ... - Docs-Master + + Docs-Master - Docs-Template + + Docs-Template - common + + common - pom.xml + + pom.xml - ch_preface.xml + + ch_preface.xml - ... + + ... - app_foundation.xml + + app_foundation.xml - ... + + ... - template + + doc_dev_guide - pom.xml + + pom.xml - bk_main.xml + + bk_main.xml - ... + + ... - pom.xml + + pom.xml - ... + + ... - my_project + + my_project - my_doc_1 + + my_doc_1 - pom.xml + + pom.xml - bk_main.xml + + bk_main.xml - ... + + ... - pom.xml + + pom.xml - ... + + ... - my_doc_2 + + my_doc_2 - bk_main.xml + + bk_main.xml - pom.xml + + pom.xml - ... + + ... + + + - ... + + ... + + + + + + + + + + + + + + + + + + + + + + + - “Master document framework” + + “Master document framework” - “Common files” + + “Common files” - “Master POM” + + “Master POM” - “Master Template Guide” + + “Master Template Guide” - “Main book file” + + “Main book file” - “Document POM” + + “Document POM” - “Workgroup POM” + + “Workgroup POM” - “A project” + + “A project” - “A document” + + “A document” - “Another document” + + “Another document” - “Workgroup POM” + + “Workgroup POM” diff --git a/template/pom.xml b/doc_dev_guide/pom.xml similarity index 100% rename from template/pom.xml rename to doc_dev_guide/pom.xml diff --git a/template/sec_example.xml b/doc_dev_guide/sec_example.xml similarity index 100% rename from template/sec_example.xml rename to doc_dev_guide/sec_example.xml diff --git a/template/sec_template_debugging.xml b/doc_dev_guide/sec_template_debugging.xml similarity index 88% rename from template/sec_template_debugging.xml rename to doc_dev_guide/sec_template_debugging.xml index 7cf44e6..a0f5815 100644 --- a/template/sec_template_debugging.xml +++ b/doc_dev_guide/sec_template_debugging.xml @@ -73,7 +73,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug"> Note: Open the temporary file: -file:/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml +file:/home/user1/Docs-Template/doc_dev_guide/target//bk_main.xml-invalid.xml to see all the errors in context. You must correct the errors in the original @@ -87,7 +87,7 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add The full path and filename that contains the context for the failure. In the message above, this is -/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml. +/home/user1/Docs-Template/doc_dev_guide/target//bk_main.xml-invalid.xml. The location within the file of the syntax error. For the above example, the key information is "lineNumber: 272; columnNumber: 70. @@ -115,14 +115,14 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add [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] +[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/doc_dev_guide/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1] ... Like validation errors, three key pieces of information are again provided: The full path and filename of our failure is -/home/user1/Docs-Template/template/sec_template_new_document.xml. +/home/user1/Docs-Template/doc_dev_guide/sec_template_new_document.xml. The location within the file of the error is "lineNumber: 55; columnNumber: 17. @@ -240,5 +240,30 @@ javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: https://www.w3.org/2002/08/XSLFOsummary.html. + +
+ Java AWT exception + + Use of Maven in headless environments from Mac OS has uncovered an intermittent exception in the AWT libraries. + This error looks like the following:... +--------------------------------------------------- +Exception in thread "main" java.awt.AWTError: Can't connect to X11 window server using 'localhost:11.0' as the value of the DISPLAY variable. + at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method) + at sun.awt.X11GraphicsEnvironment.access$200(X11GraphicsEnvironment.java:65) + at sun.awt.X11GraphicsEnvironment$1.run(X11GraphicsEnvironment.java:115) + at java.security.AccessController.doPrivileged(Native Method) + at sun.awt.X11GraphicsEnvironment.<clinit>(X11GraphicsEnvironment.java:74) + at java.lang.Class.forName0(Native Method) + at java.lang.Class.forName(Class.java:264) + at java.awt.GraphicsEnvironment.createGE(GraphicsEnvironment.java:103) + at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:82) + at sun.awt.X11.XToolkit.<clinit>(XToolkit.java:126) +... + + The circumvention for this error, is force AWT to run headless. This can be accomplished by adding the + -Djava.awt.headless=true parameter to the maven invocation such that it looks like this: + $ mvn clean generate-sources -Djava.awt.headless=true +
+ diff --git a/template/sec_template_existing_document.xml b/doc_dev_guide/sec_template_existing_document.xml similarity index 57% rename from template/sec_template_existing_document.xml rename to doc_dev_guide/sec_template_existing_document.xml index a92c465..23a3462 100644 --- a/template/sec_template_existing_document.xml +++ b/doc_dev_guide/sec_template_existing_document.xml @@ -19,10 +19,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_existing_doc Modifying an existing document - 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 . + To begin editing an existing document, you may need to clone up to two projects -- + the specific document project, and if not already cloned, the master document framework project too. + If needed, clone the master document as described in . - Once complete, obtain a copy of the desired document by cloning its project. For example, to clone this document, + To obtain a copy of the desired document source, clone its project. For example, to clone this document, Documentation Development Guide, from the public OpenPOWER Foundation git repository, use this command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git @@ -37,7 +38,7 @@ Checking connectivity... done. $ To build a specific document such as this guide, follow these steps from the directory where - you just cloned:$ cd Docs-Template/template + you just cloned:$ cd Docs-Template/doc_dev_guide $ mvn clean [INFO] Scanning for projects... [INFO] @@ -46,7 +47,7 @@ Checking connectivity... done. [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide --- -[INFO] Deleting ~/Docs-Template/template/target +[INFO] Deleting ~/Docs-Template/doc_dev_guide/target [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ @@ -77,7 +78,7 @@ Checking connectivity... done. in which one wishes to execute them. Thus, the command mvn clean generate-sources would accomplish the same thing as the above sequence of commands. - If all goes well, the generated pdf should be available in ~/Docs-Template/template/target/docbkx/webhelp/template-guide/. + If all goes well, the generated pdf should be available in ~/Docs-Template/doc_dev_guide/target/docbkx/webhelp/template-guide/. For assistance correcting commmon build failures, see . @@ -86,10 +87,44 @@ Checking connectivity... done. the base project directory will build all projects identified in the <module> list in the top-level pom.xml file, known as the "Workgroup POM". - You are now ready to begin making updates. Before diving deeply into new text, - you may want to review - to ensure that proper Work Product, - Work Process, and security values are selected for your document. + Before diving deeply into text updates, + you should consider the following items for your project and document: + + + Ensure that the previous version of the tree is tagged. + + The command git tag may be used to see existing tree tags + and set new ones. + See for more specifics on git tag commands. + + + Reset the document status. + The pom.xml file contains the <documentStatus> field which generally + needs to be reset to the draft value. In addition, for non-public work groups, the <security> + field should be returned to workgroupConfidential or foundationConfidential + values during the document update process. More information on + document development process can be found in . Detailed information on + key document settings can be found in and + . + + + Incement the new document release information. + The bk_main.xml file contains the <releaseinfo> field + which contains the Versions, Release, and Modification values. Typically, new documents when first being edited will increment the correct value, + reset sub-values to zero, and append a "_preN" tag. During the development process, you will likely increment the "N-value" in your "pre" release + information. Then, at publish, you can remove the "_preN" suffix. + More details on the release information can be found in recommendation + . + + + Create a new entry in the revision history. + The bk_main.xml file contains the revision history in <revhistory> table. To start a new entry, + add a new <revision> entry with <date> and <revdescription> fields at the top + of the list of revisions. + + + + You are now ready to make textual updates. diff --git a/template/sec_template_faq.xml b/doc_dev_guide/sec_template_faq.xml similarity index 90% rename from template/sec_template_faq.xml rename to doc_dev_guide/sec_template_faq.xml index 019963c..cb081dc 100644 --- a/template/sec_template_faq.xml +++ b/doc_dev_guide/sec_template_faq.xml @@ -24,10 +24,6 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_faq"> Do I have to follow the guidelines in of this guide? No. HOWEVER, doing so makes it simpler for all community members to participate in maintaining your document. - - Question 2... - Answer 2... - diff --git a/template/sec_template_getting_started.xml b/doc_dev_guide/sec_template_getting_started.xml similarity index 93% rename from template/sec_template_getting_started.xml rename to doc_dev_guide/sec_template_getting_started.xml index 7b9aeb5..bf5be45 100644 --- a/template/sec_template_getting_started.xml +++ b/doc_dev_guide/sec_template_getting_started.xml @@ -145,11 +145,11 @@ Checking connectivity... done. Change the working directory into the source directory for the Documentation Development Guide. - $ cd Docs-Template/template -Docs-Template/template$ + $ cd Docs-Template/doc_dev_guide +Docs-Template/doc_dev_guide$ - Build the document in Maven.Docs-Template/template$ mvn generate-sources + Build the document in Maven.Docs-Template/doc_dev_guide$ mvn generate-sources [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ @@ -170,10 +170,10 @@ Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure <!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 +Parsing: /home/scheel/mydocs/Docs-Template/doc_dev_guide/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) +The created index files are located in /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide/content/search/.js +[INFO] See /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/bk_main for generated file(s) [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ @@ -181,7 +181,7 @@ The created index files are located in /home/scheel/mydocs/Docs-Template/templat [INFO] Finished at: 2018-02-27T11:43:45-06:00 [INFO] Final Memory: 83M/729M [INFO] ------------------------------------------------------------------------ -Docs-Template/template$ +Docs-Template/doc_dev_guide$ 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 @@ -192,11 +192,11 @@ The created index files are located in /home/scheel/mydocs/Docs-Template/templat 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 + Docs-Template/doc_dev_guide$ cd target/docbkx/webhelp/ +Docs-Template/doc_dev_guide/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 +Docs-Template/doc_dev_guide/target/docbkx/webhelp$ cd doc-devel-guide +Docs-Template/doc_dev_guide/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 diff --git a/template/sec_template_git_commands.xml b/doc_dev_guide/sec_template_git_commands.xml similarity index 100% rename from template/sec_template_git_commands.xml rename to doc_dev_guide/sec_template_git_commands.xml diff --git a/template/sec_template_new_document.xml b/doc_dev_guide/sec_template_new_document.xml similarity index 91% rename from template/sec_template_new_document.xml rename to doc_dev_guide/sec_template_new_document.xml index f1b60fe..63e4a99 100644 --- a/template/sec_template_new_document.xml +++ b/doc_dev_guide/sec_template_new_document.xml @@ -120,7 +120,7 @@ Checking connectivity... done. - If your project exits on GitHub in the OpenPOWER Foundation area and it contains a template directory, + If your project exits on GitHub in the OpenPOWER Foundation area and it contains a doc_template directory, then follow the directions in to use this document as a base. @@ -144,7 +144,7 @@ Checking connectivity... done. If this is your first document, in a brand new OpenPOWER Foundation project (on GitHub), you have the fewest number of steps to perform because your project should have been primed with a single project based on Docs-Template. You can verify this by inspecting - the files in your project directory. A new project will contain a template directory, a pom.xml + the files in your project directory. A new project will contain a doc_template directory, a pom.xml file, a LICENSE file, and a README.md file. If this is the case, you simply need to perform the following three steps: @@ -154,12 +154,12 @@ Checking connectivity... done. using the cd command: $ cd ~/my_project $ - This directory should contain the template folder used to prime the project. + This directory should contain the doc_template folder used to prime the project. - Rename the template document directory to something new like my_doc. + Rename the doc_template document directory to something new like my_doc. To accomplish this, use the mv command:: -$ mv template/ my_doc +$ mv doc_template/ my_doc Change the project name in the Workgroup POM file (my_project/pom.xml). Using your editor, change this line @@ -244,11 +244,11 @@ Checking connectivity... done. $ - To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/template + To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/doc_dev_guide directory. If creating a new project named my_doc via a command line, the command sequence would look like this: $ mkdir my_doc -$ cp -r Docs-Template/template/* my_doc +$ cp -r Docs-Template/doc_dev_guide/* my_doc $ @@ -279,15 +279,45 @@ Checking connectivity... done. and bk_main.xml. Within these two files are XML comment tags that begin "<!-- TODO:" 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. - Pick your setting for document work product type (<workProduct>, + + In the pom.xml file, pick your settings for document work product type (<workProduct>, work flow status (<documentStatus>), and security (<security>) carefully. 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. - Be sure to remember two key values you used in the pom.xml file, <webhelpDirname> + + In addition to the document settings, be sure to remember two key values you used in the pom.xml + file, <webhelpDirname> and <pdfFilenameBase>, as these will be used to locate your generated document. + + In the book.xml file, you will find the following document unique values which you most likely want to change: + + + <title> + + The main title of the document. This appears in the largest font at the top of the title page. + + + + + <subtitle> + + The second title of the document. This title appears in a smaller font below the <title> on the title page. + + + + + <realeaseinfo> + + The document version value. This value should take the form of "Revision V.R.M" as described in + recommendation . + + + + + When ready, build your new document using standard maven commands like this:$ cd my_project/my_doc $ mvn clean diff --git a/template/sec_template_policies.xml b/doc_dev_guide/sec_template_policies.xml similarity index 91% rename from template/sec_template_policies.xml rename to doc_dev_guide/sec_template_policies.xml index abd87fc..f0e7279 100644 --- a/template/sec_template_policies.xml +++ b/doc_dev_guide/sec_template_policies.xml @@ -26,7 +26,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies"> The head book file should be named with the prefix "bk_". - + The document versioning as defined by the <releaseinfo> tag in the main book file bk_xxx should be named "Revision V.R.M", not "Version V.R.M" or simply "V.R.M" where: @@ -60,6 +60,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies"> Figures source and images should be placed in the figures sub-directory for the document. + + Releases of the same document sound be contained in the same tree, but tagged at levels of interest using + the git tag command. See the for more specifics + on git commands. + In addition to documentation structure, general community/project guidelines are as follows: diff --git a/template/sec_template_process.xml b/doc_dev_guide/sec_template_process.xml similarity index 98% rename from template/sec_template_process.xml rename to doc_dev_guide/sec_template_process.xml index 8d60c0f..d7498fa 100644 --- a/template/sec_template_process.xml +++ b/doc_dev_guide/sec_template_process.xml @@ -439,11 +439,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process"> 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 + in Linux from the document source directory (.../Docs-Template/doc_dev_guide/): + Docs-Template/doc_dev_guide$ cd target/docbkx/webhelp/ +Docs-Template/doc_dev_guide/target/docbkx/webhelp$ ls doc-devel-guide -Docs-Template/template/target/docbkx/webhelp$ zip -rv doc-devel-guide.zip doc-devel-guide/ +Docs-Template/doc_dev_guide/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%) @@ -455,7 +455,7 @@ doc-devel-guide ...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 +Docs-Template/doc_dev_guide/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. diff --git a/template/sec_template_references.xml b/doc_dev_guide/sec_template_references.xml similarity index 100% rename from template/sec_template_references.xml rename to doc_dev_guide/sec_template_references.xml diff --git a/template/sec_template_structure.xml b/doc_dev_guide/sec_template_structure.xml similarity index 97% rename from template/sec_template_structure.xml rename to doc_dev_guide/sec_template_structure.xml index 5da0ae3..2e0ec05 100644 --- a/template/sec_template_structure.xml +++ b/doc_dev_guide/sec_template_structure.xml @@ -74,7 +74,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> 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 + Docs-Template/doc_dev_guide directory (and in any project) are the pom.xml or "Document POM" which describes how to build the document and which points to the main document file, the bk_main.xml file. This book file contains all the Docbook source, directly or through include statements (<xi:include href="..."), to build the document. diff --git a/doc_template/app_template.xml b/doc_template/app_template.xml new file mode 100644 index 0000000..f4b7ae4 --- /dev/null +++ b/doc_template/app_template.xml @@ -0,0 +1,30 @@ + + + + + Appendix template + This is the first paragraph of a new appendix... +
+ Section title + Section text... +
+ diff --git a/doc_template/bk_main.xml b/doc_template/bk_main.xml new file mode 100644 index 0000000..c656c15 --- /dev/null +++ b/doc_template/bk_main.xml @@ -0,0 +1,109 @@ + + + + + +]> + + + + + Title + + Sub-title + + + + + + TBD Work Group Name + + tbd-chair@openpowerfoundation.org + + OpenPower Foundation + + + + 2018 + OpenPOWER Foundation + + + Revision 1.0_pre1 + OpenPOWER + + + + + + + Copyright details are filled in by the template. + + + + + + + The purpose of this document is to ...TBD describe the document + This document is a Standard Track, Workgroup Specification work product owned by the + TBD Workgroup and handled in compliance with the requirements outlined in the + OpenPOWER Foundation Work Group (WG) Process document. It was + created using the Master Template Guide version &template_version;. + Comments, questions, etc. can be submitted to the + public mailing list for the parent specification at + tbd@mailinglist.openpowerfoundation.org. + + + + + + 2018-08-29 + + + + TODO: Describe your initial draft, e.g. from where it came if not created from scratch + + + + + + + + + + + + + + + + + + + + + diff --git a/doc_template/ch_example.xml b/doc_template/ch_example.xml new file mode 100644 index 0000000..2f81fb1 --- /dev/null +++ b/doc_template/ch_example.xml @@ -0,0 +1,323 @@ + + + + + Documentation examples + + +
+ Section Title goes here + This Section covers something of interest to a limited number of people and shows a 1st level section + +
+ Example Itemized List + + Here is an example of an itemized list + + A list title is completely optional + + + Item you don't care about + + + Perhaps you'd like a sub-list + + + Oooh, here's about another + + + + + + + + Item you might care about + + + + Item you do care about + + +
+
+ Example ordered list + + All good documents need ordered lists. + + Another purely optional title + + First item + + + Second item + + + first indented item + + + second indented item + + + + + Third item + + +
+ +
+ Example figure with embedded graphic + + Here is how you embed a graphic. +
+ Example figure + + + + + +
+ Raw images such as the bitmap (bmp) file above may become blurry as they are scaled. + Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best. +
+ +
+ Example table + Of course all good documents need tables. Here's how you build a basic table. + +
+ Example Table Title + + + + + + + + + + 1st Column Heading + + + + + 2nd Column Heading + + + + + 3rd Column Heading + + + + + 4th Column Heading + + + + + + + + Yes + + + Red + Green + Blue + Custom (Amber) + + + MAIN_Junk + + + More_Junk + + + + + merged cells horizontal + + + cell_stuff + + + + + Merge cells vertical + + + filler + + + merge cells both ways + + + + + filler 2 + + + + + How about we put a list in the table cell + + + item 1 + + + item 2 + + + item 2 + + + + + Another Cell + + + Yet Another Cell + + + Finally the last cell + + + + +
+ +
+ Example of crossreferences and footnotes + To reference another section or table is pretty easy. For example: see for how tables look. + Lists are shown in and if you need to make a footnote + The footnote text goes here and can reference something like for additional explanation. + For clarification that is easy. Of course you might want an additional reference to the footnote which can also be done easily. + Lastly you probably want to mark text by making it italic text example or Bold Text Example. +
+
+ Example of code citations and user input + When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example: + $ echo "Hello world" +Hello world +$ + + Docbook also allows for formatting and display of common languages, allowing for whitespace + and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled: +main() +{ + printf("Hello world\n"); +}]]> + If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: This is my literal +text. It ignores whitespace. +
+
+ Example of special characters in text + Sometimes in text you need special characters. These can be provided using their UNICODE values such as ≠ (&#8800), + Ω (&#x2126), and ∆ (&#8710;). + These can be "coded" using the form &#ddddd; where ddddd is + the up to five digit decimal representation of the character. The form &#xhhhh; where + hhhh is the up to 4 digit hexidecimal representation of the character. + This formatting works well as long as the symbol to which you are referring is contained in the font set + used for the document -- Arimo for standard text and Cousine for monospace. If when building a document, you see a message like + "WARNING, Glyph...not available in font 'Arimo'," + see in for details on using the provided symbol fonts explicitly. +
+ + + +
+ Examples of OpenPOWER Foundation Docbook extensions + + The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are: + + + Setting text color explicitly + + Text color can be controlled using <phrase role="color:color_name"> + tag where color_name contains the color setting. For example, this + text:A red sentence contains a blue word.]]> produces this sentence: + A red sentence contains a blue word. + Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation: + aqua, black, blue, fuchsia, gray, + green, lime, maroon, navy, olive, + purple, red, silver, teal, white, + and yellow. Additionally, RGB values can be #nnnnnn where nnnnnn is a hexidecimal color value or + rgb(n1, n2, n3) where n1, n2, and n3 are integers 0-255. + This tag has also been implemented on the following tags: <thead>, + <tbody>, and <tfoot>. + This parameter should only be used for tags listed above. + + + + Inserting line breaks + Line breaks can be introduced using <?linebreak?> tags. For example, this + text:A line break in the middle of text]]> produces this sentence: + A line break in the middle of text + This tag becomes useful in table text spacing. + + + + Inserting page breaks + Page breaks can be introduced using <?hard-pagebreak?> tags. For example, this + text:A page break Between two paragraphs]]> produces this output: + A page break Between two paragraphs + This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page. + Because the XSL template behind the Processing Instruction generates + a ]]> in + the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural + components may result in the text after the break being dropped. User beware!. + + + + Varying the font size + Font sizes can also be set using the + <phrase role="font-size:size"> + tag where size contains a size value such as "6pt" or "50%" or "1.5em". + For example, a paragraph can be made to be 6 point as follows:A sentence that contains some 6pt font, +50% font, and +1.5em font in it.]]> produces this output: + A sentence that contains some 6pt font, + 50% font, and 1.5em font in it. + This tag has also been implemented on the following tags: <para>, + <thead>, <tbody>, and <tfoot>. + This parameter should only be used for tags listed above. + + + + Using additional symbols + If you find that the Arimo and Cousine fonts do not contain the special symbol you need + for your document, you may use the additional symbol font provided for document (STIX Two Math). + Due to an unimplemented feature in the Apach FO Processor, selection of this + font needs to be explicitly performed using the + <symbol role="symbolfont"> wrapper around your symbol value. + + For example, the symbol coding of should produce + a circle with a cross in here "⨁", but instead creates a "Glyph...not available in font 'Arimo'" error + on document build and the PDF renders as a "#". + + Re-coding this to use ⨁]]> produces + the correct symbole here "⨁". + If this still does not provide the symbol you expected, double check the code and the font maps found at + http://www.stixfonts.org/charactertable.html. + +
+ + + diff --git a/doc_template/figures/example_graphic.bmp b/doc_template/figures/example_graphic.bmp new file mode 100644 index 0000000..296b4ea Binary files /dev/null and b/doc_template/figures/example_graphic.bmp differ diff --git a/doc_template/pom.xml b/doc_template/pom.xml new file mode 100644 index 0000000..d601a92 --- /dev/null +++ b/doc_template/pom.xml @@ -0,0 +1,161 @@ + + + + + + org.openpowerfoundation.docs + workgroup-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + + + todo-artifact_id + + jar + + + todo-name + + + + + 0 + + + + + + + + + org.openpowerfoundation.docs + + openpowerdocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + ${comments.enabled} + openpower-template-guide + 1 + UA-17511903-1 + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + book/appendix nop + book/chapter nop + chapter toc,title + chapter/section nop + section toc + part toc,title + reference toc,title + set toc,title + + + 1 + 1 + 1 + + + todo-builddir-name + + + todo-pdfFile-name + + + + workgroupSpecification + + + + + workgroupConfidential + + + + + draft + + + + + + + + + true + . + + + bk_main.xml + + + + + ${basedir}/../glossary/glossary-terms.xml + 1 + www.openpowerfoundation.org + + + + + diff --git a/doc_template/sec_example.xml b/doc_template/sec_example.xml new file mode 100644 index 0000000..8bd05dd --- /dev/null +++ b/doc_template/sec_example.xml @@ -0,0 +1,25 @@ + +
+ + Sample section include + This section was developed in a separate file but included in the document by using the following + text:]]> + where sec_example.xml is the source file name. + +
diff --git a/errata_template/bk_main.xml b/errata_template/bk_main.xml new file mode 100644 index 0000000..2fa45e5 --- /dev/null +++ b/errata_template/bk_main.xml @@ -0,0 +1,117 @@ + + + + + +]> + + + + + <TBD Base Document Name> Errata + For <TBD Base Document Name and version> + + + + + + + TBD Work Group Name + + tbd-chair@openpowerfoundation.org + + OpenPower Foundation + + + + 2018 + OpenPOWER Foundation + + Revision 1.0 + OpenPOWER + + + + + + + + + + + Copyright details are filled in by the template. + + + + + + This document provides errata against version + #.#.# of the + Base Document Title + specification. These errata should be considered part of said specification until such + time as a newer version of the full specification is published. + This document is a Non-standard Track, Work Group Note work + product owned by the + TBD Workgroup + and handled in compliance with the requirements outlined in the + OpenPOWER Foundation Work Group (WG) Process document. It was + created using the Master Template Guide version &template_version;. + Comments, questions, etc. can be submitted to the + public mailing list for the parent specification at + + + tbd@mailinglist.openpowerfoundation.org. + + + + + + 2018-08-29 + + + + TODO: Describe your initial draft, e.g. from where it came if not created from scratch + + + + + + + + + + + + + + + + + + + + + diff --git a/errata_template/ch_errata.xml b/errata_template/ch_errata.xml new file mode 100644 index 0000000..36088d6 --- /dev/null +++ b/errata_template/ch_errata.xml @@ -0,0 +1,78 @@ + + + +Errata + + +The following statements in version + #.#.# + of the + Base Document Title + specification are incorrect, and should be considered corrected as specified. + + +
+ + Section <#.#>, <Section Name> + + Problem: + + TBD: Describe the problem here. For example, + "Paragraph 2 contains a statement that makes use of undefined behavior according to the C standard." + Then, cite the offending text in the next paragraph block. + + + +
+ + + Regardless of the alignment rules for the allocation of data types, + pointers to both aligned and unaligned data of each data type shall + return the value corresponding to a data type starting at the specified + address when accessed with either the pointer dereference operator * or + the array reference operator [ ]. + + +
+ + + + Resolution: + TBD: Describe resolution. For example, + "Paragraph 2 is stricken from the text." If needed, add a block quote of the + updated text like below. + + + + +
+ + + C pointer types have an emperical and undefined behavior which applications + should simply tolerate. Therefore and regardless of the alignment rules for + the allocation of data types, pointers to both aligned and unaligned data of + each data type shall return the value corresponding to a data type starting at the specified + address when accessed with either the pointer dereference operator * or + the array reference operator [ ]. Anything that doesn't work is somebody else's + problem. + + +
+ +
+ + diff --git a/errata_template/pom.xml b/errata_template/pom.xml new file mode 100644 index 0000000..bf8f71f --- /dev/null +++ b/errata_template/pom.xml @@ -0,0 +1,159 @@ + + + + + + org.openpowerfoundation.docs + workgroup-pom + 1.0.0-SNAPSHOT + ../pom.xml + + 4.0.0 + + + todo-errata + + jar + + + todo-errata + + + + + 0 + + + + + + + + + org.openpowerfoundation.docs + + openpowerdocs-maven-plugin + + + + generate-webhelp + + generate-webhelp + + generate-sources + + + ${comments.enabled} + openpower-template-guide + 1 + UA-17511903-1 + + appendix toc,title + article/appendix nop + article toc,title + book toc,title,figure,table,example,equation + book/appendix nop + book/chapter nop + chapter toc,title + chapter/section nop + section toc + part toc,title + reference toc,title + set toc,title + + + 1 + 3 + 1 + + + todo-errata + + + todo-pdfFile-errata + + + workgroupNotes + + + + + + workgroupConfidential + + + + + draft + + + + + + + + true + . + + bk_main.xml + + + + + ${basedir}/../glossary/glossary-terms.xml + 1 + www.openpowerfoundation.org + + + + + diff --git a/pom.xml b/pom.xml index 0f2816e..7b370ef 100644 --- a/pom.xml +++ b/pom.xml @@ -17,6 +17,8 @@ - template + doc_dev_guide + doc_template + errata_template diff --git a/template/figures/project_structure_graphic.odg b/template/figures/project_structure_graphic.odg deleted file mode 100644 index 807414e..0000000 Binary files a/template/figures/project_structure_graphic.odg and /dev/null differ