You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
229 lines
15 KiB
XML
229 lines
15 KiB
XML
<!--
|
|
Copyright (c) 2016 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug">
|
|
|
|
<title xml:id="section_template_debug_title">Debugging build failures</title>
|
|
<para>Maven/docbkx failures generally fall into these categories:</para>
|
|
<itemizedlist>
|
|
<listitem><para><xref linkend="section_template_debug_structure_error" endterm="section_template_debug_structure_error_title"/></para></listitem>
|
|
<listitem><para><xref linkend="section_template_debug_docbook_validation_error" endterm="section_template_debug_docbook_validation_error_title"/></para></listitem>
|
|
<listitem><para><xref linkend="section_template_debug_build_failure" endterm="section_template_debug_build_failure_title"/></para></listitem>
|
|
<listitem><para><xref linkend="section_template_debug_fo_validation_error" endterm="section_template_debug_fo_validation_error_title"/></para></listitem>
|
|
</itemizedlist>
|
|
<para>Correcting the document errors starts with understanding which type of failure has occurred and
|
|
understanding where to look in your document source.</para>
|
|
|
|
<section xml:id="section_template_debug_structure_error">
|
|
<title xml:id="section_template_debug_structure_error_title">Project structure errors</title>
|
|
|
|
<para>Because the OpenPOWER Foundation documentation projects are not self-contained in the
|
|
GitHub repositories, forgetting to clone the <literal>Docs-Master</literal> 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:</para>
|
|
<screen>...
|
|
[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
|
|
...</screen>
|
|
<para>The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the
|
|
<literal>pom.xml</literal> file in the documentation project, called the "workgroup-pom" because of a project
|
|
<literal><artifactId>workgroup-pom</artifactId></literal> declaration, expects its parent pom file to be in the
|
|
location defined by the <literal><relativePath>../Docs-Master/pom.xml</relativePath></literal>, up one directory and
|
|
then in the <literal>Docs-Master</literal> director.
|
|
</para>
|
|
|
|
<para>So, if you see the message "Non-resolvable parent POM", ensure that the <literal>Docs-Master</literal> project
|
|
and your project have been cloned
|
|
into the same parent directory. See <xref linkend="section_cloning_master_doc"/> for detailed directions on how to do this.</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_template_debug_docbook_validation_error">
|
|
<title xml:id="section_template_debug_docbook_validation_error_title">Docbook validation errors</title>
|
|
|
|
<para>Validation errors are generally indicated in the build output with text like the following:
|
|
<screen>...
|
|
@@@@@@@@@@@@@@@@@@@@@@
|
|
!!!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", ...</screen></para>
|
|
<para>This error message contains three key pieces of information:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The full path and filename that contains the context for the failure. In the message above, this is
|
|
<literal>/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The location within the file of the syntax error. For the above example, the key information is "<literal>lineNumber: 272; columnNumber: 70</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_template_debug_build_failure">
|
|
<title xml:id="section_template_debug_build_failure_title">Build failures</title>
|
|
|
|
<para>Build errors are easily identified as well. Below is an example:
|
|
<screen>...
|
|
[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]
|
|
...</screen></para>
|
|
|
|
<para>Like validation errors, three key pieces of information are again provided:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The full path and filename of our failure is
|
|
<literal>/home/user1/Docs-Template/template/sec_template_new_document.xml</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The location within the file of the error is "<literal>lineNumber: 55; columnNumber: 17</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An explanation of the failure begins with the text, "The element type "para" must be terminated by the
|
|
matching end-tag "</para>."</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<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 <xref linkend="section_template_references"/> may be helpful.</para>
|
|
</section>
|
|
|
|
<section xml:id="section_template_debug_fo_validation_error">
|
|
<title xml:id="section_template_debug_fo_validation_error_title">FO validation failures</title>
|
|
|
|
<para>FO (formatting objects) validation failures are a slight bit more difficult to identify and require more effort to correct. A sample appears as follows:
|
|
<screen>...
|
|
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]
|
|
...</screen></para>
|
|
|
|
<para>The "<literal>org.apache.fop.fo.ValidationException</literal>" text indicates that this error was during FO validation. The key pieces of information are as follows:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The error type is indicated in the text following the exception indictor. In our case, the error statement is:
|
|
<literal>"{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!</literal>. This error clearly
|
|
has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The location of the validation error is given in the statement
|
|
"<literal>See position 70:-1</literal>". 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 <literal>-1</literal> is an indication that the line is too long to effectively point.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>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 <xref linkend="section_template_debug_docbook_validation_error"/> includes a reference to this file which will be found in the
|
|
<literal>.../target/</literal> directory. It generally has the same name as the main book file of the document, which if copied
|
|
from the <citetitle>Master Template Guide</citetitle> project, will be <literal>bk_main.xml</literal>. When in doubt about
|
|
this file name, you will find it in the <literal><includes></literal> tag in the <literal>pom.xml</literal> file.</para>
|
|
|
|
<para>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 <literal>.fo</literal>
|
|
file which can be found in the <literal>.../target/docbkx/autopdf/</literal> directory and typically has the same base file name as
|
|
the target PDF file. Again, the <literal>pom.xml</literal> file will clarify this name with the <literal><pdfFilenameBase></literal>
|
|
variable.</para>
|
|
|
|
<para>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 <literal>xmllint</literal> 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:
|
|
<screen><prompt>$ </prompt><userinput>cd target/docbkx/autopdf</userinput>
|
|
<prompt>$ </prompt><userinput>xmllint --nonet --noent --nowarning --version --timing --format -o outfile infile</userinput>
|
|
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
|
|
<prompt>$</prompt></screen></para>
|
|
|
|
<para>For your invocation of <literal>xmllint</literal>, substitute <literal>infile</literal> with the name of the Maven-generated
|
|
.fo file for your new project and pick a new <literal>outfile</literal> for the new .fo file.</para>
|
|
|
|
<note><para>The <literal>xmllint</literal> utility may need to be loaded on your system. On an Ubuntu Linux system,
|
|
this utility is provided in the <literal>libxml2-utils</literal> package. To locate the proper package for your system,
|
|
you may need to reference Google.</para></note>
|
|
|
|
<para>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
|
|
<literal>fop</literal> as follows:<screen><prompt>$ </prompt><userinput>fop -fo fofile and -pdf pdffile</userinput>
|
|
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)
|
|
<prompt>$</prompt></screen></para>
|
|
|
|
<para>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.</para>
|
|
|
|
<note><para>Fully understanding the error, may require knowing more about XSL FO syntax. Many such web sites exist for this, but
|
|
the <citetitle>XSL Formatting Objects Summary</citetitle> from W3C (World Wide Web Consortium) provides a good starting reference online at
|
|
<link xlink:href="https://www.w3.org/2002/08/XSLFOsummary.html">https://www.w3.org/2002/08/XSLFOsummary.html</link>.</para></note>
|
|
|
|
</section>
|
|
</section>
|
|
|