You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Vincent Hennebert <vh...@gmail.com> on 2012/10/09 17:10:59 UTC
Re: svn commit: r1342781 - in /xmlgraphics/fop/trunk: src/documentation/content/xdocs/bugs.xml
src/documentation/content/xdocs/faq.xml status.xml
(Going through old unread commit messages...)
I’d like to soften a bit the rather martial tone introduced in those
changes. If I were a new user looking into submitting a bug and reading
this page, I think I would refrain from doing so for fear of the police
forces breaking into my home in the middle of the night and pointing
a gun to my head because I dared not to follow the process... :-)
Any objections?
Thanks,
Vincent
On 25/05/12 20:10, gadams wrote:
> Author: gadams
> Date: Fri May 25 19:10:28 2012
> New Revision: 1342781
>
> URL: http://svn.apache.org/viewvc?rev=1342781&view=rev
> Log:
> Update FAQ and New Bug documentation.
>
> Modified:
> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> xmlgraphics/fop/trunk/status.xml
>
> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> ==============================================================================
> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml (original)
> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml Fri May 25 19:10:28 2012
> @@ -45,21 +45,66 @@ an email as changes are made to the issu
> </section>
> <section id="issues_new">
> <title>Unreported Issues (Reporting New Issues)</title>
> - <p>User reports of bugs and requests for enhancements are extremely
> -important parts of FOP development, and we appreciate the time you take to help
> -us track these issues down.</p>
> + <p>
> + User reports of bugs and requests for enhancements are extremely
> + important parts of FOP development, and we appreciate the time you take to help
> + us track these issues down.
> + </p>
> <ul>
> - <li>To help us ensure that the bug database is as useful as it should be, please
> -use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.</li>
> - <li>Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug Writing Guidelines</link> before submitting your report.</li>
> - <li>Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP issue database (Bugzilla)</link>.
> -You will be asked to login to an existing Bugzilla account or to create a new
> -one.
> -When entering the bug report, please make your description complete and concise.
> -If appropriate, attach a minimal fo file to your report which demonstrates the
> -problem.</li>
> - <li>After submission, a copy of your bug report will be automatically
> -sent to the FOP developer discussion list.</li>
> + <li>
> + To help us ensure that the bug database is as useful as it should be, please
> + use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.
> + </li>
> + <li>
> + Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug
> + Writing Guidelines</link> before submitting your report.
> + </li>
> + <li>
> + Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
> + FOP issue database (Bugzilla)</link>. You will be asked to login to an existing Bugzilla account or to
> + create a new one. When entering the bug report, please make your description complete and concise.
> + If the issue involves a specific input or output file, then you <strong>MUST</strong> include the
> + following information in the bug report (preferably as one or more attachments):
> + <ul>
> + <li>
> + an input XSL-FO file (an input XML plus XSLT file is not acceptable, unless and only if the
> + issue being reported is related to the built-in XSLT transform processing convenience function provided
> + by FOP); this input <strong>SHOULD</strong> be <em>maximally minimal</em>, which means that it should
> + contain nothing more than the minimum needed to demonstrate the problem; if you do not take the effort
> + to provide a maximally minimal input FO file, then you will be subsequently asked to do so before the
> + bug is processed;
> + </li>
> + <li>
> + a resulting output file, preferably in PDF format; if the issue being reported involves a different output
> + format, then provide both a PDF output file and the output file for the output format for which the report
> + applies;
> + </li>
> + <li>
> + a copy of the FOP configuration file you used (e.g., fop.xconf);
> + </li>
> + <li>
> + if FOP was invoked using the command line (or an equivalent), then a dump of both the input
> + command line and any console output (stderr or stdout) produced; if the report involves an
> + exception, then this <strong>MUST</strong> include the full stack back trace;
> + </li>
> + <li>
> + information describing the version of FOP you are using and the platform (and OS) on which
> + you are invoking FOP;
> + </li>
> + <li>
> + if the report applies to the use of a specific font other than one of the built-in, base 14
> + fonts, then information that describes where to obtain the font.
> + </li>
> + </ul>
> + </li>
> + <li>
> + After submission, a copy of your bug report will be automatically
> + sent to the FOP developer discussion list. If additional information is needed to
> + process the bug, then the bug will be set to the <code>NEEDSINFO</code> state, and
> + you will be asked to provide the additional information. You can avoid this extra
> + step by being diligent about providing <strong>all</strong> of the information
> + indicated above.
> + </li>
> </ul>
> </section>
> </body>
>
> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> ==============================================================================
> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml (original)
> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml Fri May 25 19:10:28 2012
> @@ -25,7 +25,7 @@
> <question>What is Apache⢠FOP?</question>
> <answer>
> <p>
> - FOP is a print formatter for <link href="#XSLFO">XSL formatting
> + FOP is a print formatter for <link href="#xslfo">XSL formatting
> objects</link>.
> </p>
> <p>
> @@ -65,16 +65,23 @@
> <question>How does FOP interact with other Apache Projects?</question>
> <answer>
> <p>
> - FOP is distributed with <link
> - href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF serializer
> - for XSL (FO) documents.
> + <link href="http://xmlgraphics.apache.org/commons">XML Graphics Commons</link> is used with
> + FOP to provide graphics functions that are common to a number of Apache projects.
> </p>
> <p>
> - <link href="http://xmlgraphics.apache.org/batik">Batik</link> can be used with
> + <link href="http://xmlgraphics.apache.org/batik">Batik</link> is used with
> FOP to <link
> href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode an SVG
> image</link> into a PDF document.
> </p>
> + <p>FOP also makes use of the following Apache projects:</p>
> + <ul>
> + <li><link href="http://excalibur.apache.org/framework/">Avalon Framework</link></li>
> + <li><link href="http://jakarta.apache.org/commons/io/">Jakarta Commons IO</link></li>
> + <li><link href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</link></li>
> + <li><link href="http://xalan.apache.org/">Xalan-J</link></li>
> + <li><link href="http://xml.apache.org/commons/components/external/">XML Commons Externals</link></li>
> + </ul>
> </answer>
> </faq>
> <faq id="xsl-def">
> @@ -83,7 +90,7 @@
> <p>
> XSL is a W3C standard concerned with publishing XML documents. It
> consists of two parts: <link href="#XSLT">XSLT</link> and <link
> - href="#XSLFO">XSL-FO</link>. The acronym expands to
> + href="#xslfo">XSL-FO</link>. The acronym expands to
> e<strong>X</strong>tensible <strong>S</strong>tylesheet
> <strong>L</strong>anguage.
> </p>
> @@ -93,7 +100,9 @@
> <question>What is XSL-FO?</question>
> <answer>
> <p>
> - XSLFO (aka XSL-FO) is an XML vocabulary that is used to specify a pagination and
> + XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C Recommendation
> + <link href="http://www.w3.org/TR/xsl/">Extensible Stylesheet Language (XSL)
> + Version 1.1</link>, that is used to specify a pagination and
> other styling for page layout output. The acronym “FO”
> stands for
> <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO can be
> @@ -226,8 +235,7 @@
> <answer>
> <p>
> This is usually caused by an older version of one of the FOP jars or
> - old XML tools in the classpath. Check in particular for parser.jar,
> - jaxp.jar, xml4j.jar or lotusxsl.jar.
> + old XML tools in the classpath.
> </p>
> <p>
> Incompatible versions of Batik may also cause this problem. Use the
> @@ -269,8 +277,9 @@
> the <code>file:</code> prefix, for example <code>file.ext</code>,
> <code>path/file.ext</code> or <code>../file.ext</code>. The string
> <code>file:path/file.ext</code> is <em>not</em> a relative URL,
> - in fact, it isn't a valid URL at all. A relative URL is subject to a
> - resolving process, which transforms it into an absolute
> + in fact, it isn't a valid URL at all since the <code>file</code>
> + scheme does not (officially) support relative paths. A relative URL
> + is subject to a resolving process, which transforms it into an absolute
> URL.
> </p>
> <!--p>
> @@ -283,31 +292,8 @@
> <question>I get an "[ERROR]: null", or a NullPointerException.</question>
> <answer>
> <p>
> - This is often caused by an invalid FO document. Currently only very
> - common errors are intercepted and produce a comprehensible error
> - message. If you forgot container elements like <code>fo:page-sequence</code> or
> - <code>fo:flow</code> and put blocks and inline elements directly as children of
> - <code>fo:root</code> or <code>fo:page-sequence</code>, you'll only get a
> - NullPointerException. Check whether your FO file has a proper
> - structure. In some cases there are mandatory properties, like the
> - master-reference in <code>fo:conditional-page-master-reference</code>, check also
> - whether you got them right.
> - </p>
> - <p>
> - You may find it helpful to use the <link href="#fo-validate">validation tools</link> to validate your
> - FO document. This will catch most problems, but should not be
> - relied upon to catch all.
> - </p>
> - <p>
> - If you use XSLT, problems in your style sheet and in your
> - source XML also can produce a NullPointerException. <link
> - href="1.0/running.html#check-input">Run the transformation
> - separately</link> to check for this, usually you'll get a
> - detailed error message from the XSLT processor.
> - </p>
> - <p>
> - If you turn on debugging with the "<code>-d</code>" option you may be able to
> - see more detailed information.
> + This is a very likely a bug in FOP. If you encounter this error, please
> + <link href="bugs.html#issues_new">Open a New Bug</link>.
> </p>
> </answer>
> </faq>
> @@ -322,9 +308,9 @@
> <answer>
> <p>
> The most likely reason is a known problem with the Java run time
> - environment which is triggered by rendering SVGs. Suns JDK 1.4 does
> - not have this problem. See also <link href="#svghangs">FOP does not
> - exit if a SVG is included</link>.
> + environment which is triggered by rendering SVGs. Sun's JDK 1.4 and
> + later do not have this problem. See also <link href="#svghangs">FOP
> + does not exit if a SVG is included</link>.
> </p>
> <p>
> Another possibility is that FOP went into a non terminating
> @@ -340,6 +326,10 @@
> the FOP output regularly to empty the pipe buffer. It is best to avoid
> exec'ing FOP, use the library interface instead.
> </p>
> + <p>
> + If you can reproduce this problem given a specific input and configuration,
> + then please <link href="bugs.html#issues_new">Open a New Bug</link>.
> + </p>
> </answer>
> </faq>
> <faq id="boxoverflow">
> @@ -441,8 +431,7 @@ public class DefaultErrorListener implem
> To avoid the warning you can simply delete the
> old Font Cache file, which lives in ${base}\conf\font.cache (see <link
> href="1.0/configuration.html#general-elements">font-base
> - configuration</link>). Or you can disable Font Caching altogether using
> - the option "use-cache."
> + configuration</link>).
> </p>
> </answer>
> </faq>
> @@ -524,7 +513,7 @@ Check the following:</p>
> HTTP. Possible issues include security settings on the
> server, server configuration, and missing cookies or other
> authorization information. Any easy way to check this is to
> - cut&paste the source URL from the fo:external-graphic
> + cut and paste the source URL from the <code>fo:external-graphic</code>
> into the Location field of a browser <strong>on the machine
> where the FOP process will be running</strong>.</li>
> </ul>
> @@ -627,7 +616,7 @@ Check the following:</p>
> explicit wrapping+clipping,
> </li>
> <li>
> - insert zero width spaces (U+200B or &#x200B;) to allow FOP to
> + insert zero width spaces (&#x200B;) to allow FOP to
> wrap.
> </li>
> </ul>
> @@ -1281,7 +1270,7 @@ Can I control this?</question>
> <question>Where can I learn how the FOP docs and web site are built?</question>
> <answer>
> <p>
> - See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
> + See FOP <link href="dev/doc.html">Doc Management</link>.
> </p>
> </answer>
> </faq>
> @@ -1307,7 +1296,7 @@ Can I control this?</question>
> If you have a runtime exception or other runtime problem:
> <ul>
> <li>
> - double-check the <link href="#part-running">Runtime FAQs</link>.
> + Double check the <link href="#part-running">Runtime FAQs</link>.
> </li>
> <li>
> ClassNotFoundException, NoSuchMethodException and
> @@ -1325,7 +1314,7 @@ Can I control this?</question>
> </li>
> <li>
> In the case where something works properly with another formatter,
> - (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
> + (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
> check the <!--link href="relnotes.html"-->Release Notes<!--/link-->, the
> <link href="compliance.html">FOP Standards Compliance</link> document,
> and the remaining FAQ in this document. If not found there, look at the
> @@ -1348,13 +1337,8 @@ Can I control this?</question>
> Problems specific to a certain XSLT processor, like Xalan, Saxon or
> MSXML, should be handled by processor specific lists. This includes
> problems with deployment, processor specific extensions, suspected
> - bugs and processor specific APIs. Note that JDK 1.4 comes with an
> - XML parser and an XSLT processor which are older versions of
> - Xerces and Xalan, respectively, and both have a number of annoying
> - bugs. See http://java.sun.com/developer/EJTechTips/2003/tt0311.html
> - and http://java.sun.com/j2se/1.4.2/docs/guide/standards/ (or similar
> - pages for later Java releases) for some hints on how to use more
> - recent versions or other packages instead.
> + bugs and processor specific APIs. Note that JDK 1.4 and later come with an
> + XML parser and an XSLT processor which may be the source of the problem.
> </li>
> <li>
> Problems with servlet containers should be asked on the vendor
>
> Modified: xmlgraphics/fop/trunk/status.xml
> URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/status.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> ==============================================================================
> --- xmlgraphics/fop/trunk/status.xml (original)
> +++ xmlgraphics/fop/trunk/status.xml Fri May 25 19:10:28 2012
> @@ -63,6 +63,9 @@
> documents. Example: the fix of marks layering will be such a case when it's done.
> -->
> <release version="FOP Trunk" date="TBD">
> + <action context="Docs" dev="GA" type="update">
> + Update FAQ and New Bug documentation.
> + </action>
> <action context="Code" dev="VH" type="add">
> Added support for the role property on fo:page-sequence, fo:flow and fo:static-content. This
> allows to change the mapping of those FOs to PDF structure types when enabling
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
> For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
>
Re: svn commit: r1342781 - in /xmlgraphics/fop/trunk: src/documentation/content/xdocs/bugs.xml
src/documentation/content/xdocs/faq.xml status.xml
Posted by Vincent Hennebert <vh...@gmail.com>.
Great, thanks. I made the changes to the CMS and ported the other
changes in the same time.
There seems to be a bug in the Markdown converter, that doesn’t properly
handle nested lists. It’s strange because the previewer in the web
editor displays them properly. I cannot imagine that 2 different
converters are used for the preview and the actual HTML generation.
I’ll try and investigate what’s going on.
Vincent
On 20/11/12 14:40, Glenn Adams wrote:
> ok, i can accept
>
> On Tue, Nov 20, 2012 at 3:52 AM, Vincent Hennebert <vh...@gmail.com>wrote:
>
>> Ok, so what about the attached diff?
>>
>> Thanks,
>> Vincent
>>
>> On 10/10/12 00:50, Glenn Adams wrote:
>>> As long as you don't remove the MUST/SHOULD language about providing an
>>> input FO file, then I don't mind you taking another editing pass. If you
>>> want to change the MUST/SHOULD language, then please propose a
>> replacement
>>> for discussion here.
>>>
>>> On Tue, Oct 9, 2012 at 11:10 PM, Vincent Hennebert <vhennebert@gmail.com
>>> wrote:
>>>
>>>> (Going through old unread commit messages...)
>>>>
>>>> I’d like to soften a bit the rather martial tone introduced in those
>>>> changes. If I were a new user looking into submitting a bug and reading
>>>> this page, I think I would refrain from doing so for fear of the police
>>>> forces breaking into my home in the middle of the night and pointing
>>>> a gun to my head because I dared not to follow the process... :-)
>>>>
>>>> Any objections?
>>>>
>>>> Thanks,
>>>> Vincent
>>>>
>>>>
>>>> On 25/05/12 20:10, gadams wrote:
>>>>> Author: gadams
>>>>> Date: Fri May 25 19:10:28 2012
>>>>> New Revision: 1342781
>>>>>
>>>>> URL: http://svn.apache.org/viewvc?rev=1342781&view=rev
>>>>> Log:
>>>>> Update FAQ and New Bug documentation.
>>>>>
>>>>> Modified:
>>>>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>>>>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>>>>> xmlgraphics/fop/trunk/status.xml
>>>>>
>>>>> Modified:
>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>>>>> URL:
>>>>
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>>>
>>>>
>> ==============================================================================
>>>>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>>>> (original)
>>>>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml Fri
>>>> May 25 19:10:28 2012
>>>>> @@ -45,21 +45,66 @@ an email as changes are made to the issu
>>>>> </section>
>>>>> <section id="issues_new">
>>>>> <title>Unreported Issues (Reporting New Issues)</title>
>>>>> - <p>User reports of bugs and requests for enhancements are
>>>> extremely
>>>>> -important parts of FOP development, and we appreciate the time you
>> take
>>>> to help
>>>>> -us track these issues down.</p>
>>>>> + <p>
>>>>> + User reports of bugs and requests for enhancements are
>> extremely
>>>>> + important parts of FOP development, and we appreciate the time
>>>> you take to help
>>>>> + us track these issues down.
>>>>> + </p>
>>>>> <ul>
>>>>> - <li>To help us ensure that the bug database is as useful as it
>>>> should be, please
>>>>> -use the <link href="gethelp.html">Getting Help</link> checklist to
>>>> determine whether a bug report should be entered.</li>
>>>>> - <li>Review the <link href="
>>>> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
>>>> Bug Writing Guidelines</link> before submitting your report.</li>
>>>>> - <li>Enter a new issue report at <link href="
>>>> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP
>>>> issue database (Bugzilla)</link>.
>>>>> -You will be asked to login to an existing Bugzilla account or to
>> create
>>>> a new
>>>>> -one.
>>>>> -When entering the bug report, please make your description complete
>> and
>>>> concise.
>>>>> -If appropriate, attach a minimal fo file to your report which
>>>> demonstrates the
>>>>> -problem.</li>
>>>>> - <li>After submission, a copy of your bug report will be
>>>> automatically
>>>>> -sent to the FOP developer discussion list.</li>
>>>>> + <li>
>>>>> + To help us ensure that the bug database is as useful as it
>>>> should be, please
>>>>> + use the <link href="gethelp.html">Getting Help</link>
>>>> checklist to determine whether a bug report should be entered.
>>>>> + </li>
>>>>> + <li>
>>>>> + Review the <link href="
>>>> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
>> Bug
>>>>> + Writing Guidelines</link> before submitting your report.
>>>>> + </li>
>>>>> + <li>
>>>>> + Enter a new issue report at <link href="
>>>> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
>>>>> + FOP issue database (Bugzilla)</link>. You will be asked to
>>>> login to an existing Bugzilla account or to
>>>>> + create a new one. When entering the bug report, please make
>>>> your description complete and concise.
>>>>> + If the issue involves a specific input or output file, then
>>>> you <strong>MUST</strong> include the
>>>>> + following information in the bug report (preferably as one
>> or
>>>> more attachments):
>>>>> + <ul>
>>>>> + <li>
>>>>> + an input XSL-FO file (an input XML plus XSLT file is not
>>>> acceptable, unless and only if the
>>>>> + issue being reported is related to the built-in XSLT
>>>> transform processing convenience function provided
>>>>> + by FOP); this input <strong>SHOULD</strong> be
>>>> <em>maximally minimal</em>, which means that it should
>>>>> + contain nothing more than the minimum needed to
>>>> demonstrate the problem; if you do not take the effort
>>>>> + to provide a maximally minimal input FO file, then you
>>>> will be subsequently asked to do so before the
>>>>> + bug is processed;
>>>>> + </li>
>>>>> + <li>
>>>>> + a resulting output file, preferably in PDF format; if
>> the
>>>> issue being reported involves a different output
>>>>> + format, then provide both a PDF output file and the
>>>> output file for the output format for which the report
>>>>> + applies;
>>>>> + </li>
>>>>> + <li>
>>>>> + a copy of the FOP configuration file you used (e.g.,
>>>> fop.xconf);
>>>>> + </li>
>>>>> + <li>
>>>>> + if FOP was invoked using the command line (or an
>>>> equivalent), then a dump of both the input
>>>>> + command line and any console output (stderr or stdout)
>>>> produced; if the report involves an
>>>>> + exception, then this <strong>MUST</strong> include the
>>>> full stack back trace;
>>>>> + </li>
>>>>> + <li>
>>>>> + information describing the version of FOP you are using
>>>> and the platform (and OS) on which
>>>>> + you are invoking FOP;
>>>>> + </li>
>>>>> + <li>
>>>>> + if the report applies to the use of a specific font
>> other
>>>> than one of the built-in, base 14
>>>>> + fonts, then information that describes where to obtain
>>>> the font.
>>>>> + </li>
>>>>> + </ul>
>>>>> + </li>
>>>>> + <li>
>>>>> + After submission, a copy of your bug report will be
>>>> automatically
>>>>> + sent to the FOP developer discussion list. If additional
>>>> information is needed to
>>>>> + process the bug, then the bug will be set to the
>>>> <code>NEEDSINFO</code> state, and
>>>>> + you will be asked to provide the additional information. You
>>>> can avoid this extra
>>>>> + step by being diligent about providing <strong>all</strong>
>>>> of the information
>>>>> + indicated above.
>>>>> + </li>
>>>>> </ul>
>>>>> </section>
>>>>> </body>
>>>>>
>>>>> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>>>>> URL:
>>>>
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>>>
>>>>
>> ==============================================================================
>>>>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>>>> (original)
>>>>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml Fri
>>>> May 25 19:10:28 2012
>>>>> @@ -25,7 +25,7 @@
>>>>> <question>What is Apacheâ„¢ FOP?</question>
>>>>> <answer>
>>>>> <p>
>>>>> - FOP is a print formatter for <link href="#XSLFO">XSL
>> formatting
>>>>> + FOP is a print formatter for <link href="#xslfo">XSL
>> formatting
>>>>> objects</link>.
>>>>> </p>
>>>>> <p>
>>>>> @@ -65,16 +65,23 @@
>>>>> <question>How does FOP interact with other Apache
>>>> Projects?</question>
>>>>> <answer>
>>>>> <p>
>>>>> - FOP is distributed with <link
>>>>> - href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF
>>>> serializer
>>>>> - for XSL (FO) documents.
>>>>> + <link href="http://xmlgraphics.apache.org/commons">XML
>>>> Graphics Commons</link> is used with
>>>>> + FOP to provide graphics functions that are common to a
>> number
>>>> of Apache projects.
>>>>> </p>
>>>>> <p>
>>>>> - <link href="http://xmlgraphics.apache.org/batik
>> ">Batik</link>
>>>> can be used with
>>>>> + <link href="http://xmlgraphics.apache.org/batik
>> ">Batik</link>
>>>> is used with
>>>>> FOP to <link
>>>>> href="
>> http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode
>>>> an SVG
>>>>> image</link> into a PDF document.
>>>>> </p>
>>>>> + <p>FOP also makes use of the following Apache projects:</p>
>>>>> + <ul>
>>>>> + <li><link href="http://excalibur.apache.org/framework/
>> ">Avalon
>>>> Framework</link></li>
>>>>> + <li><link href="http://jakarta.apache.org/commons/io/
>> ">Jakarta
>>>> Commons IO</link></li>
>>>>> + <li><link href="http://jakarta.apache.org/commons/logging/
>> ">Jakarta
>>>> Commons Logging</link></li>
>>>>> + <li><link href="http://xalan.apache.org/
>> ">Xalan-J</link></li>
>>>>> + <li><link href="
>>>> http://xml.apache.org/commons/components/external/">XML Commons
>>>> Externals</link></li>
>>>>> + </ul>
>>>>> </answer>
>>>>> </faq>
>>>>> <faq id="xsl-def">
>>>>> @@ -83,7 +90,7 @@
>>>>> <p>
>>>>> XSL is a W3C standard concerned with publishing XML
>>>> documents. It
>>>>> consists of two parts: <link href="#XSLT">XSLT</link> and
>>>> <link
>>>>> - href="#XSLFO">XSL-FO</link>. The acronym expands to
>>>>> + href="#xslfo">XSL-FO</link>. The acronym expands to
>>>>> e<strong>X</strong>tensible <strong>S</strong>tylesheet
>>>>> <strong>L</strong>anguage.
>>>>> </p>
>>>>> @@ -93,7 +100,9 @@
>>>>> <question>What is XSL-FO?</question>
>>>>> <answer>
>>>>> <p>
>>>>> - XSLFO (aka XSL-FO) is an XML vocabulary that is used to
>>>> specify a pagination and
>>>>> + XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C
>>>> Recommendation
>>>>> + <link href="http://www.w3.org/TR/xsl/">Extensible
>> Stylesheet
>>>> Language (XSL)
>>>>> + Version 1.1</link>, that is used to specify a pagination and
>>>>> other styling for page layout output. The acronym
>>>> “FO”
>>>>> stands for
>>>>> <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO
>>>> can be
>>>>> @@ -226,8 +235,7 @@
>>>>> <answer>
>>>>> <p>
>>>>> This is usually caused by an older version of one of the FOP
>>>> jars or
>>>>> - old XML tools in the classpath. Check in particular for
>>>> parser.jar,
>>>>> - jaxp.jar, xml4j.jar or lotusxsl.jar.
>>>>> + old XML tools in the classpath.
>>>>> </p>
>>>>> <p>
>>>>> Incompatible versions of Batik may also cause this problem.
>>>> Use the
>>>>> @@ -269,8 +277,9 @@
>>>>> the <code>file:</code> prefix, for example
>>>> <code>file.ext</code>,
>>>>> <code>path/file.ext</code> or <code>../file.ext</code>. The
>>>> string
>>>>> <code>file:path/file.ext</code> is <em>not</em> a relative
>>>> URL,
>>>>> - in fact, it isn't a valid URL at all. A relative URL is
>>>> subject to a
>>>>> - resolving process, which transforms it into an absolute
>>>>> + in fact, it isn't a valid URL at all since the
>>>> <code>file</code>
>>>>> + scheme does not (officially) support relative paths. A
>>>> relative URL
>>>>> + is subject to a resolving process, which transforms it into
>>>> an absolute
>>>>> URL.
>>>>> </p>
>>>>> <!--p>
>>>>> @@ -283,31 +292,8 @@
>>>>> <question>I get an "[ERROR]: null", or a
>>>> NullPointerException.</question>
>>>>> <answer>
>>>>> <p>
>>>>> - This is often caused by an invalid FO document. Currently
>>>> only very
>>>>> - common errors are intercepted and produce a comprehensible
>>>> error
>>>>> - message. If you forgot container elements like
>>>> <code>fo:page-sequence</code> or
>>>>> - <code>fo:flow</code> and put blocks and inline elements
>>>> directly as children of
>>>>> - <code>fo:root</code> or <code>fo:page-sequence</code>,
>> you'll
>>>> only get a
>>>>> - NullPointerException. Check whether your FO file has a
>> proper
>>>>> - structure. In some cases there are mandatory properties,
>> like
>>>> the
>>>>> - master-reference in
>>>> <code>fo:conditional-page-master-reference</code>, check also
>>>>> - whether you got them right.
>>>>> - </p>
>>>>> - <p>
>>>>> - You may find it helpful to use the <link
>>>> href="#fo-validate">validation tools</link> to validate your
>>>>> - FO document. This will catch most problems, but should not
>> be
>>>>> - relied upon to catch all.
>>>>> - </p>
>>>>> - <p>
>>>>> - If you use XSLT, problems in your style sheet and in your
>>>>> - source XML also can produce a NullPointerException. <link
>>>>> - href="1.0/running.html#check-input">Run the transformation
>>>>> - separately</link> to check for this, usually you'll get a
>>>>> - detailed error message from the XSLT processor.
>>>>> - </p>
>>>>> - <p>
>>>>> - If you turn on debugging with the "<code>-d</code>" option
>>>> you may be able to
>>>>> - see more detailed information.
>>>>> + This is a very likely a bug in FOP. If you encounter this
>>>> error, please
>>>>> + <link href="bugs.html#issues_new">Open a New Bug</link>.
>>>>> </p>
>>>>> </answer>
>>>>> </faq>
>>>>> @@ -322,9 +308,9 @@
>>>>> <answer>
>>>>> <p>
>>>>> The most likely reason is a known problem with the Java run
>>>> time
>>>>> - environment which is triggered by rendering SVGs. Suns JDK
>>>> 1.4 does
>>>>> - not have this problem. See also <link href="#svghangs">FOP
>>>> does not
>>>>> - exit if a SVG is included</link>.
>>>>> + environment which is triggered by rendering SVGs. Sun's JDK
>>>> 1.4 and
>>>>> + later do not have this problem. See also <link
>>>> href="#svghangs">FOP
>>>>> + does not exit if a SVG is included</link>.
>>>>> </p>
>>>>> <p>
>>>>> Another possibility is that FOP went into a non terminating
>>>>> @@ -340,6 +326,10 @@
>>>>> the FOP output regularly to empty the pipe buffer. It is
>> best
>>>> to avoid
>>>>> exec'ing FOP, use the library interface instead.
>>>>> </p>
>>>>> + <p>
>>>>> + If you can reproduce this problem given a specific input and
>>>> configuration,
>>>>> + then please <link href="bugs.html#issues_new">Open a New
>>>> Bug</link>.
>>>>> + </p>
>>>>> </answer>
>>>>> </faq>
>>>>> <faq id="boxoverflow">
>>>>> @@ -441,8 +431,7 @@ public class DefaultErrorListener implem
>>>>> To avoid the warning you can simply delete the
>>>>> old Font Cache file, which lives in ${base}\conf\font.cache
>>>> (see <link
>>>>> href="1.0/configuration.html#general-elements">font-base
>>>>> - configuration</link>). Or you can disable Font Caching
>>>> altogether using
>>>>> - the option "use-cache."
>>>>> + configuration</link>).
>>>>> </p>
>>>>> </answer>
>>>>> </faq>
>>>>> @@ -524,7 +513,7 @@ Check the following:</p>
>>>>> HTTP. Possible issues include security settings on the
>>>>> server, server configuration, and missing cookies or other
>>>>> authorization information. Any easy way to check this is to
>>>>> - cut&paste the source URL from the fo:external-graphic
>>>>> + cut and paste the source URL from the
>>>> <code>fo:external-graphic</code>
>>>>> into the Location field of a browser <strong>on the machine
>>>>> where the FOP process will be running</strong>.</li>
>>>>> </ul>
>>>>> @@ -627,7 +616,7 @@ Check the following:</p>
>>>>> explicit wrapping+clipping,
>>>>> </li>
>>>>> <li>
>>>>> - insert zero width spaces (U+200B or &#x200B;) to allow
>>>> FOP to
>>>>> + insert zero width spaces (&#x200B;) to allow FOP to
>>>>> wrap.
>>>>> </li>
>>>>> </ul>
>>>>> @@ -1281,7 +1270,7 @@ Can I control this?</question>
>>>>> <question>Where can I learn how the FOP docs and web site are
>>>> built?</question>
>>>>> <answer>
>>>>> <p>
>>>>> - See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
>>>>> + See FOP <link href="dev/doc.html">Doc Management</link>.
>>>>> </p>
>>>>> </answer>
>>>>> </faq>
>>>>> @@ -1307,7 +1296,7 @@ Can I control this?</question>
>>>>> If you have a runtime exception or other runtime problem:
>>>>> <ul>
>>>>> <li>
>>>>> - double-check the <link href="#part-running">Runtime
>>>> FAQs</link>.
>>>>> + Double check the <link href="#part-running">Runtime
>>>> FAQs</link>.
>>>>> </li>
>>>>> <li>
>>>>> ClassNotFoundException, NoSuchMethodException and
>>>>> @@ -1325,7 +1314,7 @@ Can I control this?</question>
>>>>> </li>
>>>>> <li>
>>>>> In the case where something works properly with another
>>>> formatter,
>>>>> - (AntennaHouse, PassiveTex, etc.) but doesn't work with
>> FOP,
>>>> please
>>>>> + (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work
>>>> with FOP, please
>>>>> check the <!--link href="relnotes.html"-->Release
>>>> Notes<!--/link-->, the
>>>>> <link href="compliance.html">FOP Standards
>>>> Compliance</link> document,
>>>>> and the remaining FAQ in this document. If not found
>> there,
>>>> look at the
>>>>> @@ -1348,13 +1337,8 @@ Can I control this?</question>
>>>>> Problems specific to a certain XSLT processor, like Xalan,
>>>> Saxon or
>>>>> MSXML, should be handled by processor specific lists. This
>>>> includes
>>>>> problems with deployment, processor specific extensions,
>>>> suspected
>>>>> - bugs and processor specific APIs. Note that JDK 1.4 comes
>>>> with an
>>>>> - XML parser and an XSLT processor which are older versions
>> of
>>>>> - Xerces and Xalan, respectively, and both have a number of
>>>> annoying
>>>>> - bugs. See
>>>> http://java.sun.com/developer/EJTechTips/2003/tt0311.html
>>>>> - and
>> http://java.sun.com/j2se/1.4.2/docs/guide/standards/(or similar
>>>>> - pages for later Java releases) for some hints on how to
>> use
>>>> more
>>>>> - recent versions or other packages instead.
>>>>> + bugs and processor specific APIs. Note that JDK 1.4 and
>>>> later come with an
>>>>> + XML parser and an XSLT processor which may be the source
>> of
>>>> the problem.
>>>>> </li>
>>>>> <li>
>>>>> Problems with servlet containers should be asked on the
>>>> vendor
>>>>>
>>>>> Modified: xmlgraphics/fop/trunk/status.xml
>>>>> URL:
>>>>
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/status.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>>>
>>>>
>> ==============================================================================
>>>>> --- xmlgraphics/fop/trunk/status.xml (original)
>>>>> +++ xmlgraphics/fop/trunk/status.xml Fri May 25 19:10:28 2012
>>>>> @@ -63,6 +63,9 @@
>>>>> documents. Example: the fix of marks layering will be such a
>> case
>>>> when it's done.
>>>>> -->
>>>>> <release version="FOP Trunk" date="TBD">
>>>>> + <action context="Docs" dev="GA" type="update">
>>>>> + Update FAQ and New Bug documentation.
>>>>> + </action>
>>>>> <action context="Code" dev="VH" type="add">
>>>>> Added support for the role property on fo:page-sequence,
>>>> fo:flow and fo:static-content. This
>>>>> allows to change the mapping of those FOs to PDF structure
>>>> types when enabling
>>>>>
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
>>>>> For additional commands, e-mail:
>> fop-commits-help@xmlgraphics.apache.org
>>>>>
>>>>
>>>
>>
>
Re: svn commit: r1342781 - in /xmlgraphics/fop/trunk:
src/documentation/content/xdocs/bugs.xml src/documentation/content/xdocs/faq.xml
status.xml
Posted by Glenn Adams <gl...@skynav.com>.
ok, i can accept
On Tue, Nov 20, 2012 at 3:52 AM, Vincent Hennebert <vh...@gmail.com>wrote:
> Ok, so what about the attached diff?
>
> Thanks,
> Vincent
>
> On 10/10/12 00:50, Glenn Adams wrote:
> > As long as you don't remove the MUST/SHOULD language about providing an
> > input FO file, then I don't mind you taking another editing pass. If you
> > want to change the MUST/SHOULD language, then please propose a
> replacement
> > for discussion here.
> >
> > On Tue, Oct 9, 2012 at 11:10 PM, Vincent Hennebert <vhennebert@gmail.com
> >wrote:
> >
> >> (Going through old unread commit messages...)
> >>
> >> I’d like to soften a bit the rather martial tone introduced in those
> >> changes. If I were a new user looking into submitting a bug and reading
> >> this page, I think I would refrain from doing so for fear of the police
> >> forces breaking into my home in the middle of the night and pointing
> >> a gun to my head because I dared not to follow the process... :-)
> >>
> >> Any objections?
> >>
> >> Thanks,
> >> Vincent
> >>
> >>
> >> On 25/05/12 20:10, gadams wrote:
> >>> Author: gadams
> >>> Date: Fri May 25 19:10:28 2012
> >>> New Revision: 1342781
> >>>
> >>> URL: http://svn.apache.org/viewvc?rev=1342781&view=rev
> >>> Log:
> >>> Update FAQ and New Bug documentation.
> >>>
> >>> Modified:
> >>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> >>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> >>> xmlgraphics/fop/trunk/status.xml
> >>>
> >>> Modified:
> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> >>> URL:
> >>
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >>>
> >>
> ==============================================================================
> >>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> >> (original)
> >>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml Fri
> >> May 25 19:10:28 2012
> >>> @@ -45,21 +45,66 @@ an email as changes are made to the issu
> >>> </section>
> >>> <section id="issues_new">
> >>> <title>Unreported Issues (Reporting New Issues)</title>
> >>> - <p>User reports of bugs and requests for enhancements are
> >> extremely
> >>> -important parts of FOP development, and we appreciate the time you
> take
> >> to help
> >>> -us track these issues down.</p>
> >>> + <p>
> >>> + User reports of bugs and requests for enhancements are
> extremely
> >>> + important parts of FOP development, and we appreciate the time
> >> you take to help
> >>> + us track these issues down.
> >>> + </p>
> >>> <ul>
> >>> - <li>To help us ensure that the bug database is as useful as it
> >> should be, please
> >>> -use the <link href="gethelp.html">Getting Help</link> checklist to
> >> determine whether a bug report should be entered.</li>
> >>> - <li>Review the <link href="
> >> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
> >> Bug Writing Guidelines</link> before submitting your report.</li>
> >>> - <li>Enter a new issue report at <link href="
> >> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP
> >> issue database (Bugzilla)</link>.
> >>> -You will be asked to login to an existing Bugzilla account or to
> create
> >> a new
> >>> -one.
> >>> -When entering the bug report, please make your description complete
> and
> >> concise.
> >>> -If appropriate, attach a minimal fo file to your report which
> >> demonstrates the
> >>> -problem.</li>
> >>> - <li>After submission, a copy of your bug report will be
> >> automatically
> >>> -sent to the FOP developer discussion list.</li>
> >>> + <li>
> >>> + To help us ensure that the bug database is as useful as it
> >> should be, please
> >>> + use the <link href="gethelp.html">Getting Help</link>
> >> checklist to determine whether a bug report should be entered.
> >>> + </li>
> >>> + <li>
> >>> + Review the <link href="
> >> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
> Bug
> >>> + Writing Guidelines</link> before submitting your report.
> >>> + </li>
> >>> + <li>
> >>> + Enter a new issue report at <link href="
> >> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
> >>> + FOP issue database (Bugzilla)</link>. You will be asked to
> >> login to an existing Bugzilla account or to
> >>> + create a new one. When entering the bug report, please make
> >> your description complete and concise.
> >>> + If the issue involves a specific input or output file, then
> >> you <strong>MUST</strong> include the
> >>> + following information in the bug report (preferably as one
> or
> >> more attachments):
> >>> + <ul>
> >>> + <li>
> >>> + an input XSL-FO file (an input XML plus XSLT file is not
> >> acceptable, unless and only if the
> >>> + issue being reported is related to the built-in XSLT
> >> transform processing convenience function provided
> >>> + by FOP); this input <strong>SHOULD</strong> be
> >> <em>maximally minimal</em>, which means that it should
> >>> + contain nothing more than the minimum needed to
> >> demonstrate the problem; if you do not take the effort
> >>> + to provide a maximally minimal input FO file, then you
> >> will be subsequently asked to do so before the
> >>> + bug is processed;
> >>> + </li>
> >>> + <li>
> >>> + a resulting output file, preferably in PDF format; if
> the
> >> issue being reported involves a different output
> >>> + format, then provide both a PDF output file and the
> >> output file for the output format for which the report
> >>> + applies;
> >>> + </li>
> >>> + <li>
> >>> + a copy of the FOP configuration file you used (e.g.,
> >> fop.xconf);
> >>> + </li>
> >>> + <li>
> >>> + if FOP was invoked using the command line (or an
> >> equivalent), then a dump of both the input
> >>> + command line and any console output (stderr or stdout)
> >> produced; if the report involves an
> >>> + exception, then this <strong>MUST</strong> include the
> >> full stack back trace;
> >>> + </li>
> >>> + <li>
> >>> + information describing the version of FOP you are using
> >> and the platform (and OS) on which
> >>> + you are invoking FOP;
> >>> + </li>
> >>> + <li>
> >>> + if the report applies to the use of a specific font
> other
> >> than one of the built-in, base 14
> >>> + fonts, then information that describes where to obtain
> >> the font.
> >>> + </li>
> >>> + </ul>
> >>> + </li>
> >>> + <li>
> >>> + After submission, a copy of your bug report will be
> >> automatically
> >>> + sent to the FOP developer discussion list. If additional
> >> information is needed to
> >>> + process the bug, then the bug will be set to the
> >> <code>NEEDSINFO</code> state, and
> >>> + you will be asked to provide the additional information. You
> >> can avoid this extra
> >>> + step by being diligent about providing <strong>all</strong>
> >> of the information
> >>> + indicated above.
> >>> + </li>
> >>> </ul>
> >>> </section>
> >>> </body>
> >>>
> >>> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> >>> URL:
> >>
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >>>
> >>
> ==============================================================================
> >>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> >> (original)
> >>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml Fri
> >> May 25 19:10:28 2012
> >>> @@ -25,7 +25,7 @@
> >>> <question>What is Apacheâ„¢ FOP?</question>
> >>> <answer>
> >>> <p>
> >>> - FOP is a print formatter for <link href="#XSLFO">XSL
> formatting
> >>> + FOP is a print formatter for <link href="#xslfo">XSL
> formatting
> >>> objects</link>.
> >>> </p>
> >>> <p>
> >>> @@ -65,16 +65,23 @@
> >>> <question>How does FOP interact with other Apache
> >> Projects?</question>
> >>> <answer>
> >>> <p>
> >>> - FOP is distributed with <link
> >>> - href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF
> >> serializer
> >>> - for XSL (FO) documents.
> >>> + <link href="http://xmlgraphics.apache.org/commons">XML
> >> Graphics Commons</link> is used with
> >>> + FOP to provide graphics functions that are common to a
> number
> >> of Apache projects.
> >>> </p>
> >>> <p>
> >>> - <link href="http://xmlgraphics.apache.org/batik
> ">Batik</link>
> >> can be used with
> >>> + <link href="http://xmlgraphics.apache.org/batik
> ">Batik</link>
> >> is used with
> >>> FOP to <link
> >>> href="
> http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode
> >> an SVG
> >>> image</link> into a PDF document.
> >>> </p>
> >>> + <p>FOP also makes use of the following Apache projects:</p>
> >>> + <ul>
> >>> + <li><link href="http://excalibur.apache.org/framework/
> ">Avalon
> >> Framework</link></li>
> >>> + <li><link href="http://jakarta.apache.org/commons/io/
> ">Jakarta
> >> Commons IO</link></li>
> >>> + <li><link href="http://jakarta.apache.org/commons/logging/
> ">Jakarta
> >> Commons Logging</link></li>
> >>> + <li><link href="http://xalan.apache.org/
> ">Xalan-J</link></li>
> >>> + <li><link href="
> >> http://xml.apache.org/commons/components/external/">XML Commons
> >> Externals</link></li>
> >>> + </ul>
> >>> </answer>
> >>> </faq>
> >>> <faq id="xsl-def">
> >>> @@ -83,7 +90,7 @@
> >>> <p>
> >>> XSL is a W3C standard concerned with publishing XML
> >> documents. It
> >>> consists of two parts: <link href="#XSLT">XSLT</link> and
> >> <link
> >>> - href="#XSLFO">XSL-FO</link>. The acronym expands to
> >>> + href="#xslfo">XSL-FO</link>. The acronym expands to
> >>> e<strong>X</strong>tensible <strong>S</strong>tylesheet
> >>> <strong>L</strong>anguage.
> >>> </p>
> >>> @@ -93,7 +100,9 @@
> >>> <question>What is XSL-FO?</question>
> >>> <answer>
> >>> <p>
> >>> - XSLFO (aka XSL-FO) is an XML vocabulary that is used to
> >> specify a pagination and
> >>> + XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C
> >> Recommendation
> >>> + <link href="http://www.w3.org/TR/xsl/">Extensible
> Stylesheet
> >> Language (XSL)
> >>> + Version 1.1</link>, that is used to specify a pagination and
> >>> other styling for page layout output. The acronym
> >> “FO”
> >>> stands for
> >>> <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO
> >> can be
> >>> @@ -226,8 +235,7 @@
> >>> <answer>
> >>> <p>
> >>> This is usually caused by an older version of one of the FOP
> >> jars or
> >>> - old XML tools in the classpath. Check in particular for
> >> parser.jar,
> >>> - jaxp.jar, xml4j.jar or lotusxsl.jar.
> >>> + old XML tools in the classpath.
> >>> </p>
> >>> <p>
> >>> Incompatible versions of Batik may also cause this problem.
> >> Use the
> >>> @@ -269,8 +277,9 @@
> >>> the <code>file:</code> prefix, for example
> >> <code>file.ext</code>,
> >>> <code>path/file.ext</code> or <code>../file.ext</code>. The
> >> string
> >>> <code>file:path/file.ext</code> is <em>not</em> a relative
> >> URL,
> >>> - in fact, it isn't a valid URL at all. A relative URL is
> >> subject to a
> >>> - resolving process, which transforms it into an absolute
> >>> + in fact, it isn't a valid URL at all since the
> >> <code>file</code>
> >>> + scheme does not (officially) support relative paths. A
> >> relative URL
> >>> + is subject to a resolving process, which transforms it into
> >> an absolute
> >>> URL.
> >>> </p>
> >>> <!--p>
> >>> @@ -283,31 +292,8 @@
> >>> <question>I get an "[ERROR]: null", or a
> >> NullPointerException.</question>
> >>> <answer>
> >>> <p>
> >>> - This is often caused by an invalid FO document. Currently
> >> only very
> >>> - common errors are intercepted and produce a comprehensible
> >> error
> >>> - message. If you forgot container elements like
> >> <code>fo:page-sequence</code> or
> >>> - <code>fo:flow</code> and put blocks and inline elements
> >> directly as children of
> >>> - <code>fo:root</code> or <code>fo:page-sequence</code>,
> you'll
> >> only get a
> >>> - NullPointerException. Check whether your FO file has a
> proper
> >>> - structure. In some cases there are mandatory properties,
> like
> >> the
> >>> - master-reference in
> >> <code>fo:conditional-page-master-reference</code>, check also
> >>> - whether you got them right.
> >>> - </p>
> >>> - <p>
> >>> - You may find it helpful to use the <link
> >> href="#fo-validate">validation tools</link> to validate your
> >>> - FO document. This will catch most problems, but should not
> be
> >>> - relied upon to catch all.
> >>> - </p>
> >>> - <p>
> >>> - If you use XSLT, problems in your style sheet and in your
> >>> - source XML also can produce a NullPointerException. <link
> >>> - href="1.0/running.html#check-input">Run the transformation
> >>> - separately</link> to check for this, usually you'll get a
> >>> - detailed error message from the XSLT processor.
> >>> - </p>
> >>> - <p>
> >>> - If you turn on debugging with the "<code>-d</code>" option
> >> you may be able to
> >>> - see more detailed information.
> >>> + This is a very likely a bug in FOP. If you encounter this
> >> error, please
> >>> + <link href="bugs.html#issues_new">Open a New Bug</link>.
> >>> </p>
> >>> </answer>
> >>> </faq>
> >>> @@ -322,9 +308,9 @@
> >>> <answer>
> >>> <p>
> >>> The most likely reason is a known problem with the Java run
> >> time
> >>> - environment which is triggered by rendering SVGs. Suns JDK
> >> 1.4 does
> >>> - not have this problem. See also <link href="#svghangs">FOP
> >> does not
> >>> - exit if a SVG is included</link>.
> >>> + environment which is triggered by rendering SVGs. Sun's JDK
> >> 1.4 and
> >>> + later do not have this problem. See also <link
> >> href="#svghangs">FOP
> >>> + does not exit if a SVG is included</link>.
> >>> </p>
> >>> <p>
> >>> Another possibility is that FOP went into a non terminating
> >>> @@ -340,6 +326,10 @@
> >>> the FOP output regularly to empty the pipe buffer. It is
> best
> >> to avoid
> >>> exec'ing FOP, use the library interface instead.
> >>> </p>
> >>> + <p>
> >>> + If you can reproduce this problem given a specific input and
> >> configuration,
> >>> + then please <link href="bugs.html#issues_new">Open a New
> >> Bug</link>.
> >>> + </p>
> >>> </answer>
> >>> </faq>
> >>> <faq id="boxoverflow">
> >>> @@ -441,8 +431,7 @@ public class DefaultErrorListener implem
> >>> To avoid the warning you can simply delete the
> >>> old Font Cache file, which lives in ${base}\conf\font.cache
> >> (see <link
> >>> href="1.0/configuration.html#general-elements">font-base
> >>> - configuration</link>). Or you can disable Font Caching
> >> altogether using
> >>> - the option "use-cache."
> >>> + configuration</link>).
> >>> </p>
> >>> </answer>
> >>> </faq>
> >>> @@ -524,7 +513,7 @@ Check the following:</p>
> >>> HTTP. Possible issues include security settings on the
> >>> server, server configuration, and missing cookies or other
> >>> authorization information. Any easy way to check this is to
> >>> - cut&paste the source URL from the fo:external-graphic
> >>> + cut and paste the source URL from the
> >> <code>fo:external-graphic</code>
> >>> into the Location field of a browser <strong>on the machine
> >>> where the FOP process will be running</strong>.</li>
> >>> </ul>
> >>> @@ -627,7 +616,7 @@ Check the following:</p>
> >>> explicit wrapping+clipping,
> >>> </li>
> >>> <li>
> >>> - insert zero width spaces (U+200B or &#x200B;) to allow
> >> FOP to
> >>> + insert zero width spaces (&#x200B;) to allow FOP to
> >>> wrap.
> >>> </li>
> >>> </ul>
> >>> @@ -1281,7 +1270,7 @@ Can I control this?</question>
> >>> <question>Where can I learn how the FOP docs and web site are
> >> built?</question>
> >>> <answer>
> >>> <p>
> >>> - See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
> >>> + See FOP <link href="dev/doc.html">Doc Management</link>.
> >>> </p>
> >>> </answer>
> >>> </faq>
> >>> @@ -1307,7 +1296,7 @@ Can I control this?</question>
> >>> If you have a runtime exception or other runtime problem:
> >>> <ul>
> >>> <li>
> >>> - double-check the <link href="#part-running">Runtime
> >> FAQs</link>.
> >>> + Double check the <link href="#part-running">Runtime
> >> FAQs</link>.
> >>> </li>
> >>> <li>
> >>> ClassNotFoundException, NoSuchMethodException and
> >>> @@ -1325,7 +1314,7 @@ Can I control this?</question>
> >>> </li>
> >>> <li>
> >>> In the case where something works properly with another
> >> formatter,
> >>> - (AntennaHouse, PassiveTex, etc.) but doesn't work with
> FOP,
> >> please
> >>> + (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work
> >> with FOP, please
> >>> check the <!--link href="relnotes.html"-->Release
> >> Notes<!--/link-->, the
> >>> <link href="compliance.html">FOP Standards
> >> Compliance</link> document,
> >>> and the remaining FAQ in this document. If not found
> there,
> >> look at the
> >>> @@ -1348,13 +1337,8 @@ Can I control this?</question>
> >>> Problems specific to a certain XSLT processor, like Xalan,
> >> Saxon or
> >>> MSXML, should be handled by processor specific lists. This
> >> includes
> >>> problems with deployment, processor specific extensions,
> >> suspected
> >>> - bugs and processor specific APIs. Note that JDK 1.4 comes
> >> with an
> >>> - XML parser and an XSLT processor which are older versions
> of
> >>> - Xerces and Xalan, respectively, and both have a number of
> >> annoying
> >>> - bugs. See
> >> http://java.sun.com/developer/EJTechTips/2003/tt0311.html
> >>> - and
> http://java.sun.com/j2se/1.4.2/docs/guide/standards/(or similar
> >>> - pages for later Java releases) for some hints on how to
> use
> >> more
> >>> - recent versions or other packages instead.
> >>> + bugs and processor specific APIs. Note that JDK 1.4 and
> >> later come with an
> >>> + XML parser and an XSLT processor which may be the source
> of
> >> the problem.
> >>> </li>
> >>> <li>
> >>> Problems with servlet containers should be asked on the
> >> vendor
> >>>
> >>> Modified: xmlgraphics/fop/trunk/status.xml
> >>> URL:
> >>
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/status.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >>>
> >>
> ==============================================================================
> >>> --- xmlgraphics/fop/trunk/status.xml (original)
> >>> +++ xmlgraphics/fop/trunk/status.xml Fri May 25 19:10:28 2012
> >>> @@ -63,6 +63,9 @@
> >>> documents. Example: the fix of marks layering will be such a
> case
> >> when it's done.
> >>> -->
> >>> <release version="FOP Trunk" date="TBD">
> >>> + <action context="Docs" dev="GA" type="update">
> >>> + Update FAQ and New Bug documentation.
> >>> + </action>
> >>> <action context="Code" dev="VH" type="add">
> >>> Added support for the role property on fo:page-sequence,
> >> fo:flow and fo:static-content. This
> >>> allows to change the mapping of those FOs to PDF structure
> >> types when enabling
> >>>
> >>>
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
> >>> For additional commands, e-mail:
> fop-commits-help@xmlgraphics.apache.org
> >>>
> >>
> >
>
Re: svn commit: r1342781 - in /xmlgraphics/fop/trunk: src/documentation/content/xdocs/bugs.xml
src/documentation/content/xdocs/faq.xml status.xml
Posted by Vincent Hennebert <vh...@gmail.com>.
Ok, so what about the attached diff?
Thanks,
Vincent
On 10/10/12 00:50, Glenn Adams wrote:
> As long as you don't remove the MUST/SHOULD language about providing an
> input FO file, then I don't mind you taking another editing pass. If you
> want to change the MUST/SHOULD language, then please propose a replacement
> for discussion here.
>
> On Tue, Oct 9, 2012 at 11:10 PM, Vincent Hennebert <vh...@gmail.com>wrote:
>
>> (Going through old unread commit messages...)
>>
>> I’d like to soften a bit the rather martial tone introduced in those
>> changes. If I were a new user looking into submitting a bug and reading
>> this page, I think I would refrain from doing so for fear of the police
>> forces breaking into my home in the middle of the night and pointing
>> a gun to my head because I dared not to follow the process... :-)
>>
>> Any objections?
>>
>> Thanks,
>> Vincent
>>
>>
>> On 25/05/12 20:10, gadams wrote:
>>> Author: gadams
>>> Date: Fri May 25 19:10:28 2012
>>> New Revision: 1342781
>>>
>>> URL: http://svn.apache.org/viewvc?rev=1342781&view=rev
>>> Log:
>>> Update FAQ and New Bug documentation.
>>>
>>> Modified:
>>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>>> xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>>> xmlgraphics/fop/trunk/status.xml
>>>
>>> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>>> URL:
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>
>> ==============================================================================
>>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
>> (original)
>>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml Fri
>> May 25 19:10:28 2012
>>> @@ -45,21 +45,66 @@ an email as changes are made to the issu
>>> </section>
>>> <section id="issues_new">
>>> <title>Unreported Issues (Reporting New Issues)</title>
>>> - <p>User reports of bugs and requests for enhancements are
>> extremely
>>> -important parts of FOP development, and we appreciate the time you take
>> to help
>>> -us track these issues down.</p>
>>> + <p>
>>> + User reports of bugs and requests for enhancements are extremely
>>> + important parts of FOP development, and we appreciate the time
>> you take to help
>>> + us track these issues down.
>>> + </p>
>>> <ul>
>>> - <li>To help us ensure that the bug database is as useful as it
>> should be, please
>>> -use the <link href="gethelp.html">Getting Help</link> checklist to
>> determine whether a bug report should be entered.</li>
>>> - <li>Review the <link href="
>> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
>> Bug Writing Guidelines</link> before submitting your report.</li>
>>> - <li>Enter a new issue report at <link href="
>> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP
>> issue database (Bugzilla)</link>.
>>> -You will be asked to login to an existing Bugzilla account or to create
>> a new
>>> -one.
>>> -When entering the bug report, please make your description complete and
>> concise.
>>> -If appropriate, attach a minimal fo file to your report which
>> demonstrates the
>>> -problem.</li>
>>> - <li>After submission, a copy of your bug report will be
>> automatically
>>> -sent to the FOP developer discussion list.</li>
>>> + <li>
>>> + To help us ensure that the bug database is as useful as it
>> should be, please
>>> + use the <link href="gethelp.html">Getting Help</link>
>> checklist to determine whether a bug report should be entered.
>>> + </li>
>>> + <li>
>>> + Review the <link href="
>> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug
>>> + Writing Guidelines</link> before submitting your report.
>>> + </li>
>>> + <li>
>>> + Enter a new issue report at <link href="
>> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
>>> + FOP issue database (Bugzilla)</link>. You will be asked to
>> login to an existing Bugzilla account or to
>>> + create a new one. When entering the bug report, please make
>> your description complete and concise.
>>> + If the issue involves a specific input or output file, then
>> you <strong>MUST</strong> include the
>>> + following information in the bug report (preferably as one or
>> more attachments):
>>> + <ul>
>>> + <li>
>>> + an input XSL-FO file (an input XML plus XSLT file is not
>> acceptable, unless and only if the
>>> + issue being reported is related to the built-in XSLT
>> transform processing convenience function provided
>>> + by FOP); this input <strong>SHOULD</strong> be
>> <em>maximally minimal</em>, which means that it should
>>> + contain nothing more than the minimum needed to
>> demonstrate the problem; if you do not take the effort
>>> + to provide a maximally minimal input FO file, then you
>> will be subsequently asked to do so before the
>>> + bug is processed;
>>> + </li>
>>> + <li>
>>> + a resulting output file, preferably in PDF format; if the
>> issue being reported involves a different output
>>> + format, then provide both a PDF output file and the
>> output file for the output format for which the report
>>> + applies;
>>> + </li>
>>> + <li>
>>> + a copy of the FOP configuration file you used (e.g.,
>> fop.xconf);
>>> + </li>
>>> + <li>
>>> + if FOP was invoked using the command line (or an
>> equivalent), then a dump of both the input
>>> + command line and any console output (stderr or stdout)
>> produced; if the report involves an
>>> + exception, then this <strong>MUST</strong> include the
>> full stack back trace;
>>> + </li>
>>> + <li>
>>> + information describing the version of FOP you are using
>> and the platform (and OS) on which
>>> + you are invoking FOP;
>>> + </li>
>>> + <li>
>>> + if the report applies to the use of a specific font other
>> than one of the built-in, base 14
>>> + fonts, then information that describes where to obtain
>> the font.
>>> + </li>
>>> + </ul>
>>> + </li>
>>> + <li>
>>> + After submission, a copy of your bug report will be
>> automatically
>>> + sent to the FOP developer discussion list. If additional
>> information is needed to
>>> + process the bug, then the bug will be set to the
>> <code>NEEDSINFO</code> state, and
>>> + you will be asked to provide the additional information. You
>> can avoid this extra
>>> + step by being diligent about providing <strong>all</strong>
>> of the information
>>> + indicated above.
>>> + </li>
>>> </ul>
>>> </section>
>>> </body>
>>>
>>> Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>>> URL:
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>
>> ==============================================================================
>>> --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
>> (original)
>>> +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml Fri
>> May 25 19:10:28 2012
>>> @@ -25,7 +25,7 @@
>>> <question>What is Apacheâ„¢ FOP?</question>
>>> <answer>
>>> <p>
>>> - FOP is a print formatter for <link href="#XSLFO">XSL formatting
>>> + FOP is a print formatter for <link href="#xslfo">XSL formatting
>>> objects</link>.
>>> </p>
>>> <p>
>>> @@ -65,16 +65,23 @@
>>> <question>How does FOP interact with other Apache
>> Projects?</question>
>>> <answer>
>>> <p>
>>> - FOP is distributed with <link
>>> - href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF
>> serializer
>>> - for XSL (FO) documents.
>>> + <link href="http://xmlgraphics.apache.org/commons">XML
>> Graphics Commons</link> is used with
>>> + FOP to provide graphics functions that are common to a number
>> of Apache projects.
>>> </p>
>>> <p>
>>> - <link href="http://xmlgraphics.apache.org/batik">Batik</link>
>> can be used with
>>> + <link href="http://xmlgraphics.apache.org/batik">Batik</link>
>> is used with
>>> FOP to <link
>>> href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode
>> an SVG
>>> image</link> into a PDF document.
>>> </p>
>>> + <p>FOP also makes use of the following Apache projects:</p>
>>> + <ul>
>>> + <li><link href="http://excalibur.apache.org/framework/">Avalon
>> Framework</link></li>
>>> + <li><link href="http://jakarta.apache.org/commons/io/">Jakarta
>> Commons IO</link></li>
>>> + <li><link href="http://jakarta.apache.org/commons/logging/">Jakarta
>> Commons Logging</link></li>
>>> + <li><link href="http://xalan.apache.org/">Xalan-J</link></li>
>>> + <li><link href="
>> http://xml.apache.org/commons/components/external/">XML Commons
>> Externals</link></li>
>>> + </ul>
>>> </answer>
>>> </faq>
>>> <faq id="xsl-def">
>>> @@ -83,7 +90,7 @@
>>> <p>
>>> XSL is a W3C standard concerned with publishing XML
>> documents. It
>>> consists of two parts: <link href="#XSLT">XSLT</link> and
>> <link
>>> - href="#XSLFO">XSL-FO</link>. The acronym expands to
>>> + href="#xslfo">XSL-FO</link>. The acronym expands to
>>> e<strong>X</strong>tensible <strong>S</strong>tylesheet
>>> <strong>L</strong>anguage.
>>> </p>
>>> @@ -93,7 +100,9 @@
>>> <question>What is XSL-FO?</question>
>>> <answer>
>>> <p>
>>> - XSLFO (aka XSL-FO) is an XML vocabulary that is used to
>> specify a pagination and
>>> + XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C
>> Recommendation
>>> + <link href="http://www.w3.org/TR/xsl/">Extensible Stylesheet
>> Language (XSL)
>>> + Version 1.1</link>, that is used to specify a pagination and
>>> other styling for page layout output. The acronym
>> “FO”
>>> stands for
>>> <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO
>> can be
>>> @@ -226,8 +235,7 @@
>>> <answer>
>>> <p>
>>> This is usually caused by an older version of one of the FOP
>> jars or
>>> - old XML tools in the classpath. Check in particular for
>> parser.jar,
>>> - jaxp.jar, xml4j.jar or lotusxsl.jar.
>>> + old XML tools in the classpath.
>>> </p>
>>> <p>
>>> Incompatible versions of Batik may also cause this problem.
>> Use the
>>> @@ -269,8 +277,9 @@
>>> the <code>file:</code> prefix, for example
>> <code>file.ext</code>,
>>> <code>path/file.ext</code> or <code>../file.ext</code>. The
>> string
>>> <code>file:path/file.ext</code> is <em>not</em> a relative
>> URL,
>>> - in fact, it isn't a valid URL at all. A relative URL is
>> subject to a
>>> - resolving process, which transforms it into an absolute
>>> + in fact, it isn't a valid URL at all since the
>> <code>file</code>
>>> + scheme does not (officially) support relative paths. A
>> relative URL
>>> + is subject to a resolving process, which transforms it into
>> an absolute
>>> URL.
>>> </p>
>>> <!--p>
>>> @@ -283,31 +292,8 @@
>>> <question>I get an "[ERROR]: null", or a
>> NullPointerException.</question>
>>> <answer>
>>> <p>
>>> - This is often caused by an invalid FO document. Currently
>> only very
>>> - common errors are intercepted and produce a comprehensible
>> error
>>> - message. If you forgot container elements like
>> <code>fo:page-sequence</code> or
>>> - <code>fo:flow</code> and put blocks and inline elements
>> directly as children of
>>> - <code>fo:root</code> or <code>fo:page-sequence</code>, you'll
>> only get a
>>> - NullPointerException. Check whether your FO file has a proper
>>> - structure. In some cases there are mandatory properties, like
>> the
>>> - master-reference in
>> <code>fo:conditional-page-master-reference</code>, check also
>>> - whether you got them right.
>>> - </p>
>>> - <p>
>>> - You may find it helpful to use the <link
>> href="#fo-validate">validation tools</link> to validate your
>>> - FO document. This will catch most problems, but should not be
>>> - relied upon to catch all.
>>> - </p>
>>> - <p>
>>> - If you use XSLT, problems in your style sheet and in your
>>> - source XML also can produce a NullPointerException. <link
>>> - href="1.0/running.html#check-input">Run the transformation
>>> - separately</link> to check for this, usually you'll get a
>>> - detailed error message from the XSLT processor.
>>> - </p>
>>> - <p>
>>> - If you turn on debugging with the "<code>-d</code>" option
>> you may be able to
>>> - see more detailed information.
>>> + This is a very likely a bug in FOP. If you encounter this
>> error, please
>>> + <link href="bugs.html#issues_new">Open a New Bug</link>.
>>> </p>
>>> </answer>
>>> </faq>
>>> @@ -322,9 +308,9 @@
>>> <answer>
>>> <p>
>>> The most likely reason is a known problem with the Java run
>> time
>>> - environment which is triggered by rendering SVGs. Suns JDK
>> 1.4 does
>>> - not have this problem. See also <link href="#svghangs">FOP
>> does not
>>> - exit if a SVG is included</link>.
>>> + environment which is triggered by rendering SVGs. Sun's JDK
>> 1.4 and
>>> + later do not have this problem. See also <link
>> href="#svghangs">FOP
>>> + does not exit if a SVG is included</link>.
>>> </p>
>>> <p>
>>> Another possibility is that FOP went into a non terminating
>>> @@ -340,6 +326,10 @@
>>> the FOP output regularly to empty the pipe buffer. It is best
>> to avoid
>>> exec'ing FOP, use the library interface instead.
>>> </p>
>>> + <p>
>>> + If you can reproduce this problem given a specific input and
>> configuration,
>>> + then please <link href="bugs.html#issues_new">Open a New
>> Bug</link>.
>>> + </p>
>>> </answer>
>>> </faq>
>>> <faq id="boxoverflow">
>>> @@ -441,8 +431,7 @@ public class DefaultErrorListener implem
>>> To avoid the warning you can simply delete the
>>> old Font Cache file, which lives in ${base}\conf\font.cache
>> (see <link
>>> href="1.0/configuration.html#general-elements">font-base
>>> - configuration</link>). Or you can disable Font Caching
>> altogether using
>>> - the option "use-cache."
>>> + configuration</link>).
>>> </p>
>>> </answer>
>>> </faq>
>>> @@ -524,7 +513,7 @@ Check the following:</p>
>>> HTTP. Possible issues include security settings on the
>>> server, server configuration, and missing cookies or other
>>> authorization information. Any easy way to check this is to
>>> - cut&paste the source URL from the fo:external-graphic
>>> + cut and paste the source URL from the
>> <code>fo:external-graphic</code>
>>> into the Location field of a browser <strong>on the machine
>>> where the FOP process will be running</strong>.</li>
>>> </ul>
>>> @@ -627,7 +616,7 @@ Check the following:</p>
>>> explicit wrapping+clipping,
>>> </li>
>>> <li>
>>> - insert zero width spaces (U+200B or &#x200B;) to allow
>> FOP to
>>> + insert zero width spaces (&#x200B;) to allow FOP to
>>> wrap.
>>> </li>
>>> </ul>
>>> @@ -1281,7 +1270,7 @@ Can I control this?</question>
>>> <question>Where can I learn how the FOP docs and web site are
>> built?</question>
>>> <answer>
>>> <p>
>>> - See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
>>> + See FOP <link href="dev/doc.html">Doc Management</link>.
>>> </p>
>>> </answer>
>>> </faq>
>>> @@ -1307,7 +1296,7 @@ Can I control this?</question>
>>> If you have a runtime exception or other runtime problem:
>>> <ul>
>>> <li>
>>> - double-check the <link href="#part-running">Runtime
>> FAQs</link>.
>>> + Double check the <link href="#part-running">Runtime
>> FAQs</link>.
>>> </li>
>>> <li>
>>> ClassNotFoundException, NoSuchMethodException and
>>> @@ -1325,7 +1314,7 @@ Can I control this?</question>
>>> </li>
>>> <li>
>>> In the case where something works properly with another
>> formatter,
>>> - (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP,
>> please
>>> + (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work
>> with FOP, please
>>> check the <!--link href="relnotes.html"-->Release
>> Notes<!--/link-->, the
>>> <link href="compliance.html">FOP Standards
>> Compliance</link> document,
>>> and the remaining FAQ in this document. If not found there,
>> look at the
>>> @@ -1348,13 +1337,8 @@ Can I control this?</question>
>>> Problems specific to a certain XSLT processor, like Xalan,
>> Saxon or
>>> MSXML, should be handled by processor specific lists. This
>> includes
>>> problems with deployment, processor specific extensions,
>> suspected
>>> - bugs and processor specific APIs. Note that JDK 1.4 comes
>> with an
>>> - XML parser and an XSLT processor which are older versions of
>>> - Xerces and Xalan, respectively, and both have a number of
>> annoying
>>> - bugs. See
>> http://java.sun.com/developer/EJTechTips/2003/tt0311.html
>>> - and http://java.sun.com/j2se/1.4.2/docs/guide/standards/(or similar
>>> - pages for later Java releases) for some hints on how to use
>> more
>>> - recent versions or other packages instead.
>>> + bugs and processor specific APIs. Note that JDK 1.4 and
>> later come with an
>>> + XML parser and an XSLT processor which may be the source of
>> the problem.
>>> </li>
>>> <li>
>>> Problems with servlet containers should be asked on the
>> vendor
>>>
>>> Modified: xmlgraphics/fop/trunk/status.xml
>>> URL:
>> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/status.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
>>>
>> ==============================================================================
>>> --- xmlgraphics/fop/trunk/status.xml (original)
>>> +++ xmlgraphics/fop/trunk/status.xml Fri May 25 19:10:28 2012
>>> @@ -63,6 +63,9 @@
>>> documents. Example: the fix of marks layering will be such a case
>> when it's done.
>>> -->
>>> <release version="FOP Trunk" date="TBD">
>>> + <action context="Docs" dev="GA" type="update">
>>> + Update FAQ and New Bug documentation.
>>> + </action>
>>> <action context="Code" dev="VH" type="add">
>>> Added support for the role property on fo:page-sequence,
>> fo:flow and fo:static-content. This
>>> allows to change the mapping of those FOs to PDF structure
>> types when enabling
>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
>>> For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
>>>
>>
>
Re: svn commit: r1342781 - in /xmlgraphics/fop/trunk:
src/documentation/content/xdocs/bugs.xml src/documentation/content/xdocs/faq.xml
status.xml
Posted by Glenn Adams <gl...@skynav.com>.
As long as you don't remove the MUST/SHOULD language about providing an
input FO file, then I don't mind you taking another editing pass. If you
want to change the MUST/SHOULD language, then please propose a replacement
for discussion here.
On Tue, Oct 9, 2012 at 11:10 PM, Vincent Hennebert <vh...@gmail.com>wrote:
> (Going through old unread commit messages...)
>
> I’d like to soften a bit the rather martial tone introduced in those
> changes. If I were a new user looking into submitting a bug and reading
> this page, I think I would refrain from doing so for fear of the police
> forces breaking into my home in the middle of the night and pointing
> a gun to my head because I dared not to follow the process... :-)
>
> Any objections?
>
> Thanks,
> Vincent
>
>
> On 25/05/12 20:10, gadams wrote:
> > Author: gadams
> > Date: Fri May 25 19:10:28 2012
> > New Revision: 1342781
> >
> > URL: http://svn.apache.org/viewvc?rev=1342781&view=rev
> > Log:
> > Update FAQ and New Bug documentation.
> >
> > Modified:
> > xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> > xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> > xmlgraphics/fop/trunk/status.xml
> >
> > Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> > URL:
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >
> ==============================================================================
> > --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml
> (original)
> > +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/bugs.xml Fri
> May 25 19:10:28 2012
> > @@ -45,21 +45,66 @@ an email as changes are made to the issu
> > </section>
> > <section id="issues_new">
> > <title>Unreported Issues (Reporting New Issues)</title>
> > - <p>User reports of bugs and requests for enhancements are
> extremely
> > -important parts of FOP development, and we appreciate the time you take
> to help
> > -us track these issues down.</p>
> > + <p>
> > + User reports of bugs and requests for enhancements are extremely
> > + important parts of FOP development, and we appreciate the time
> you take to help
> > + us track these issues down.
> > + </p>
> > <ul>
> > - <li>To help us ensure that the bug database is as useful as it
> should be, please
> > -use the <link href="gethelp.html">Getting Help</link> checklist to
> determine whether a bug report should be entered.</li>
> > - <li>Review the <link href="
> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache
> Bug Writing Guidelines</link> before submitting your report.</li>
> > - <li>Enter a new issue report at <link href="
> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP
> issue database (Bugzilla)</link>.
> > -You will be asked to login to an existing Bugzilla account or to create
> a new
> > -one.
> > -When entering the bug report, please make your description complete and
> concise.
> > -If appropriate, attach a minimal fo file to your report which
> demonstrates the
> > -problem.</li>
> > - <li>After submission, a copy of your bug report will be
> automatically
> > -sent to the FOP developer discussion list.</li>
> > + <li>
> > + To help us ensure that the bug database is as useful as it
> should be, please
> > + use the <link href="gethelp.html">Getting Help</link>
> checklist to determine whether a bug report should be entered.
> > + </li>
> > + <li>
> > + Review the <link href="
> http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug
> > + Writing Guidelines</link> before submitting your report.
> > + </li>
> > + <li>
> > + Enter a new issue report at <link href="
> http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
> > + FOP issue database (Bugzilla)</link>. You will be asked to
> login to an existing Bugzilla account or to
> > + create a new one. When entering the bug report, please make
> your description complete and concise.
> > + If the issue involves a specific input or output file, then
> you <strong>MUST</strong> include the
> > + following information in the bug report (preferably as one or
> more attachments):
> > + <ul>
> > + <li>
> > + an input XSL-FO file (an input XML plus XSLT file is not
> acceptable, unless and only if the
> > + issue being reported is related to the built-in XSLT
> transform processing convenience function provided
> > + by FOP); this input <strong>SHOULD</strong> be
> <em>maximally minimal</em>, which means that it should
> > + contain nothing more than the minimum needed to
> demonstrate the problem; if you do not take the effort
> > + to provide a maximally minimal input FO file, then you
> will be subsequently asked to do so before the
> > + bug is processed;
> > + </li>
> > + <li>
> > + a resulting output file, preferably in PDF format; if the
> issue being reported involves a different output
> > + format, then provide both a PDF output file and the
> output file for the output format for which the report
> > + applies;
> > + </li>
> > + <li>
> > + a copy of the FOP configuration file you used (e.g.,
> fop.xconf);
> > + </li>
> > + <li>
> > + if FOP was invoked using the command line (or an
> equivalent), then a dump of both the input
> > + command line and any console output (stderr or stdout)
> produced; if the report involves an
> > + exception, then this <strong>MUST</strong> include the
> full stack back trace;
> > + </li>
> > + <li>
> > + information describing the version of FOP you are using
> and the platform (and OS) on which
> > + you are invoking FOP;
> > + </li>
> > + <li>
> > + if the report applies to the use of a specific font other
> than one of the built-in, base 14
> > + fonts, then information that describes where to obtain
> the font.
> > + </li>
> > + </ul>
> > + </li>
> > + <li>
> > + After submission, a copy of your bug report will be
> automatically
> > + sent to the FOP developer discussion list. If additional
> information is needed to
> > + process the bug, then the bug will be set to the
> <code>NEEDSINFO</code> state, and
> > + you will be asked to provide the additional information. You
> can avoid this extra
> > + step by being diligent about providing <strong>all</strong>
> of the information
> > + indicated above.
> > + </li>
> > </ul>
> > </section>
> > </body>
> >
> > Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> > URL:
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >
> ==============================================================================
> > --- xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml
> (original)
> > +++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/faq.xml Fri
> May 25 19:10:28 2012
> > @@ -25,7 +25,7 @@
> > <question>What is Apacheâ„¢ FOP?</question>
> > <answer>
> > <p>
> > - FOP is a print formatter for <link href="#XSLFO">XSL formatting
> > + FOP is a print formatter for <link href="#xslfo">XSL formatting
> > objects</link>.
> > </p>
> > <p>
> > @@ -65,16 +65,23 @@
> > <question>How does FOP interact with other Apache
> Projects?</question>
> > <answer>
> > <p>
> > - FOP is distributed with <link
> > - href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF
> serializer
> > - for XSL (FO) documents.
> > + <link href="http://xmlgraphics.apache.org/commons">XML
> Graphics Commons</link> is used with
> > + FOP to provide graphics functions that are common to a number
> of Apache projects.
> > </p>
> > <p>
> > - <link href="http://xmlgraphics.apache.org/batik">Batik</link>
> can be used with
> > + <link href="http://xmlgraphics.apache.org/batik">Batik</link>
> is used with
> > FOP to <link
> > href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode
> an SVG
> > image</link> into a PDF document.
> > </p>
> > + <p>FOP also makes use of the following Apache projects:</p>
> > + <ul>
> > + <li><link href="http://excalibur.apache.org/framework/">Avalon
> Framework</link></li>
> > + <li><link href="http://jakarta.apache.org/commons/io/">Jakarta
> Commons IO</link></li>
> > + <li><link href="http://jakarta.apache.org/commons/logging/">Jakarta
> Commons Logging</link></li>
> > + <li><link href="http://xalan.apache.org/">Xalan-J</link></li>
> > + <li><link href="
> http://xml.apache.org/commons/components/external/">XML Commons
> Externals</link></li>
> > + </ul>
> > </answer>
> > </faq>
> > <faq id="xsl-def">
> > @@ -83,7 +90,7 @@
> > <p>
> > XSL is a W3C standard concerned with publishing XML
> documents. It
> > consists of two parts: <link href="#XSLT">XSLT</link> and
> <link
> > - href="#XSLFO">XSL-FO</link>. The acronym expands to
> > + href="#xslfo">XSL-FO</link>. The acronym expands to
> > e<strong>X</strong>tensible <strong>S</strong>tylesheet
> > <strong>L</strong>anguage.
> > </p>
> > @@ -93,7 +100,9 @@
> > <question>What is XSL-FO?</question>
> > <answer>
> > <p>
> > - XSLFO (aka XSL-FO) is an XML vocabulary that is used to
> specify a pagination and
> > + XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C
> Recommendation
> > + <link href="http://www.w3.org/TR/xsl/">Extensible Stylesheet
> Language (XSL)
> > + Version 1.1</link>, that is used to specify a pagination and
> > other styling for page layout output. The acronym
> “FO”
> > stands for
> > <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO
> can be
> > @@ -226,8 +235,7 @@
> > <answer>
> > <p>
> > This is usually caused by an older version of one of the FOP
> jars or
> > - old XML tools in the classpath. Check in particular for
> parser.jar,
> > - jaxp.jar, xml4j.jar or lotusxsl.jar.
> > + old XML tools in the classpath.
> > </p>
> > <p>
> > Incompatible versions of Batik may also cause this problem.
> Use the
> > @@ -269,8 +277,9 @@
> > the <code>file:</code> prefix, for example
> <code>file.ext</code>,
> > <code>path/file.ext</code> or <code>../file.ext</code>. The
> string
> > <code>file:path/file.ext</code> is <em>not</em> a relative
> URL,
> > - in fact, it isn't a valid URL at all. A relative URL is
> subject to a
> > - resolving process, which transforms it into an absolute
> > + in fact, it isn't a valid URL at all since the
> <code>file</code>
> > + scheme does not (officially) support relative paths. A
> relative URL
> > + is subject to a resolving process, which transforms it into
> an absolute
> > URL.
> > </p>
> > <!--p>
> > @@ -283,31 +292,8 @@
> > <question>I get an "[ERROR]: null", or a
> NullPointerException.</question>
> > <answer>
> > <p>
> > - This is often caused by an invalid FO document. Currently
> only very
> > - common errors are intercepted and produce a comprehensible
> error
> > - message. If you forgot container elements like
> <code>fo:page-sequence</code> or
> > - <code>fo:flow</code> and put blocks and inline elements
> directly as children of
> > - <code>fo:root</code> or <code>fo:page-sequence</code>, you'll
> only get a
> > - NullPointerException. Check whether your FO file has a proper
> > - structure. In some cases there are mandatory properties, like
> the
> > - master-reference in
> <code>fo:conditional-page-master-reference</code>, check also
> > - whether you got them right.
> > - </p>
> > - <p>
> > - You may find it helpful to use the <link
> href="#fo-validate">validation tools</link> to validate your
> > - FO document. This will catch most problems, but should not be
> > - relied upon to catch all.
> > - </p>
> > - <p>
> > - If you use XSLT, problems in your style sheet and in your
> > - source XML also can produce a NullPointerException. <link
> > - href="1.0/running.html#check-input">Run the transformation
> > - separately</link> to check for this, usually you'll get a
> > - detailed error message from the XSLT processor.
> > - </p>
> > - <p>
> > - If you turn on debugging with the "<code>-d</code>" option
> you may be able to
> > - see more detailed information.
> > + This is a very likely a bug in FOP. If you encounter this
> error, please
> > + <link href="bugs.html#issues_new">Open a New Bug</link>.
> > </p>
> > </answer>
> > </faq>
> > @@ -322,9 +308,9 @@
> > <answer>
> > <p>
> > The most likely reason is a known problem with the Java run
> time
> > - environment which is triggered by rendering SVGs. Suns JDK
> 1.4 does
> > - not have this problem. See also <link href="#svghangs">FOP
> does not
> > - exit if a SVG is included</link>.
> > + environment which is triggered by rendering SVGs. Sun's JDK
> 1.4 and
> > + later do not have this problem. See also <link
> href="#svghangs">FOP
> > + does not exit if a SVG is included</link>.
> > </p>
> > <p>
> > Another possibility is that FOP went into a non terminating
> > @@ -340,6 +326,10 @@
> > the FOP output regularly to empty the pipe buffer. It is best
> to avoid
> > exec'ing FOP, use the library interface instead.
> > </p>
> > + <p>
> > + If you can reproduce this problem given a specific input and
> configuration,
> > + then please <link href="bugs.html#issues_new">Open a New
> Bug</link>.
> > + </p>
> > </answer>
> > </faq>
> > <faq id="boxoverflow">
> > @@ -441,8 +431,7 @@ public class DefaultErrorListener implem
> > To avoid the warning you can simply delete the
> > old Font Cache file, which lives in ${base}\conf\font.cache
> (see <link
> > href="1.0/configuration.html#general-elements">font-base
> > - configuration</link>). Or you can disable Font Caching
> altogether using
> > - the option "use-cache."
> > + configuration</link>).
> > </p>
> > </answer>
> > </faq>
> > @@ -524,7 +513,7 @@ Check the following:</p>
> > HTTP. Possible issues include security settings on the
> > server, server configuration, and missing cookies or other
> > authorization information. Any easy way to check this is to
> > - cut&paste the source URL from the fo:external-graphic
> > + cut and paste the source URL from the
> <code>fo:external-graphic</code>
> > into the Location field of a browser <strong>on the machine
> > where the FOP process will be running</strong>.</li>
> > </ul>
> > @@ -627,7 +616,7 @@ Check the following:</p>
> > explicit wrapping+clipping,
> > </li>
> > <li>
> > - insert zero width spaces (U+200B or &#x200B;) to allow
> FOP to
> > + insert zero width spaces (&#x200B;) to allow FOP to
> > wrap.
> > </li>
> > </ul>
> > @@ -1281,7 +1270,7 @@ Can I control this?</question>
> > <question>Where can I learn how the FOP docs and web site are
> built?</question>
> > <answer>
> > <p>
> > - See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
> > + See FOP <link href="dev/doc.html">Doc Management</link>.
> > </p>
> > </answer>
> > </faq>
> > @@ -1307,7 +1296,7 @@ Can I control this?</question>
> > If you have a runtime exception or other runtime problem:
> > <ul>
> > <li>
> > - double-check the <link href="#part-running">Runtime
> FAQs</link>.
> > + Double check the <link href="#part-running">Runtime
> FAQs</link>.
> > </li>
> > <li>
> > ClassNotFoundException, NoSuchMethodException and
> > @@ -1325,7 +1314,7 @@ Can I control this?</question>
> > </li>
> > <li>
> > In the case where something works properly with another
> formatter,
> > - (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP,
> please
> > + (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work
> with FOP, please
> > check the <!--link href="relnotes.html"-->Release
> Notes<!--/link-->, the
> > <link href="compliance.html">FOP Standards
> Compliance</link> document,
> > and the remaining FAQ in this document. If not found there,
> look at the
> > @@ -1348,13 +1337,8 @@ Can I control this?</question>
> > Problems specific to a certain XSLT processor, like Xalan,
> Saxon or
> > MSXML, should be handled by processor specific lists. This
> includes
> > problems with deployment, processor specific extensions,
> suspected
> > - bugs and processor specific APIs. Note that JDK 1.4 comes
> with an
> > - XML parser and an XSLT processor which are older versions of
> > - Xerces and Xalan, respectively, and both have a number of
> annoying
> > - bugs. See
> http://java.sun.com/developer/EJTechTips/2003/tt0311.html
> > - and http://java.sun.com/j2se/1.4.2/docs/guide/standards/(or similar
> > - pages for later Java releases) for some hints on how to use
> more
> > - recent versions or other packages instead.
> > + bugs and processor specific APIs. Note that JDK 1.4 and
> later come with an
> > + XML parser and an XSLT processor which may be the source of
> the problem.
> > </li>
> > <li>
> > Problems with servlet containers should be asked on the
> vendor
> >
> > Modified: xmlgraphics/fop/trunk/status.xml
> > URL:
> http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/status.xml?rev=1342781&r1=1342780&r2=1342781&view=diff
> >
> ==============================================================================
> > --- xmlgraphics/fop/trunk/status.xml (original)
> > +++ xmlgraphics/fop/trunk/status.xml Fri May 25 19:10:28 2012
> > @@ -63,6 +63,9 @@
> > documents. Example: the fix of marks layering will be such a case
> when it's done.
> > -->
> > <release version="FOP Trunk" date="TBD">
> > + <action context="Docs" dev="GA" type="update">
> > + Update FAQ and New Bug documentation.
> > + </action>
> > <action context="Code" dev="VH" type="add">
> > Added support for the role property on fo:page-sequence,
> fo:flow and fo:static-content. This
> > allows to change the mapping of those FOs to PDF structure
> types when enabling
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
> > For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
> >
>