Creating a new document from scratch follows four simple steps: Clone the appropriate template document framework. Copy the template directory into a new project directory. Modify core project files. Begin adding document content, either from scratch or from another document.

All new projects need to begin by cloning the appropriate documentation template. The template document project resides at https://github.com/open-power/openpower-foundation-docbkx-framework.git. This template should be used for both private and public OpenPOWER Foundation documents. To clone the existing template document framework use the clone git command:$git clone https://github.com/open-power/openpower-foundation-docbkx-framework.git Cloning into 'openpower-foundation-docbkx-framework'... remote: Counting objects: 288, done. remote: Compressing objects: 100% (157/157), done. remote: Total 288 (delta 121), reused 288 (delta 121) Receiving objects: 100% (288/288), 12.41 MiB | 8.04 MiB/s, done. Resolving deltas: 100% (121/121), done. Checking connectivity... done. $ This command clones the head of the git tree into your current working directory. If successful, the contents of the current directory should now include a new openpower-foundation-docbkx-framework directory.

To create a new document directory, follow these steps: Navigate down to the doc sub-directory. On Linux and Mac OS command lines, this can be achieved using the cd command: $cd /openpower-foundation-docbkx-framework/doc $ This directory should contain at least two directories, one named doc and another template, as well as a pom.xml file. To create a new project directory, simply create a new directory and copy the contents of the template directory. If creating a new project named my_proj via a command line in Linux or Mac OS, the command sequence would look like this: $mkdir my_proj $cp -r template/* my_proj $ Finally, make sure to add the new directory to the git repository. $git add my_proj

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 openpower-foundation-docbkx-framework/doc/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 ~/openpower-foundation-docbkx-framework/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.

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.