Maven/docbkx failures generally fall into these categories: Project structure errors Docbook validation errors Build failures Correcting the document errors starts with understanding which type of failure has occurred and understanding where to look in your document source.

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.

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