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
> &#8220;FO&#8221;
> >            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&amp;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 &amp;#x200B;) to allow
> FOP to
> > +            insert zero width spaces (&amp;#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
> >
>

Reply via email to