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.

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. In some XML validation failure scenarios, the lineNumber or colNumber values are not specified or are -1. If you encounter such a situation, please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org so they can assist in identifying the exact location of the failure. 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 the most common 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. When creating new documentation projects, you may encounter the following error during your first build:... [ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp (generate-webhelp) on project openpower-vector-programming-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp failed: One of setGitDir or setWorkTree must be called. -> [Help 1] ... This error results from interactions of the maven build process and git. It may be circumvented by issuing the git init command in your directory.

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 Documentation Development 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. This error generally indicates a problem with documentation tooling. If you encounter such a situation, please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org so they can assist in identifying the exact cause of the failure. If you wish to fully understanding the error, you 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.