- Bumped version to 0.9.4
- Added FO validation error debugging section with detailed steps
in ch_template_debugging.xml.
- Provided links to sub-sections in top of Debugging section,
again in ch_template.debugging.xml.
- Added License section with reference to Apache V2 license to README.md
Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
[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>
[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>
@ -132,5 +133,96 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add
correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
<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)
[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:
<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
Jeff Scheel
8 years ago