From: William Victor Mote <vmote@apache.org>
Date: Sat, 5 Apr 2003 19:29:26 +0000 (+0000)
Subject: Fix link to "Asking Questions ..."
X-Git-Tag: Root_Temp_KnuthStylePageBreaking~1668
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=81d5469fd47ab83a50ee83c0279586e4df45469b;p=xmlgraphics-fop.git

Fix link to "Asking Questions ..."
Normalize  and clean up content.


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

diff --git a/src/documentation/content/xdocs/bugs.xml b/src/documentation/content/xdocs/bugs.xml
index 8effa92e4..767d94b7f 100644
--- 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>
-
diff --git a/src/documentation/content/xdocs/gethelp.xml b/src/documentation/content/xdocs/gethelp.xml
index 431aab99a..a3321475e 100644
--- 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>
-
diff --git a/src/documentation/content/xdocs/resources.xml b/src/documentation/content/xdocs/resources.xml
index 4fcc89435..ec2099eab 100644
--- 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>