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
> <[email protected]>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: [email protected]
>>> For additional commands, e-mail: [email protected]
>>>
>>
>
Index: bugs.xml
===================================================================
--- bugs.xml (revision 1411613)
+++ bugs.xml (working copy)
@@ -62,29 +62,29 @@
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
+ If the issue involves a specific input or output file, then please 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;
+ an input XSL-FO file (if you generate the XSL-FO file from an input XML using XSLT,
+ then please directly provide the result of the transformation (the XSL-FO output),
+ <em>not</em> the XML input and XSLT). Please try and make the XSL-FO input as small as
+ possible; Ideally it would contain nothing more than the minimum needed to demonstrate
+ the problem. By doing this you increase your chance that a developer will take the
+ time to look at your file.
</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;
+ a resulting output file, preferably in PDF format, unless the issue being reported
+ involves a different output format; In which case please provide the output in that
+ format;
</li>
<li>
- a copy of the FOP configuration file you used (e.g., fop.xconf);
+ a copy of the FOP configuration file you used (e.g., fop.xconf), if applicable;
</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;
+ exception, be sure to include the full stack trace;
</li>
<li>
information describing the version of FOP you are using and the platform (and OS) on which
@@ -92,18 +92,13 @@
</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.
+ fonts, then information that describes where to obtain the font. If the font is not
+ freely available, please describe your problem on the <link
+ href="../maillist.html#fop-user">fop-users</link> mailing list, where a developer
+ may step up and ask you to send them the font privately for investigation purpose.
</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>
