vmote 2003/04/05 11:29:26
Modified: src/documentation/content/xdocs bugs.xml gethelp.xml
resources.xml
Log:
Fix link to "Asking Questions ..."
Normalize and clean up content.
Revision Changes Path
1.5 +8 -28 xml-fop/src/documentation/content/xdocs/bugs.xml
Index: bugs.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/bugs.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- bugs.xml 15 Mar 2003 19:59:46 -0000 1.4
+++ bugs.xml 5 Apr 2003 19:29:26 -0000 1.5
@@ -30,40 +30,20 @@
<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>
-
1.4 +69 -63 xml-fop/src/documentation/content/xdocs/gethelp.xml
Index: gethelp.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/gethelp.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- gethelp.xml 14 Mar 2003 00:12:10 -0000 1.3
+++ gethelp.xml 5 Apr 2003 19:29:26 -0000 1.4
@@ -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&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&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>
-
1.8 +12 -11 xml-fop/src/documentation/content/xdocs/resources.xml
Index: resources.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/resources.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- resources.xml 17 Mar 2003 17:10:38 -0000 1.7
+++ resources.xml 5 Apr 2003 19:29:26 -0000 1.8
@@ -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 @@
</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 @@
</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 @@
</ul>
</section>
</section>
- <section>
+ <section id="specs">
<title>Specifications</title>
<ul>
<li>
@@ -140,7 +142,7 @@
</li>
</ul>
</section>
- <section>
+ <section id="articles">
<title>Tutorials/Articles</title>
<ul>
<li>
@@ -160,7 +162,7 @@
</li>
</ul>
</section>
- <section>
+ <section id="products">
<title>Related/Useful Products</title>
<ul>
<li>
@@ -196,7 +198,6 @@
</li>
</ul>
</section>
-</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
