diff --git a/Intrinsics_Reference/sec_template_debugging.xml b/Intrinsics_Reference/sec_template_debugging.xml deleted file mode 100644 index 82f6f3a..0000000 --- a/Intrinsics_Reference/sec_template_debugging.xml +++ /dev/null @@ -1,228 +0,0 @@ - -
- - Debugging build failures - Maven/docbkx failures generally fall into these categories: - - - - - - - Correcting the document errors starts with understanding which type of failure has occurred and - understanding where to look in your document source. - -
- Project structure errors - - Because the OpenPOWER Foundation documentation projects are not self-contained in the - GitHub repositories, forgetting to clone the Docs-Master 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: -... -[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 -... - The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the - pom.xml file in the documentation project, called the "workgroup-pom" because of a project - <artifactId>workgroup-pom</artifactId> declaration, expects its parent pom file to be in the - location defined by the <relativePath>../Docs-Master/pom.xml</relativePath>, up one directory and - then in the Docs-Master director. - - - So, if you see the message "Non-resolvable parent POM", ensure that the Docs-Master project - and your project have been cloned - into the same parent directory. See for detailed directions on how to do this. - -
- -
- Docbook validation errors - - Validation errors are generally indicated in the build output with text like the following: -... -@@@@@@@@@@@@@@@@@@@@@@ -!!!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", ... - This error message contains three key pieces of information: - - - 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. - - - The location within the file of the syntax error. For the above example, the key information is "lineNumber: 272; columnNumber: 70. - - - An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...". - - - -
- -
- Build failures - - Build errors are easily identified as well. Below is an example: -... -[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] -... - - 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. - - - The location within the file of the error is "lineNumber: 55; columnNumber: 17. - - - An explanation of the failure begins with the text, "The element type "para" must be terminated by the - matching end-tag "</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 may be helpful. -
- -
- FO validation failures - - FO (formatting objects) validation failures are a slight bit more difficult to identify and require more effort to correct. A sample appears as follows: -... -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] -... - - The "org.apache.fop.fo.ValidationException" text indicates that this error was during FO validation. The key pieces of information are as follows: - - - The error type is indicated in the text following the exception indictor. In our case, the error statement is: - "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!. This error clearly - has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement. - - - The location of the validation error is given in the statement - "See position 70:-1". 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 -1 is an indication that the line is too long to effectively point. - - - - 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 includes a reference to this file which will be found in the - .../target/ directory. It generally has the same name as the main book file of the document, which if copied - from the Master Template Guide project, will be bk_main.xml. When in doubt about - this file name, you will find it in the <includes> tag in the pom.xml file. - - 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 .fo - file which can be found in the .../target/docbkx/autopdf/ directory and typically has the same base file name as - the target PDF file. Again, the pom.xml file will clarify this name with the <pdfFilenameBase> - variable. - - 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 xmllint 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: - $ cd target/docbkx/autopdf -$ xmllint --nonet --noent --nowarning --version --timing --format -o outfile infile -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 -$ - - For your invocation of xmllint, substitute infile with the name of the Maven-generated - .fo file for your new project and pick a new outfile for the new .fo file. - - The xmllint utility may need to be loaded on your system. On an Ubuntu Linux system, - this utility is provided in the libxml2-utils package. To locate the proper package for your system, - you may need to reference Google. - - 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 - fop as follows:$ fop -fo fofile and -pdf pdffile -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) -$ - - 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. - - Fully understanding the error, may require knowing more about XSL FO syntax. Many such web sites exist for this, but - the XSL Formatting Objects Summary from W3C (World Wide Web Consortium) provides a good starting reference online at - https://www.w3.org/2002/08/XSLFOsummary.html. - -
-
- diff --git a/Intrinsics_Reference/sec_template_existing_document.xml b/Intrinsics_Reference/sec_template_existing_document.xml deleted file mode 100644 index b21896d..0000000 --- a/Intrinsics_Reference/sec_template_existing_document.xml +++ /dev/null @@ -1,95 +0,0 @@ - -
- - 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 . - - Once complete, obtain a copy of the desired document by cloning its project. For example, to clone this document, - Master Template Guide, from the - public OpenPOWER Foundation git repository, use this - command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git -Cloning into 'Docs-Template'... -Username for 'https://github.com': my_userid -Password for 'https://my_userid@github.com': my_password -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. -$ - - To build a specific document such as the template guide, follow these steps from the directory where - you just cloned:$ cd Docs-Template/template -$ mvn clean -[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] ------------------------------------------------------------------------ -$ mvn generate-sources -[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] ------------------------------------------------------------------------ -$ - - 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 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/. - - For assistance correcting commmon build failures, see . - - Projects may contain multiple documents. While specific documents can be built by executing a - mvn clean generate-sources in the specific document directory, executing this command in - 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. - -
- diff --git a/Intrinsics_Reference/sec_template_faq.xml b/Intrinsics_Reference/sec_template_faq.xml deleted file mode 100644 index 019963c..0000000 --- a/Intrinsics_Reference/sec_template_faq.xml +++ /dev/null @@ -1,34 +0,0 @@ - -
- - Frequently asked questions - The list of questions and answers may be helpful to first time document writers: - - - 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/Intrinsics_Reference/sec_template_getting_started.xml b/Intrinsics_Reference/sec_template_getting_started.xml deleted file mode 100644 index 7d38fe0..0000000 --- a/Intrinsics_Reference/sec_template_getting_started.xml +++ /dev/null @@ -1,105 +0,0 @@ - -
- - Getting started - To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed: - - - Installing tools - - - Creating accounts - - - Cloning master document information - - - - - Once complete, you can proceed to either or - as needed. - -
- Installing tools - 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. - On Debian-based Linux operating systems (Ubuntu and Debian), install maven and git as follows: - # apt-get install git -# apt-get install maven - On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows: - # yum install git -# yum install maven - On Mac OS X, use Macports to install maven and git as follows: - # port install git -# port install maven3 - or use Homebrew to install maven and git as follows: - $ brew install git -$ brew install maven - For information on how to setup the environment on Windows, see the following websites: - - - git for Windows - http://msysgit.github.io/ - - - Maven on Windows - - http://maven.apache.org/guides/getting-started/windows-prerequisites.html - - - - 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 http://bluefish.openoffice.nl/index.html. -
- -
- Creating accounts - All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first - step to creating documentation will be joining the GitHub community. - To join the GitHub community, - apply at https://github.com/join. - The OpenPOWER Foundation documentation trees are grouped in the OpenPOWER Foundation project at - https://github.com/OpenPOWERFoundation. - 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, tsc-chair@openpowerfoundation.org. - To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at - - https://help.github.com/articles/good-resources-for-learning-git-and-github/. -
- -
- Cloning master document information - 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 Docs-Master. - To clone the master template document framework use the clone git command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git -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. -$ - More information can be found about the Docs-Master project online at - https://github.com/OpenPOWERFoundation/Docs-Master. Additional details about the OpenPOWER Foundation documentation structure - are explained in of this document. -
-
- diff --git a/Intrinsics_Reference/sec_template_git_commands.xml b/Intrinsics_Reference/sec_template_git_commands.xml deleted file mode 100644 index c66c351..0000000 --- a/Intrinsics_Reference/sec_template_git_commands.xml +++ /dev/null @@ -1,182 +0,0 @@ - -
- - Common git commands - 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. - - - - - To clone a git tree for first time or temporary use via http, - use:$ git clone <URL> - The <URL> value for OpenPOWER Foundation GitHub projects can be found on the project web pages. - They generally take the form of https://github.com/OpenPOWERFoundation/project_name where the - project_name can be found on the OpenPOWER Foundation Git Hub community page at - https://github.com/OpenPOWERFoundation. 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. - Trees can only be cloned once. To update a tree, use a git pull or git merge - command. - When cloning from a private tree, you will be prompted for your GitHub userid and password. - - - - To update a git tree with new files from the remote repository, - use:$ git pull - 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 git status command to see what has changed in a local tree. - When pulling from a private tree, you will be prompted for your GitHub userid and password. - - - - To see the status of the local repository, - use:$ git status - This command identifies files which have changed in the local repository and provides suggestions on how to handle. - - Adding the -s parameter to the end of the command will provide a simplified view in which changed files - are listed with flags such as M for modified files, A for newly added files, - and ?? for new or unknown files. This parameter also suppresses suggested action information for the files. - - - - To add a new file or directory to a git tree, - use:$ git add <new_file> - The <new_file> 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 git status -s - command from ?? to A or move it from the "Untracked files" section to the - "Changes to be committed" section of the git status command. - - - - To remove a file from a git tree, - use:$ git rm <file> - The <file> 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 D in the git status -s - command and be reflected in the "Changes not staged for commit" section of thegit status command - with a "deleted:" status. - - - - To remove a directory from a git tree, - use:$ git rm -rf <directory> - The <directory> 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 rmdir <directory> command must be issued separately to - remove the local directory. All removed files will show in - a status modifier of D in the git status -s - command and be reflected in the "Changes not staged for commit" section of thegit status command with a - "deleted:" status. Because git does not - track directories, they will not be reflected in status. - - - - To move or rename a file or directory in a git tree, - use:$ git mv <source> <destination> - The <source> value must be a file or directory and may include the path to - the target file. The <destination> 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. - - - - To commit all local changes to the staging area for a git tree, - use:$ git commit -a - 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. Signed-off-by: Your name <your_email@domain.com> - For information on the DCO, see Developer Certificate Of Origin at - http://elinux.org/Developer_Certificate_Of_Origin. - - - - To push all locally staged changes to the remote git tree, - use:$ git push - When pushing to a private tree, you will be prompted for your GitHub userid and password. - - - - To see what tags exist in a git tree, - use:$ git tag - - - - To create a new tag locally, - use:$ git tag -a <tag_name> -m"text" - The tag_name represents the simple value of the tag. The text string - provides more description of the tag for readibility. - This command simply tags locally. See the next command for how to push the tag to the remote repository. - - - - To push a new tag from the local tree to the remote tree, - use:$ git push origin <tag_name> - This commands assumes the git tag command has been run on the local tree. - - - - To discard changes from a locally changed file and return to the last copy, - use:$ git checkout -- <file> - The <file> value must be a file and may include wildcard characters or the path to - the target file. - - - - To identify what changes have been made locally to a file - use:$ git diff <file> - The <file> 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 diff command. - - - - - Additional resources about git can be found online at the following locations: - - - - - The GitHub Glossary at - https://help.github.com/articles/github-glossary/. - This site provides a list of common terms associated with git and GitHub. - - - - The GitHub Git Cheat Sheet at - - https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf. - This two page pdf provides a quick summary of many common commands. - - - - - The Git Reference at - http://gitref.org/. This is a deeper and more comprehensive reference of important commands. - - - - The git-scm.com Documentation library at - http://git-scm.com/doc. This site provides education in the form of books, videos, - and other tutorials for common git activities. - - - - - -
- diff --git a/Intrinsics_Reference/sec_template_new_document.xml b/Intrinsics_Reference/sec_template_new_document.xml deleted file mode 100644 index b76a836..0000000 --- a/Intrinsics_Reference/sec_template_new_document.xml +++ /dev/null @@ -1,274 +0,0 @@ - -
- - Creating a new document - Creating a new document from scratch follows four simple steps: - - - Cloning the project source. - - - Finding a document framework. - - - Modifying core project files. - - - Adding new document content. - - - -
- Clone the project source. - All documentation projects reside in a project directory maintained in GitHub, just like the - Docs-Master framework described in . In the same directory - where the Docs-Master 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 - https://github.com/OpenPOWERFoundation/. Select - the project from this list. - - If you do not see the project for which you are looking, you may not be authorized to it. See - 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, tsc-chair@openpowerfoundation.org, to request and get this setup. - - To clone an OpenPOWER Foundation project like Docs-Template issue the following - command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git -Cloning into 'Docs-Template'... -Username for 'https://github.com': my_userid -Password for 'https://my_userid@github.com': my_password -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. -$ The results should look roughly something like above with actual numbers of objects, files, etc. varying - for different projects. - - Private projects prompt for a GitHub userid and and password. When cloning public projects, these prompts - are skipped. - - The base project has now been cloned. -
- -
- Finding a document framework - 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 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 - file, a LICENSE file, and a README.md file. If this is the case, you simply - need to perform the following three steps: - - - - Navigate down to your project directory, called my_project for this example. This can be achieved - using the cd command: -$ cd ~/my_project -$ - This directory should contain the template folder used to prime the project. - - - Rename the template document directory to something new like my_doc. - To accomplish this, use the mv command:: -$ mv template/ my_doc - - - 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:template -]]> to read like this:my_doc -]]> - - - - If this is not the first document in the project, then you can either begin by copying an existing document or by cloning the - Docs-Template project. To copy an existing project, follow these steps: - - - - Navigate down to your project directory, called my_project for this example. - This can be achieved using the cd command: -$ cd ~/my_project -$ - This directory should contain the folder name of the document wishing to be copied, called source_doc - for clarity in these directions. - - - To create a new document directory, simply create a new directory and copy the contents of the source_doc - directory. If creating a new directory named my_doc via a command line, the command - sequence would look like this: -$ mkdir my_doc -$ cp -r source_doc/* my_doc -$ - - - 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:my_doc -]]> - - - - 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: - - - - Navigate down to your project directory, called my_project for this example. - This can be achieved using the cd command: -$ cd ~/my_project -$ - This directory should contain any existing document folders along with at least a pom.xml file, a - LICENSE file, and a README.md file. - - - Clone the the template project into your working directory with this - command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git -Cloning into 'Docs-Template'... -Username for 'https://github.com': my_userid -Password for 'https://my_userid@github.com': my_password -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. -$ - - - To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/template - 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 -$ - - - 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 - between the <modules> and the </modules> tags near the top of the file:my_doc -]]> - - - - 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 git add my_doc/ command on the whole directory. - - - - You are now ready to begin making updates to your new document. The next section will provided detailed steps of where to - get started. -
- -
- Modifying core project files - The first step to customizing a new project is to modify two core project files--pom.xml - 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>, - 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> - and <pdfFilenameBase>, as these will be used to locate your generated document. - When ready, build your new document using standard maven commands like - this:$ cd my_proj/my_doc -$ mvn clean -[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] ------------------------------------------------------------------------ -$ mvn generate-sources -[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] ------------------------------------------------------------------------ -$ - If all goes well, the new generated pdf should be available in - target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf. - For assistance correcting commmon build failures, see . - - 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 mvn clean generate-sources would accomplish the - same thing as the above sequence of commands. -
- -
- 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 will be controlled by entries near the - end of that file which appear as follows: - - - - - - - - - - - - -]]> - - 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 ch_example.xml and app_template.xml files - may serve as excellent starting points. For XML examples of various document structures, please see - and its supporting source files in this document. Online resources such as those listed in - may also be helpful. - - When creating new files for the project, remember to use the git add <file name> command to - add new files to the git tree. - -
- -
- diff --git a/Intrinsics_Reference/sec_template_policies.xml b/Intrinsics_Reference/sec_template_policies.xml deleted file mode 100644 index ff8f382..0000000 --- a/Intrinsics_Reference/sec_template_policies.xml +++ /dev/null @@ -1,59 +0,0 @@ - -
- - Policies and conventions - 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. - The recommended documentation structure guidelines are as follows: - - - 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 N.N", not "Version N.N" or simply "N.N" - - - Chapters files should be named with the prefix "ch_". - - - Section and sub-section files should be named with the prefix "sec_". - - - Appendix files should be named with the prefix "app_". - - - Figures source and images should be placed in the figures sub-directory for the document. - - - - In addition to documentation structure, general community/project guidelines are as follows: - - - Contributions to the documentation projects should conform to the Developer Certificate - Of Origin as defined at - http://elinux.org/Developer_Certificate_Of_Origin. Commits to the GitHub project need - to contain the following line to indicate the submitter accepts the - DCO:Signed-off-by: Your name <your_email@domain.com> - - - - -
diff --git a/Intrinsics_Reference/sec_template_process.xml b/Intrinsics_Reference/sec_template_process.xml deleted file mode 100644 index 88f8391..0000000 --- a/Intrinsics_Reference/sec_template_process.xml +++ /dev/null @@ -1,169 +0,0 @@ - -
- - Publishing OpenPOWER Documents - The OpenPOWER Foundation Work Group (WG) Process 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. - - 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. - - 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: - -
- Document work flow for Standard Track Work Products - - - - - -
- - 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. - - Non-standard Track Work Products exist simply as Work Group Notes. Their document - lifecycle follows this simplified workflow: - -
- Document work flow for Non-standard Track Work Products - - - - - -
- - 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). - - Once these decisions have been made, then they can be reflected into the document in the following ways: - - - - - The document Work Product type is defined in the document pom.xml file with the - <workProduct> variable. Valid settings are workgroupNotes, - workgroupSpecification, candidateStandard, and openpowerStandard. - Select the appropriate setting in the following section: - -workgroupNotes - - -]]> - - - - The document security is set in the document pom.xml file with the - <security> variable. Valid settings are public, - foundationConfidential, and workgroupConfidential. - Select the appropriate setting in the following section: - -workgroupConfidential - -]]> - - - - The document work flow status is set in the document pom.xml file with the - <documentStatus> variable. Valid settings are draft, - review, and published. - Select the appropriate setting in the following section: - -draft - -]]> - - - - The final place to make updates to a new document is in the <abstract> section of - the bk_main.xml file for the document. This section needs to be updated with the appropriate - work group information and document information. Typical text appears as follows: - - - 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. - 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 OpenPOWER Foundation Work Group (WG) - Process document. -]]> - 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. - - - - -
- diff --git a/Intrinsics_Reference/sec_template_references.xml b/Intrinsics_Reference/sec_template_references.xml deleted file mode 100644 index 96a7344..0000000 --- a/Intrinsics_Reference/sec_template_references.xml +++ /dev/null @@ -1,38 +0,0 @@ - -
- - Finding more information - The following lists of references may be helpful in learning about XML, Docbook, and/or Maven: - - - XML In a Nutshell by Elliotte Rusy Harold and W. Scott Means. Online at http://docstore.mik.ua/orelly/xml/xmlnut/index.htm. - - - DocBook 5: The Definitive Guide by Normal Walsh. Online at https://www.safaribooksonline.com/library/view/docbook-5-the/9781449380243/. - - - DocBook XSL: The Complete Guide by Bob Stayton. Online at http://www.sagehill.net/docbookxsl/. - - - Maven: The Complete Reference by Tim O'Brien, Manfred Moser, John Casey, Brian Fox, Jason Van Zyl, Eric Redmond, and Larry Shatzer. Online at http://books.sonatype.com/mvnref-book/reference/index.html. - - - -
- diff --git a/Intrinsics_Reference/sec_template_structure.xml b/Intrinsics_Reference/sec_template_structure.xml deleted file mode 100644 index 67c8570..0000000 --- a/Intrinsics_Reference/sec_template_structure.xml +++ /dev/null @@ -1,88 +0,0 @@ - -
- - Understanding the project structure - 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. - - As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation - document requires two things: - - The cloning of the Docs-Master project. - The cloning of the specific documentation project into the same parent directory as the - Docs-Master project. - - To begin to understand why, let us use a picture. The following graphic illustrates - the directory structure of three projects -- two - Docs-Master and Docs-Template, both existing OpenPOWER Foundation GitHub projects and a - hypothetical new project named my_project. - -
- Directory structure and key files in the OpenPOWER Foundation Docbook projects - - - - - -
- - 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 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. - - Inside the Docs-Masterproject directory, the two most important pieces are a - commmon directory - and a pom.xml file. The directory contains common files used by all projects such as the common preface - (ch_preface.xml) and the common appendix (app_foundation.xml. The pom.xml 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 - http://openpowerfoundation.org/repo.openpowerfoundation.org/) - used to control the OpenPOWER - Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. - - The Docs-Template project and directory are depicted in blue in the above figure. The top level of the - project Docs-Template must be cloned into the same parent directory as the Docs-Master - 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 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 - 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. - - For completeness of understanding, a hypothetical project my_project is also depected in red. Like all - OpenPOWER Foundation projects, it is cloned at the correct level, equal to Docs-Master. Like the - Docs-Template project, it has a "Workgroup POM" which will differ only in the <modules> - section where it will describe two document projects, my_doc_1 and my_doc_2. But, each - document directory has similar contents to Docs-Template/template -- a "Document POM" (pom.xml) - and a "Main book file" (bk_main.xml). -
-