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 <vhenneb...@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-unsubscr...@xmlgraphics.apache.org > > For additional commands, e-mail: fop-commits-h...@xmlgraphics.apache.org > > >
