diff --git a/README.md b/README.md index d654ab8..1bf5d39 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,12 @@ Document library at [TBD](http://openpowerfoundation.org/docs) The project which control the look and feel of the document is the [Docs-Maven-Plugin project](https://github.com/OpenPOWERFoundation/Docs-Maven-Plugin). +## License +This project is licensed under the Apache V2 license. More information +can be found in the LICENSE file or online at + + http://www.apache.org/licenses/LICENSE-2.0 + ## Contributions To contribute to the OpenPOWER Foundation template document project, contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\). diff --git a/template/bk_main.xml b/template/bk_main.xml index 1185240..7f121b5 100644 --- a/template/bk_main.xml +++ b/template/bk_main.xml @@ -46,7 +46,7 @@ OpenPOWER Foundation - Revision 0.9.3 + Revision 0.9.4 OpenPOWER @@ -54,8 +54,8 @@ "apache2" for an Apache V2 license or "opfExternal" for an official OpenPOWER Foundation external license text. If you don't know which one to select, leave as "apache2" --> - - + + Copyright details are filled in by the template. @@ -76,6 +76,16 @@ + + 2016-03-21 + + + + Version 0.9.4: Review version for TSC. + + + + 2016-02-25 diff --git a/template/sec_template_debugging.xml b/template/sec_template_debugging.xml index dcd90cf..82f6f3a 100644 --- a/template/sec_template_debugging.xml +++ b/template/sec_template_debugging.xml @@ -20,15 +20,16 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug"> Debugging build failures 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. -
- Project structure errors +
+ Project structure errors Because the OpenPOWER Foundation documentation projects are not self-contained in the GitHub repositories, forgetting to clone the Docs-Master project in addition @@ -46,7 +47,8 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug"> [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 +[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 @@ -60,8 +62,8 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug">
-
- Docbook validation errors +
+ Docbook validation errors Validation errors are generally indicated in the build output with text like the following: ... @@ -80,8 +82,7 @@ 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", ... - +lineNumber: 272; columnNumber: 70; text not allowed here; expected element "address", ... This error message contains three key pieces of information: @@ -98,8 +99,8 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add
-
- Build failures +
+ Build failures Build errors are easily identified as well. Below is an example: ... @@ -110,8 +111,8 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add [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]... - +[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: @@ -132,5 +133,96 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add correction. Online resources such as those listed in may be helpful.
+
+ FO validation failures + + 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 Master Template 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. + + Fully understanding the error, 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. + +