Normalize and clean up content. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196208 13f79535-47bb-0310-9956-ffa450edef68

21 years ago · 81d5469fd4
--- a/src/documentation/content/xdocs/bugs.xml
+++ b/src/documentation/content/xdocs/bugs.xml
@@ -30,40 +30,20 @@ an email as changes are made to the issue.</li>
      <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.
 To help us ensure that the bug database is as useful as it should be, please
 use the following checklist if you are considering reporting a new issue:</p>
        <ul>
          <li>Is your issue really a request to comply with some aspect of the
 XSL-FO standard?
 If so, please do not enter a bug report.
 The developers already carefully track which standard requirements have been
 implemented.
 Other enhancement requests are welcome, but please be sure to mark
 the issue as an enhancement.</li>
          <li>Is your issue addressed by an <link
 href="http://xml.apache.org/fop/faq.html">FAQ</link>? If so, please do not
 enter a bug report unless the FAQ did not adequately address your issue.</li>
          <li>Has this issue already been reported? If so, please do not
 report it again, as this will only slow the development team down.
 See section above for a list of issues that have already been reported.</li>
          <li>Do you know how to write a good bug report?
 Please review the
 <link href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">Apache Bug
 Writing Guidelines</link> before submitting your report.</li>
          <li>If, and only if, you have passed all of the above steps, please
 enter a new bug report at
 <link href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
 FOP bug database (Bugzilla)</link>.
 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://nagoya.apache.org/bugzilla/bugwritinghelp.html">Apache Bug Writing Guidelines</link> before submitting your report.</li>
        <li>Enter a new issue report at <link href="http://nagoya.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
        <li>After submission, a copy of your bug report will be automatically
 sent to the FOP developer discussion list.</li>
        </ul>
      </ul>
    </section>
  </body>
 </document>

--- a/src/documentation/content/xdocs/gethelp.xml
+++ b/src/documentation/content/xdocs/gethelp.xml
@@ -3,72 +3,78 @@
    "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
 <document>
  <header>
    <title>How to Get Help</title>
    <subtitle>Solving problems</subtitle>
    <title>Getting Help</title>
    <subtitle>Checklist for Finding Appropriate Resources</subtitle>
  </header>
  <body>
    <p>The FOP developer community is eager to help you maximize the usefulness of FOP.
 However, to make wise use of its limited resources, support must be primarily self-service.
 Go through the following checklist sequentially to determine what kind of help you need,
 and where to get it:</p>
    <section>
      <title>How to get Help</title>
      <ol>
        <li>
          Have a look at the documentation pages on this site. You can find
          information on how to run FOP, how to embed it, how to add custom
          fonts etc.
        </li>
        <li>
          Consult the <link href="faq.html">FAQ</link> to see if your question
          has already been answered before.
        </li>
        <li>
          If you have a question concerning XSLFO that is not related to FOP
          directly or regarding XSLT, please consult the various resources on
          the net. See <link href="resources.html">Resources</link> for some
          interesting links.
        </li>
        <li>
          Before you post your questions to one of the mailing lists, please
          search the mailing list archives, since it's possible that your
          question has already been answered but it may not have found its way
          into the FAQ. You'll find links to the mailing list archive in the
          <link href="resources.html">Resources</link>.
        </li>
        <li>
          If you still can't solve your problem subscribe to FOP's user mailing
          list and post your question there. Your question is likely to be
          handled more favorably the further down the following checklist
          you get:
          <ol>
            <li>State the version of FOP you're using.</li>
            <li>Include detailed error messages, if there are any.</li>
            <li>Provide FO code instead of XSLT snippets or DocBook source.
              See <link href="running.html#running_xalan">Running Xalan</link>
              for how to produce FO from your XML+XSLT.</li>
            <li>Provide complete, <strong>self-contained</strong> FO code.
              This includes images. Be careful with confidential material
              though.</li>
            <li>Provide <strong>short</strong>, self-contained FO code. Cut
              out everything unnecessary to demonstrate the effect, in
              particular images.</li>
            <li>Prune stack traces sensibly instead of dumping the whole
              shebang.</li>
            <li>Instead of attaching large PDF files or screen shots, use a
              small B&amp;W GIF, JPG or PNG of the area of interest.</li>
          </ol>
          This makes it easier to help you.  The instructions on how to
          subscribe to the mailin lists can be found in the <link
          href="resources.html">Resources</link>.
        </li>
        <li>
          You should probably read <link
          href="http://www.tuxedo.org/~esr/faqs/smart-questions.html">"How to
          Ask Questions the Smart Way"</link>.
        </li>
      </ol>
      <note>
        Please don't use Bugzilla to post questions. Please ask on the user
        mailing list first if you think you've found a bug.
      </note>
      <title>Understand Underlying Technologies</title>
      <p>If you have a questions about XML, XSLT, or XSL-FO that are not directly related to FOP, please consult resources that are appropriate for those questions.
 FOP is an implementation of these technologies, and when you use FOP, there is a presumption that you have a working understanding of them.
 We have included several useful links on our <link href="resources.html">Resources</link> page that may help you get started.
        </p>
    </section>
    <section>
      <title>Review FOP's Standards Compliance</title>
      <p>FOP is a work in progress, and does not yet fully comply with the W3C XSL-FO standard.
 The developers track which standard requirements have been implemented, and have documented these capabilities on the <link href="compliance.html">Compliance</link> page.
 If this document appears to be in error, continue down this checklist so that either the document or the software can be corrected.
 Otherwise, please do not submit mailing list questions or bug reports regarding features documented in the standard.</p>
    </section>
    <section>
      <title>Read the Documentation</title>
      <p>Review the documentation pages on this site.
 There is information about how to run FOP, how to embed it, how to add custom fonts etc.</p>
    </section>
    <section>
      <title>Check the FAQs</title>
      <p>Consult the <link href="faq.html">Frequently Asked Questions (FAQ)</link> to see if your question has already been answered.</p>
    </section>
    <section>
      <title>Review FOP User Mailing List Archive</title>
      <p>It is possible that your question has already been answered but has not yet found its way into the FAQ.
 Links to the FOP User mailing list archives are on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.
        </p>
    </section>
    <section>
      <title>Look for an Existing Issue Report</title>
      <p>See <link href="bugs.html#issues_existing">Reported Issues</link> for instructions on how to use the list of open issues. Review these open issues to see if any match your concerns.
 If so, please do not post a mailing list question or report another issue, as these will only slow the development team down.</p>
    </section>
    <section>
      <title>Submit Question to FOP User Mailing List</title>
      <ul>
        <li>Subscription information is on the <link href="resources.html#mailing-lists-fop-user">Resources</link> page.</li>
        <li>Review <link href="resources.html#mailing-lists-general">General Mailing List Information</link> before submitting your question.</li>
        <li>State the version of FOP you're using.</li>
        <li>Include detailed error messages, if there are any.</li>
        <li>Provide FO code instead of XSLT snippets or DocBook source. 
 See <link href="running.html#running_xalan">Running Xalan</link> for how to produce FO from your XML+XSLT.</li>
        <li>Provide the shortest possible complete, <strong>self-contained</strong> FO code that demonstrates the problem.
 Include images only if they are an integral part of the question.
 Filter out any confidential material.</li>
        <li>Include only those portions of stack traces that will be helpful in finding the problem.</li>
        <li>Instead of attaching large PDF files or screen shots, include a small B&amp;W GIF, JPG or PNG of the area of interest.</li>
      </ul>
    </section>
    <section>
      <title>Enter an Issue Report</title>
      <p>If, and only if, you have followed all of the above steps, and believe that there is a bug or needed feature that you would like to report, please enter an issue in Bugzilla. Never use Bugzilla to post questions, only to enter issues that have already been asked on the user mailing list.</p>
      <p>See <link href="bugs.html#issues_new">Reporting New Issues</link> for detailed instructions on how to enter an issue.
      </p>
    </section>
    <section>
      <title>Find Out How <em>You</em> Can Help</title>
    </section>
    <p>As stated above, the FOP development team is a limited resource. Most make their livings doing things other than writing and supporting FOP. Perhaps you need a feature from the XSL-FO standard to be implemented right away, or a bug fixed, or a new output format, or .... If so, there are several ways that you can help:</p>
    <ul>
      <li>Become a <link href="dev/index.html">FOP developer</link>.</li>
      <li>Fund a developer (or part of one). There is usually at least one FOP developer who would be glad to devote more time to FOP development if funding were in place.</li>
      <li>Help out on the user mailing list. Users giving good answers to other users allows developers to focus more on development and less on support.</li>
    </ul>
  </body>
 </document>

--- a/src/documentation/content/xdocs/resources.xml
+++ b/src/documentation/content/xdocs/resources.xml
@@ -9,16 +9,18 @@
    <subtitle>Resources useful for developing and using FOP</subtitle>
  </header>
  <body>
 <section>
  <title>FOP Relevant Specifications and Links</title>
  <section>
    <title>Mailing Lists (and archives)</title>
  <section id="mailing-lists">
    <title>Mailing Lists and Archives</title>
    <section id="mailing-lists-general">
      <title>General Information</title>
        <p>
 For the Apache mailing lists, see
 <link href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</link>
 for detailed subscription information.
        </p>
    <section>
        <p>Before posting questions to the lists, review "<link href="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</link>".</p>
    </section>
    <section id="mailing-lists-fop-user">
      <title>FOP User Mailing List</title>
        <p>
 Use this forum to discuss topics of interest to FOP users.
@@ -56,7 +58,7 @@ To unsubscribe: Send email to <link href="mailto:fop-user-unsubscribe@xml.apache
            </li>
      </ul>
    </section>
    <section>
    <section id="mailing-lists-fop-dev">
      <title>FOP Developer Mailing List</title>
          <p>
 Use this forum to discuss topics related to FOP development,
@@ -90,7 +92,7 @@ To unsubscribe: Send email to <link href="mailto:fop-dev-unsubscribe@xml.apache.
            </li>
      </ul>
    </section>
    <section>
    <section id="mailing-lists-w3c-xslfo">
      <title>XSL:FO Mailing List (at W3C)</title>
          <p>
 Use this forum to ask general XSL-FO questions.
@@ -105,7 +107,7 @@ Subscription administration information can be found at <link href="http://www.w
      </ul>
    </section>
  </section>
  <section>
  <section id="specs">
    <title>Specifications</title>
  <ul>
          <li>
@@ -140,7 +142,7 @@ Subscription administration information can be found at <link href="http://www.w
          </li>
  </ul>
  </section>
  <section>
  <section id="articles">
    <title>Tutorials/Articles</title>
    <ul>
          <li>
@@ -160,7 +162,7 @@ Subscription administration information can be found at <link href="http://www.w
          </li>
    </ul>
  </section>
  <section>
  <section id="products">
    <title>Related/Useful Products</title>
    <ul>
      <li>
@@ -196,7 +198,6 @@ printers.
      </li>
    </ul>
  </section>
 </section>
  </body>
 </document>