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 existing OpenPOWER Foundation GitHub projects, Docs-Master and Docs-Template, and a hypothetical new project named my_project.

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" (POM stands for Program Object Model and serves as the main configuration file) 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 depicted 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).