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.

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.

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

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. 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 complete, be sure to 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.

The starting point for book content is the bk_main.xml file (or whatever to which it was renamed in the previous step). Removal and additions of the main chapter files files will be controlled by entries near the 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.