forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r527010 [3/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_0...
Date Tue, 10 Apr 2007 03:48:57 GMT
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/bugzilla-patch/howto-bugzilla-patch.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/bugzilla-patch/howto-bugzilla-patch.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/bugzilla-patch/howto-bugzilla-patch.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/bugzilla-patch/howto-bugzilla-patch.xml Mon Apr  9 20:48:52 2007
@@ -16,366 +16,340 @@
   limitations under the License.
 -->
 <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "http://forrest.apache.org/dtd/howto-v10.dtd">
-
- 
 <howto>
   <header>
     <title>How to Contribute a Patch via Bugzilla</title>
     <abstract>
-Bugzilla is the Internet-based mechanism to facilitate contributions to any
-Apache project. This includes changes to code and documents
-(Patches), and also reports of flaws in the system (Bugs), and suggestions
-for enhancement.
-In this How-to we will concentrate on the Patch tracking capabilities of
-Bugzilla. We will explain how to create your Bugzilla account,
-how to enter a patch description, and finally how to attach the actual patch
-file.
+      Bugzilla is the Internet-based mechanism to facilitate contributions to
+      any Apache project. This includes changes to code and documents (Patches),
+      and also reports of flaws in the system (Bugs), and suggestions for
+      enhancement. In this How-to we will concentrate on the Patch tracking
+      capabilities of Bugzilla. We will explain how to create your Bugzilla
+      account, how to enter a patch description, and finally how to attach the
+      actual patch file.
     </abstract>
     <last-modified-content-date date="2002-05-25"/>
   </header>
-
   <audience title="Intended Audience">
-<p>
-This document is meant for first-time users of Bugzilla.
-The web interface can be daunting, so this concise explanation will help
-you to start. After your first patch submission, you can proceed to make more
-substantial contributions.
-</p> 
-
-<p> 
-As our example we use the contribution of a simple documentation patch for
-the Apache Cocoon project. The principles apply to any project.
-</p>
+    <p>
+      This document is meant for first-time users of Bugzilla. The web interface
+      can be daunting, so this concise explanation will help you to start. After
+      your first patch submission, you can proceed to make more substantial
+      contributions.
+    </p>
+    <p>
+      As our example we use the contribution of a simple documentation patch for
+      the Apache Cocoon project. The principles apply to any project.
+    </p>
   </audience>
-
   <prerequisites title="Prerequisites">
-<p>
-Bugzilla contributors should:
-</p>
-<ul>
-<li>Understand what a Patch is and how to make one.
+    <p>
+      Bugzilla contributors should:
+    </p>
+    <ul>
+      <li>Understand what a Patch is and how to make one.
 Note that a new complete document is still just a &quot;patch&quot;,
 though it does need separate treatment to a normal &quot;diff&quot;.
 </li>
-<li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
+      <li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
 distinguish between a Bug report, a Patch submission, and an Enhancement suggestion. They are all <em>&quot;Bugs&quot;</em> as far as Bugzilla is concerned.
 </li>
-</ul>
-
-</prerequisites>
-
+    </ul>
+  </prerequisites>
   <steps title="Steps">
-<p>
-Here is how to proceed. Go to
-<fork href="http://issues.apache.org/bugzilla/">Bugzilla</fork>
-in another browser window.
-</p>
-
-  <section>
-  <title>1. Create your Bugzilla Account</title>
-<p>
-Follow the link the home page to &quot;Open a new Bugzilla account&quot;.
-Do not worry, you will not be sent spam email nor bombarded with advertisements
-by setting up this account. It is purely a workgroup tool.
-</p>
-
-<p>
-Note that you can conduct queries in Bugzilla and review submissions without
-having an account. However, to make a contribution you must have an account.
-This ensures legitimacy. It also enables the system to send you
-email automatically when your patch is applied by a Cocoon committer.
-</p>
-  </section>
-
-  <section>
-  <title>2. Enter a new bug report</title>
-  
-<p>
-Follow the "Enter a new bug report" link from the Bugzilla home page. First,
-you will be asked to select the relevant project ... choose Cocoon 2 of course.
-Next, you will be asked to provide your account details. Following that, you
-will be presented an input form for the various details ...
-</p>
-
-<p><img src="my-images/bugzilla-screen.gif" alt="Bugzilla Screen" height="342" width="479" /></p>
-
-  <section>
-   <title>Specify Version</title>
-<p>
-This is the version of Cocoon that you prepared your patch against. Choose
-<code>Current CVS</code> if you have an up-to-date local working copy
-of HEAD branch or a very recent nightly build. Otherwise choose the relevant
-release version. This is a very important step, as you will confuse the
-committer if your changes do not match the repository. If you are unsure, then
-please say so in the description at step 12.
-</p>
-  </section>
-
-  <section>
-    <title>Specify Component</title>
-<p>
-Follow the &quot;Component&quot; link for description of the available
-components. If you do not know which component is relevant, then just use
-<code>core</code>.
-</p>
-  </section>
-
-  <section>
-    <title>Specify Platform</title>
-<p>
-This is really meant for bug reporting. Perhaps it could be relevant for a
-patch. You would usually specify the <code>All</code> option.
-</p>
-  </section>
-
-  <section>
-    <title>Specify Operating System (OS)</title>
-<p>
-Really meant for bug reporting. Perhaps it could be relevant for a patch.
-You would usually specify the <code>All</code> option.
-</p>
-  </section>
-
-  <section>
-    <title>Specify Severity</title>
-<p>
-The impact that would arise if your patch is not applied. For a documentation
-patch, the severity would usually be the default <code>Normal</code>.
-However, if it addressed some serious lack or fixed a misguided configuration
-statement, then the impact could be <code>major</code>.
-</p>
-<p>
+    <p>
+      Here is how to proceed. Go to
+      <fork href="http://issues.apache.org/bugzilla/">Bugzilla</fork> in another
+      browser window.
+    </p>
+    <section>
+      <title>1. Create your Bugzilla Account</title>
+      <p>
+        Follow the link the home page to &quot;Open a new Bugzilla
+        account&quot;. Do not worry, you will not be sent spam email nor
+        bombarded with advertisements by setting up this account. It is purely a
+        workgroup tool.
+      </p>
+      <p>
+        Note that you can conduct queries in Bugzilla and review submissions
+        without having an account. However, to make a contribution you must have
+        an account. This ensures legitimacy. It also enables the system to send
+        you email automatically when your patch is applied by a Cocoon
+        committer.
+      </p>
+    </section>
+    <section>
+      <title>2. Enter a new bug report</title>
+      <p>
+        Follow the "Enter a new bug report" link from the Bugzilla home page.
+        First, you will be asked to select the relevant project ... choose
+        Cocoon 2 of course. Next, you will be asked to provide your account
+        details. Following that, you will be presented an input form for the
+        various details ...
+      </p>
+      <p>
+        <img src="my-images/bugzilla-screen.gif" alt="Bugzilla Screen" height="342" width="479" />
+      </p>
+      <section>
+        <title>Specify Version</title>
+        <p>
+          This is the version of Cocoon that you prepared your patch against.
+          Choose <code>Current CVS</code> if you have an up-to-date local
+          working copy of HEAD branch or a very recent nightly build. Otherwise
+          choose the relevant release version. This is a very important step, as
+          you will confuse the committer if your changes do not match the
+          repository. If you are unsure, then please say so in the description
+          at step 12.
+        </p>
+      </section>
+      <section>
+        <title>Specify Component</title>
+        <p>
+          Follow the &quot;Component&quot; link for description of the available
+          components. If you do not know which component is relevant, then just
+          use <code>core</code>.
+        </p>
+      </section>
+      <section>
+        <title>Specify Platform</title>
+        <p>
+          This is really meant for bug reporting. Perhaps it could be relevant
+          for a patch. You would usually specify the <code>All</code> option.
+        </p>
+      </section>
+      <section>
+        <title>Specify Operating System (OS)</title>
+        <p>
+          Really meant for bug reporting. Perhaps it could be relevant for a
+          patch. You would usually specify the <code>All</code> option.
+        </p>
+      </section>
+      <section>
+        <title>Specify Severity</title>
+        <p>
+          The impact that would arise if your patch is not applied. For a
+          documentation patch, the severity would usually be the default
+          <code>Normal</code>. However, if it addressed some serious lack or
+          fixed a misguided configuration statement, then the impact could be
+          <code>major</code>.
+        </p>
+        <p>
 <!--FIXME: (DS) Why include this if it isn't recommended for a patch? -->
 <!--       (DC) To try to discourage them from using it. Does it need
 better words? -->
-(The <code>enhancement</code> option would not be used for a patch, as it is
-intended for suggesting something that should be done. Use this option wisely.
-It would be better to discuss it on the mailing list first.)
-</p>
-  </section>
-
-  <section>
-    <title>Specify Initial State</title>
-<p>
-Use the <code>New</code> option.
-</p>
-  </section>
-
-  <section>
-    <title>Specify Assigned To</title>
-<p>
-Leave it blank. Your patch will be automatically assigned to the
-<code>cocoon-dev</code> mailing list. When a committer takes on your patch,
-that committer will assign the bug to their own email address. This pevents
-duplication of effort by other committers.
-</p>
-<p>
-The Cc field can be used if you need the bug reports, and any follow-up, to be
-copied to some other person. Remember that your report will be sent
-automatically to the <code>cocoon-dev</code> mailing list, so you do not need
-to Cc anyone there.
-</p>
-  </section>
-
-  <section>
-    <title>Specify URL</title>
-<p>
-If the patch refers to a particular document, then provide the website URL.
-If it refers to an issue with one of the local Cocoon Samples, then provide
-the localhost URL.
-</p>
-  </section>
-
-  <section>
-    <title>Carefully choose the Summary</title>
-<p>
-The summary will become the all-important title of the bug. Use it wisely. You want
-to draw attention to your patch. Just as with posting email to the listervers,
-choosing a poor title may cause your posting to be easily overlooked.
-Use up all the characters available ... about 60 maximum.
-</p>
-<p>
-Start the Summary with the <code>[PATCH]</code> tag. This will ensure that it
-is included in the Cocoon automated patch queue summary posted to the mailing
-lists. The patch queue summary reminds people what patches are pending. If you
-omit this tag, then your patch may easily be overlooked.
-</p>
-  </section>
-
-  <section>
-   <title>Description</title>
-<p>
-Provide a brief explanation of what your patch does. Supply any instructions
-to help the committer apply your patch efficiently. Note any issues that may
-remain. It may help to list each file that you are submitting and briefly
-describe what it is. A committer will need to provide a descriptive log message
-when committing your work. Providing a clear description here will help them.
-</p>
-<p>
-Consider writing the Description and Summary text before you start entering
-your patch report. You could save it in a local text file beforehand and
-then copy-and-paste it when the time comes.
-</p>
-<p>
+          (The <code>enhancement</code> option would not be used for a patch, as
+          it is intended for suggesting something that should be done. Use this
+          option wisely. It would be better to discuss it on the mailing list
+          first.)
+        </p>
+      </section>
+      <section>
+        <title>Specify Initial State</title>
+        <p>
+          Use the <code>New</code> option.
+        </p>
+      </section>
+      <section>
+        <title>Specify Assigned To</title>
+        <p>
+          Leave it blank. Your patch will be automatically assigned to the
+          <code>cocoon-dev</code> mailing list. When a committer takes on your
+          patch, that committer will assign the bug to their own email address.
+          This pevents duplication of effort by other committers.
+        </p>
+        <p>
+          The Cc field can be used if you need the bug reports, and any
+          follow-up, to be copied to some other person. Remember that your
+          report will be sent automatically to the <code>cocoon-dev</code>
+          mailing list, so you do not need to Cc anyone there.
+        </p>
+      </section>
+      <section>
+        <title>Specify URL</title>
+        <p>
+          If the patch refers to a particular document, then provide the website
+          URL. If it refers to an issue with one of the local Cocoon Samples,
+          then provide the localhost URL.
+        </p>
+      </section>
+      <section>
+        <title>Carefully choose the Summary</title>
+        <p>
+          The summary will become the all-important title of the bug. Use it
+          wisely. You want to draw attention to your patch. Just as with posting
+          email to the listervers, choosing a poor title may cause your posting
+          to be easily overlooked. Use up all the characters available ... about
+          60 maximum.
+        </p>
+        <p>
+          Start the Summary with the <code>[PATCH]</code> tag. This will ensure
+          that it is included in the Cocoon automated patch queue summary posted
+          to the mailing lists. The patch queue summary reminds people what
+          patches are pending. If you omit this tag, then your patch may easily
+          be overlooked.
+        </p>
+      </section>
+      <section>
+        <title>Description</title>
+        <p>
+          Provide a brief explanation of what your patch does. Supply any
+          instructions to help the committer apply your patch efficiently. Note
+          any issues that may remain. It may help to list each file that you are
+          submitting and briefly describe what it is. A committer will need to
+          provide a descriptive log message when committing your work. Providing
+          a clear description here will help them.
+        </p>
+        <p>
+          Consider writing the Description and Summary text before you start
+          entering your patch report. You could save it in a local text file
+          beforehand and then copy-and-paste it when the time comes.
+        </p>
+        <p>
 <!--FIXME (DS): Do we need this? It's a patch, not a bug. It may be confusing. -->
-If this were a bug report, then it would need extensive description.
-</p>
-  </section>
-  
-  </section>
-  
-
-  <section>
-    <title>3. Send the patch report</title>
-<p>
-Review your options, then press the <strong>Commit</strong> button. This will
-add an entry to the bug database and email a report to the 
-<code>cocoon-dev</code> mailing list and a copy to you. Your submission will be
-assigned a unique Bug Number which you can use to review its progress.
-</p>
-<p>
-The next steps will show you how to attach your patch to the report that you
-have just created ...
-</p>
-  </section>
-
-  <section>
-    <title>4. Create an attachment of the actual patch</title>
-<p>
-You will be presented with a status screen saying that your bug report
-was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
-</p>
-
-<p>
-Now you have a choice ... proceed to review your bug report by selecting the
-link &quot;Back to Bug #XXXXX&quot;. If you forgot to mention something,
-then you can add more comments. From that screen, follow the link
-&quot;Create a new attachment&quot;.
-Otherwise follow the link from this status screen to &quot;Attach a file to
-this bug&quot;.
-</p>
-
-  <section>
-    <title>Specify the file to be uploaded</title>
-<p>
-Provide the local pathname to your patchfile, e.g.
-<code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
-</p>
-  </section>
-
-  <section>
-    <title>Describe the attachment</title>
-<p>
-Provide a concise one line description, e.g.
-<code>Gzipped TAR archive with new docs and diffs</code>
-</p>
-  </section>
-
-  <section>
-    <title>Specify the contentType of the attachment</title>
-<p>
-If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select
-&quot;<code>Binary file (application/octet-stream)</code>&quot;.
-If it is just a single xml document, then select
-&quot;<code>Plain text (text/plain)</code>&quot;.
-If the patch is just a single diff file, then select
-&quot;<code>Patch file (text/plain, diffs)</code>&quot;.
-</p>
-  </section>
-  
-  </section>
-
-  <section>
-    <title>5. Submit the attachment</title>
-<p>
-When you are ready, press the <strong>Submit</strong> button. As for Step 3,
-you will be presented with a status screen saying that your attachment
-was accepted and that email was sent to <code>cocoon-dev</code> mailing list.
-</p>
-  </section>
-
-  <section>
-    <title>6. Be patient</title>
-<p>
-Now your patch will wait inside Bugzilla until one of the Cocoon committers
-assigns the patch to their own email address and starts to process it to apply
-it to the master CVS repository. As the registered owner of the Bug, you will
-be sent an automatic email at each of these stages.
-</p>
-  </section>
-
-  <section>
-    <title>7. Add more description or attachments if necessary</title>
-<p>
-Until the patch is applied by the committer and the Bug report is closed, you
-can still add more to your bug report. However, only do this when
-absolutely necessary because the patch should not be
-changing while the committer is trying to commit it. If you just want to make
-further changes, then it would be better to wait until your patch is
-applied. Then you can make a new patch. Remember that the committer has full
-veto and may decide to make some slight modifications to your patch. So it
-is far better to wait.
-</p>
-  </section>
-
-  <section>
-    <title>8. Adding subsequent patches to the same document or program</title>
-<p>
-If you want to make more patches to the same file, then please open a new Bug
-rather than re-open the old one. After all, once the original patch is
-applied by the committer, its corresponding Bug report is closed.
-</p>
-  </section>
-
+          If this were a bug report, then it would need extensive description.
+        </p>
+      </section>
+    </section>
+    <section>
+      <title>3. Send the patch report</title>
+      <p>
+        Review your options, then press the <strong>Commit</strong> button. This
+        will add an entry to the bug database and email a report to the
+        <code>cocoon-dev</code> mailing list and a copy to you. Your submission
+        will be assigned a unique Bug Number which you can use to review its
+        progress.
+      </p>
+      <p>
+        The next steps will show you how to attach your patch to the report that
+        you have just created ...
+      </p>
+    </section>
+    <section>
+      <title>4. Create an attachment of the actual patch</title>
+      <p>
+        You will be presented with a status screen saying that your bug report
+        was accepted and that email was sent to <code>cocoon-dev</code> mailing
+        list.
+      </p>
+      <p>
+        Now you have a choice ... proceed to review your bug report by selecting
+        the link &quot;Back to Bug #XXXXX&quot;. If you forgot to mention
+        something, then you can add more comments. From that screen, follow the
+        link &quot;Create a new attachment&quot;. Otherwise follow the link from
+        this status screen to &quot;Attach a file to this bug&quot;.
+      </p>
+      <section>
+        <title>Specify the file to be uploaded</title>
+        <p>
+          Provide the local pathname to your patchfile, e.g.
+          <code>/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</code>
+        </p>
+      </section>
+      <section>
+        <title>Describe the attachment</title>
+        <p>
+          Provide a concise one line description, e.g. <code>Gzipped TAR archive
+          with new docs and diffs</code>
+        </p>
+      </section>
+      <section>
+        <title>Specify the contentType of the attachment</title>
+        <p>
+          If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then
+          select &quot;<code>Binary file
+          (application/octet-stream)</code>&quot;. If it is just a single xml
+          document, then select &quot;<code>Plain text
+          (text/plain)</code>&quot;. If the patch is just a single diff file,
+          then select &quot;<code>Patch file (text/plain, diffs)</code>&quot;.
+        </p>
+      </section>
+    </section>
+    <section>
+      <title>5. Submit the attachment</title>
+      <p>
+        When you are ready, press the <strong>Submit</strong> button. As for
+        Step 3, you will be presented with a status screen saying that your
+        attachment was accepted and that email was sent to
+        <code>cocoon-dev</code> mailing list.
+      </p>
+    </section>
+    <section>
+      <title>6. Be patient</title>
+      <p>
+        Now your patch will wait inside Bugzilla until one of the Cocoon
+        committers assigns the patch to their own email address and starts to
+        process it to apply it to the master CVS repository. As the registered
+        owner of the Bug, you will be sent an automatic email at each of these
+        stages.
+      </p>
+    </section>
+    <section>
+      <title>7. Add more description or attachments if necessary</title>
+      <p>
+        Until the patch is applied by the committer and the Bug report is
+        closed, you can still add more to your bug report. However, only do this
+        when absolutely necessary because the patch should not be changing while
+        the committer is trying to commit it. If you just want to make further
+        changes, then it would be better to wait until your patch is applied.
+        Then you can make a new patch. Remember that the committer has full veto
+        and may decide to make some slight modifications to your patch. So it is
+        far better to wait.
+      </p>
+    </section>
+    <section>
+      <title>8. Adding subsequent patches to the same document or program</title>
+      <p>
+        If you want to make more patches to the same file, then please open a
+        new Bug rather than re-open the old one. After all, once the original
+        patch is applied by the committer, its corresponding Bug report is
+        closed.
+      </p>
+    </section>
   </steps>
-
   <extension title="Real World Extension">
-  <!--FIXME: (DS) The purpose of this is to provide examples of how they can use
+<!--FIXME: (DS) The purpose of this is to provide examples of how they can use
                   the knowledge gained in this how-to -->
-<p>Contributing patches, in the form of documentation or code, is a vital way to give back to the Cocoon community. For example, you might consider contributing a timely patch in the form of a new FAQ, how-to, or tutorial. Or, you may also consider submitting a patch which updates Cocoon's existing user and developer guides. </p>
+    <p>
+      Contributing patches, in the form of documentation or code, is a vital way
+      to give back to the Cocoon community. For example, you might consider
+      contributing a timely patch in the form of a new FAQ, how-to, or tutorial.
+      Or, you may also consider submitting a patch which updates Cocoon's
+      existing user and developer guides.
+    </p>
   </extension>
-
   <tips title="Tips">
-
-  <section>
-    <title>Setting user preferences</title>
-<p>
-You can configure certain preferences, though the Bugzilla defaults work just
-fine.
-</p>
-  </section>
-
-  <section>
-    <title>Review the bugzilla documentation</title>
-<p>
-There are various explanations of terminology and procedures ... follow the
-links should you need to know more.
-</p>
-  </section>
-
-  <section>
-    <title>Search Bugzilla</title>
-<p>
-Bugzilla has a very powerful search interface. Now that you have a login
-account, Bugzilla can remember customized queries which you can run with a
-single click.
-</p>
-  </section>
-
+    <section>
+      <title>Setting user preferences</title>
+      <p>
+        You can configure certain preferences, though the Bugzilla defaults work
+        just fine.
+      </p>
+    </section>
+    <section>
+      <title>Review the bugzilla documentation</title>
+      <p>
+        There are various explanations of terminology and procedures ... follow
+        the links should you need to know more.
+      </p>
+    </section>
+    <section>
+      <title>Search Bugzilla</title>
+      <p>
+        Bugzilla has a very powerful search interface. Now that you have a login
+        account, Bugzilla can remember customized queries which you can run with
+        a single click.
+      </p>
+    </section>
   </tips>
-
   <references title="References">
-  <ul>
-<li>
+    <ul>
+      <li>
 Bugzilla is at 
-<link href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</link>
-</li>
-<li>
+<link href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</link></li>
+      <li>
 Helpful Bug Writing Guidelines are available directly from the
 Bug entry interface.
 </li>
-  </ul>
-  
+    </ul>
   </references>
-
 </howto>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/book.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/book.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/book.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/book.xml Mon Apr  9 20:48:52 2007
@@ -16,17 +16,14 @@
   limitations under the License.
 -->
 <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "http://forrest.apache.org/dtd/book-cocoon-v10.dtd">
-
 <book software="Forrest"
   title="Forrest"
   copyright="2003 The Apache Software Foundation"
   xmlns:xlink="http://www.w3.org/1999/xlink">
-
   <menu label="How-To Samples">
     <menu-item label="Overview" href="site:v0.70//howto/overview"/>
   </menu>
   <menu label="Committers">
     <menu-item label="CVS through SSH" href="howto-cvs-ssh.html"/>
   </menu>
-
 </book>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/howto-cvs-ssh.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/howto-cvs-ssh.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/howto-cvs-ssh.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/cvs-ssh/howto-cvs-ssh.xml Mon Apr  9 20:48:52 2007
@@ -17,69 +17,96 @@
 -->
 <!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.0//EN" "http://forrest.apache.org/dtd/howto-v10.dtd">
 <howto>
-    <header>
-        <title>CVS through SSH</title>
-        <version>1.0</version>
-        <abstract>This How-To describes the steps necessary to configure an SSH enabled CVS connection. It is recommended to configure an SSH enabled CVS connection to work with Apache code repositories.</abstract>
-        <last-modified-content-date date="2002-05-27"/>
-    </header>
-    <audience title="Intended audience">
-        <p>This How-to is aimed at developers who have been granted committer access to CVS repositories for particular projects.</p>
-    </audience>
-    <purpose title="Purpose">
-        <p> 
-              Using SSH to access CVS repositories is recommended for security reasons. By configuring CVS to work with remote repository using private/public SSH keys you'll be able to run CVS commands without a need to enter your password every time you need access to CVS through SSH.
-        </p>
-    </purpose>
-    <prerequisites title="Prerequisites">
-        <ul>
-            <li>Account on the local machine.</li>
-            <li>Commiter access to the project(s). <em>This also imply having account on the CVS host machine.</em></li>        
-            <li>Cygwin - a Unix environment for Windows systems. You can get it <link href="http://www.redhat.com/software/tools/cygwin/">here</link>. <em>Not required for Linux/*nix users.</em></li>
-            <li>A CVS GUI application (for Windows users only), e.g. WinCVS. <em>It is not required, but can be very useful.</em></li>
-        </ul>
-        <note>If you are behind a firewall check that you can communicate through the 22 port. For anonymous access you will need 2401 one.</note>
-    </prerequisites>
-    <steps title="Steps">
-        <p>How to proceed.</p>
-        <section>
-            <title>Terms</title>
-            <dl>
+  <header>
+    <title>CVS through SSH</title>
+    <version>1.0</version>
+    <abstract>
+      This How-To describes the steps necessary to configure an SSH enabled CVS
+      connection. It is recommended to configure an SSH enabled CVS connection
+      to work with Apache code repositories.
+    </abstract>
+    <last-modified-content-date date="2002-05-27"/>
+  </header>
+  <audience title="Intended audience">
+    <p>
+      This How-to is aimed at developers who have been granted committer access
+      to CVS repositories for particular projects.
+    </p>
+  </audience>
+  <purpose title="Purpose">
+    <p>
+      Using SSH to access CVS repositories is recommended for security reasons.
+      By configuring CVS to work with remote repository using private/public SSH
+      keys you'll be able to run CVS commands without a need to enter your
+      password every time you need access to CVS through SSH.
+    </p>
+  </purpose>
+  <prerequisites title="Prerequisites">
+    <ul>
+      <li>Account on the local machine.</li>
+      <li>Commiter access to the project(s). <em>This also imply having account on the CVS host machine.</em></li>
+      <li>Cygwin - a Unix environment for Windows systems. You can get it <link href="http://www.redhat.com/software/tools/cygwin/">here</link>. <em>Not required for Linux/*nix users.</em></li>
+      <li>A CVS GUI application (for Windows users only), e.g. WinCVS. <em>It is not required, but can be very useful.</em></li>
+    </ul>
+    <note>
+      If you are behind a firewall check that you can communicate through the 22
+      port. For anonymous access you will need 2401 one.
+    </note>
+  </prerequisites>
+  <steps title="Steps">
+    <p>
+      How to proceed.
+    </p>
+    <section>
+      <title>Terms</title>
+      <dl>
         <dt>SSH</dt>
         <dd>Secure Shell. See <link href="http://www.openssh.org">OpenSSH</link></dd>
         <dt>CVS</dt>
         <dd>Concurrent Version System See <link href="http://www.cvshome.org" >CVS Home Page</link></dd>
-         </dl>                    
-        </section>
-        <note><strong>$</strong> represents local, <strong>%</strong> remote machine.</note>                
-        <section>
-            <title>Setting up domain users</title>
-            <note>This step is necessary only for Windows users. Linux users can happily skip this section and pass to <link href="#ssh_access">Setting up SSH access</link> section</note>
-            <p>If you are a domain user then you should be added to Cygwin users list (See <code>[cygwin-dir]/etc/passwd</code>). 
-            </p>
-            <ul>
-              <li>Start Cygwin, then enter following commands:</li>
-            </ul>
-            <source>
+      </dl>
+    </section>
+    <note>
+      <strong>$</strong> represents local, <strong>%</strong> remote machine.
+    </note>
+    <section>
+      <title>Setting up domain users</title>
+      <note>
+        This step is necessary only for Windows users. Linux users can happily
+        skip this section and pass to <link href="#ssh_access">Setting up SSH
+        access</link> section
+      </note>
+      <p>
+        If you are a domain user then you should be added to Cygwin users list
+        (See <code>[cygwin-dir]/etc/passwd</code>).
+      </p>
+      <ul>
+        <li>Start Cygwin, then enter following commands:</li>
+      </ul>
+      <source>
 $ whoami
 administrator
 $ mkgroup -d > /etc/group
 $ mkpasswd -d | grep 'userxxx' >> /etc/passwd
 $ exit
     </source>
-       <note>Replace 'userxxx' by your account name</note>    
-    <ul>
-      <li>Start Cygwin/shell again and check that everything's Ok:</li>
-    </ul>
-    <source>
+      <note>
+        Replace 'userxxx' by your account name
+      </note>
+      <ul>
+        <li>Start Cygwin/shell again and check that everything's Ok:</li>
+      </ul>
+      <source>
 $ whoami
 userxxx
             </source>
-        </section>
-        <section id="ssh_access">
-            <title>Setting up SSH access</title>
-            <p>Start Cygwin/shell, then enter:</p>
-            <source>
+    </section>
+    <section id="ssh_access">
+      <title>Setting up SSH access</title>
+      <p>
+        Start Cygwin/shell, then enter:
+      </p>
+      <source>
 $ ssh-user-config
   Shall I create an SSH1 RSA identity file for you? (yes/no) no
   Shall I create an SSH2 RSA identity file for you? (yes/no)  (yes/no) no
@@ -92,15 +119,22 @@
   
   Configuration finished. Have fun!
     </source>
-    <p>
-      Now you have configured SSH on your machine. Next you have to setup access to the CVS machine.
-    </p>
-    <warning>Having an empty passphrase isn't recommended for security reasons. See <code>ssh-agent</code> documentation on how to configure automatic passphrase retaining.</warning>
-        </section>
-        <section>
-            <title>Setting up passphrase access</title>
-            <p>Perform the following:</p>
-            <source>
+      <p>
+        Now you have configured SSH on your machine. Next you have to setup
+        access to the CVS machine.
+      </p>
+      <warning>
+        Having an empty passphrase isn't recommended for security reasons. See
+        <code>ssh-agent</code> documentation on how to configure automatic
+        passphrase retaining.
+      </warning>
+    </section>
+    <section>
+      <title>Setting up passphrase access</title>
+      <p>
+        Perform the following:
+      </p>
+      <source>
 $ scp ~/.ssh/id_dsa.pub userxxx@cvs.apache.org:.
 $ ssh -l userxxx -L 2401:localhost:2401 cvs.apache.org
 % mkdir ~/.ssh
@@ -110,57 +144,69 @@
 % chmod 600 ~/.ssh/*
 % exit            
             </source>
-            <note>Note, that the account name on CVS machine can differ from your local account name.</note>
-            <p>
-            Check that your configuration is correct:
-            </p>
-            <source>
+      <note>
+        Note, that the account name on CVS machine can differ from your local
+        account name.
+      </note>
+      <p>
+        Check that your configuration is correct:
+      </p>
+      <source>
 $ ssh userxxx@cvs.apache.org
             </source>
-            <note>If this command doesn't work then it can mean that you have an old version of SSH. In this case try <code>ssh -l userxxx cvs.apache.org</code>. Run <code>ssh --help</code> to get all available options.</note>
-            <p>
-            If now you are logged in to the to the CVS machine without entering the password then everything's Ok.
-            </p>           
-        </section>
-        <section>
-            <title>Getting the project from CVS</title>
-            <p>Now you are ready to get a project from CVS using SSH connection.</p>
-            <p>E.g. how it is done using Cygwin/shell</p>
-            <source>
+      <note>
+        If this command doesn't work then it can mean that you have an old
+        version of SSH. In this case try <code>ssh -l userxxx
+        cvs.apache.org</code>. Run <code>ssh --help</code> to get all available
+        options.
+      </note>
+      <p>
+        If now you are logged in to the to the CVS machine without entering the
+        password then everything's Ok.
+      </p>
+    </section>
+    <section>
+      <title>Getting the project from CVS</title>
+      <p>
+        Now you are ready to get a project from CVS using SSH connection.
+      </p>
+      <p>
+        E.g. how it is done using Cygwin/shell
+      </p>
+      <source>
 $ export CVS_RSH=/bin/ssh
 $ cvs -d :ext:userxxx@cvs.apache.org:/home/cvs co xml-cocoon2            
             </source>
-        </section>
-        <section>
-            <title>How to setup WinCVS</title>
-            <ul>
-                <li>Add ssh.exe directory to your system PATH environment variable. Say: <br/>
-                <code>C:\>set PATH=%PATH%;C:\cygwin\bin</code></li>
-                <li>Add <code>CVS_RSH=ssh</code> environment variable</li>
-            </ul>
-            <p>
-            Start WinCVS, then:
-            </p>
-            <ul>
-                <li>From the main menu select <strong>Admin</strong></li>
-                <li>Then select <strong>Preferences</strong></li>
-                <li>In the dialog that comes up: <br/>
+    </section>
+    <section>
+      <title>How to setup WinCVS</title>
+      <ul>
+        <li>Add ssh.exe directory to your system PATH environment variable. Say: <br/><code>C:\>set PATH=%PATH%;C:\cygwin\bin</code></li>
+        <li>Add <code>CVS_RSH=ssh</code> environment variable</li>
+      </ul>
+      <p>
+        Start WinCVS, then:
+      </p>
+      <ul>
+        <li>From the main menu select <strong>Admin</strong></li>
+        <li>Then select <strong>Preferences</strong></li>
+        <li>In the dialog that comes up: <br/>
                 Set the CVSROOT to <code>userxxx@cvs.apache.org:/home/cvs</code></li>
-                <li>Set the Authentication to SSH Server</li>                
-                <li>Click Ok</li>
-            </ul>
-        </section>
-        <section>
-            <title>References</title>
-            <p>
-                You can find more on CVS, SSH and WinCVS here:
-            </p>
-            <ul>
-                <li><link href="http://www.cvshome.org">CVS Home Page</link></li>            
-                <li><link href="http://www.openssh.org">OpenSSH</link></li>            
-                <li><link href="http://www.redhat.com/software/tools/cygwin/">Cygwin Home Page</link></li>            
-                <li><link href="http://odin.himinbi.org/wincvs-over-ssh/">WinCVS over SSH</link></li>
-            </ul>
-        </section>
-    </steps>
+        <li>Set the Authentication to SSH Server</li>
+        <li>Click Ok</li>
+      </ul>
+    </section>
+    <section>
+      <title>References</title>
+      <p>
+        You can find more on CVS, SSH and WinCVS here:
+      </p>
+      <ul>
+        <li><link href="http://www.cvshome.org">CVS Home Page</link></li>
+        <li><link href="http://www.openssh.org">OpenSSH</link></li>
+        <li><link href="http://www.redhat.com/software/tools/cygwin/">Cygwin Home Page</link></li>
+        <li><link href="http://odin.himinbi.org/wincvs-over-ssh/">WinCVS over SSH</link></li>
+      </ul>
+    </section>
+  </steps>
 </howto>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/forrest.xmap.html
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/forrest.xmap.html?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/forrest.xmap.html (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/forrest.xmap.html Mon Apr  9 20:48:52 2007
@@ -15,12 +15,13 @@
   limitations under the License.
 -->
 <html>
-<head>
-<title>Annotated forrest.xmap</title>
-</head>
-<body>
-<h1>sitemap.xmap</h1>
-<pre><![CDATA[
+  <head>
+    <title>Annotated forrest.xmap</title>
+  </head>
+  <body>
+    <h1>sitemap.xmap</h1>
+    <pre>
+<![CDATA[
 <?xml version="1.0"?>
 <!-- ===============================================
 Pipelines defining all Source XML types Forrest can handle.
@@ -238,10 +239,11 @@
         </map:select>
       </map:act>
     </map:resource>
-]]></pre>
-
+]]>
+    </pre>
     <h2>Definition of File-Resolver-Resource</h2>
-<pre><![CDATA[
+    <pre>
+<![CDATA[
     <map:resource name="file-resolver">
       <map:select type="exists">
         <map:when test="{project:content.xdocs}{uri}.ihtml">
@@ -306,10 +308,11 @@
       <!-- ============================================================ -->
       <!-- SOURCE FORMATS                                               -->
       <!-- ============================================================ -->
-]]></pre>
-
-      <h2>Second Match for '**.xml'</h2>
-<pre><![CDATA[
+]]>
+    </pre>
+    <h2>Second Match for '**.xml'</h2>
+    <pre>
+<![CDATA[
       <map:match pattern="**.xml">
         <map:select type="config">
           <map:parameter name="value" value="{defaults:i18n}"/>
@@ -331,6 +334,7 @@
     </map:pipeline>
   </map:pipelines>
 </map:sitemap>
-]]></pre>
-</body>
+]]>
+    </pre>
+  </body>
 </html>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-asf-mirror.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-asf-mirror.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-asf-mirror.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-asf-mirror.xml Mon Apr  9 20:48:52 2007
@@ -20,15 +20,13 @@
 <howto>
   <header>
     <title>Generate an ASF mirrors page using interactive web form</title>
-
-    <abstract>Include html form elements
-    into a forrest-generated html page. For example, this enables building
-    automated download mirror pages for ASF project websites.
+    <abstract>
+      Include html form elements into a forrest-generated html page. For
+      example, this enables building automated download mirror pages for ASF
+      project websites.
     </abstract>
-
     <last-modified-content-date date="2005-04-20" />
   </header>
-
   <audience title="Intended Audience">
     <ul>
       <li>Any Apache project that uses Forrest to generate their website
@@ -36,28 +34,26 @@
       <li>Also anyone interested in the use of embedding html form
         elements into a generated Forrest page.</li>
     </ul>
-<warning>
-Due to issue
-<link href="http://issues.apache.org/jira/browse/FOR-555">FOR-555</link>
-the html comments that the CGI script depends upon are stripped before
-the output stage. You need to manually add those comments.
-This is fixed in forrest_07_branch of SVN.
-</warning>
+    <warning>
+      Due to issue
+      <link href="http://issues.apache.org/jira/browse/FOR-555">FOR-555</link>
+      the html comments that the CGI script depends upon are stripped before the
+      output stage. You need to manually add those comments. This is fixed in
+      forrest_07_branch of SVN.
+    </warning>
   </audience>
-
   <purpose title="Purpose">
-    <p>All Apache projects use dynamically generated download pages
-    which determine the closest mirror and provide an interactive list of
-    the current alternative mirrors.
-    This HowTo describes the procedure to generate the template page
-    that is utilised by the mirrors.cgi script.
+    <p>
+      All Apache projects use dynamically generated download pages which
+      determine the closest mirror and provide an interactive list of the
+      current alternative mirrors. This HowTo describes the procedure to
+      generate the template page that is utilised by the mirrors.cgi script.
     </p>
-    <p>The mirrors.cgi and mirrors.html are "extra" documents,
-    i.e. have no links from anywhere in the site. So we explain
-    how to process additional files.
+    <p>
+      The mirrors.cgi and mirrors.html are "extra" documents, i.e. have no links
+      from anywhere in the site. So we explain how to process additional files.
     </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
     <ul>
       <li>Followed the documentation about
@@ -70,60 +66,65 @@
       <li>Already building your project website with Forrest.</li>
     </ul>
   </prerequisites>
-
   <steps title="Steps">
     <section id="cgi">
       <title>Add the mirrors.cgi as a raw file</title>
-      <p>As explained in the mirrors document, there will be a two-line CGI
-      wrapper script at the top-level of your website called
-      <code>mirrors.cgi</code></p>
-      <p>Utilising the Forrest concept of raw un-processed content,
-       add the file as <code>src/documentation/mirrors.cgi</code>
-       (copy the Forrest project's
+      <p>
+        As explained in the mirrors document, there will be a two-line CGI
+        wrapper script at the top-level of your website called
+        <code>mirrors.cgi</code>
+      </p>
+      <p>
+        Utilising the Forrest concept of raw un-processed content, add the file
+        as <code>src/documentation/mirrors.cgi</code> (copy the Forrest
+        project's
         <link href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/mirrors.cgi">mirrors.cgi</link>)
       </p>
     </section>
-
     <section id="html">
       <title>Add the mirrors.html to xdocs directory</title>
-      <p>This file contains the html content of your mirror page, including
-        the html form elements which drive the mirror selection. It also
-        contains the specific tokens that are interpreted by the mirrors.cgi
-        script to add the list of mirrors and select the closest.
+      <p>
+        This file contains the html content of your mirror page, including the
+        html form elements which drive the mirror selection. It also contains
+        the specific tokens that are interpreted by the mirrors.cgi script to
+        add the list of mirrors and select the closest.
       </p>
       <p>
-        Add the file as <code>src/documentation/xdocs/mirrors.html</code>
-        (Use the Forrest project's
+        Add the file as <code>src/documentation/xdocs/mirrors.html</code> (Use
+        the Forrest project's
         <link href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/mirrors.html">mirrors.html</link>
         as a template and edit it to suit.)
       </p>
       <p>
-        Note that the special tokens (e.g. [if-any http] [for http]) need to
-        be encompassed by xml comments.
+        Note that the special tokens (e.g. [if-any http] [for http]) need to be
+        encompassed by xml comments.
       </p>
     </section>
-
     <section id="menu">
       <title>Add a menu entry for Download</title>
-      <p>Add an entry to your site.xml navigation. For example ...
+      <p>
+        Add an entry to your site.xml navigation. For example ...
       </p>
-      <source><![CDATA[
+      <source>
+<![CDATA[
  <about label="About">
   <index label="Index" href="index.html"/>
   <license label="License" href="license.html"/>
   <download label="Download" href="http://forrest.apache.org/mirrors.cgi"/>
   <download_html href="mirrors.html"/><!-- so the page is part of a tab -->
-  ...]]></source>
+  ...]]>
+      </source>
     </section>
-
     <section id="link">
       <title>Cause the mirrors.html to be processed as an extra file</title>
-      <p>Forrest gathers the links that are to be crawled, by reading site.xml
-        and by finding any other internal links in the actual documents.
-        There is no link to mirrors.html because it is an extra file that needs
-        to be generated and skinned, but not linked in any way.
+      <p>
+        Forrest gathers the links that are to be crawled, by reading site.xml
+        and by finding any other internal links in the actual documents. There
+        is no link to mirrors.html because it is an extra file that needs to be
+        generated and skinned, but not linked in any way.
       </p>
-      <p>The Cocoon command-line interface
+      <p>
+        The Cocoon command-line interface
         (<link href="http://cocoon.apache.org/2.1/userdocs/offline/">CLI</link>)
         to the rescue. Add an entry to your project's cli.xconf by copying the
         default one from
@@ -131,12 +132,13 @@
         <code>src/documentation/conf/</code> directory (or wherever
         ${forrest.conf-dir} points). Add the following entry ...
       </p>
-      <source><![CDATA[
+      <source>
+<![CDATA[
 <uris name="mirrors" follow-links="false">
   <uri type="append" src="mirrors.html"/>
-</uris>]]></source>
+</uris>]]>
+      </source>
     </section>
-
     <section id="forrest">
       <title>Run 'forrest' to build your site</title>
       <p>
@@ -144,12 +146,12 @@
         there. Run the '<code>forrest</code>' command. The mirrors.html page
         will be generated with the skin applied.
       </p>
-<note>
-Due to Issue
-<link href="http://issues.apache.org/jira/browse/FOR-480">FOR-480</link>,
-the generated mirror.html will end up in forrest/main/site/mirrors.html
-rather than in the project's build directory.
-</note>
+      <note>
+        Due to Issue
+        <link href="http://issues.apache.org/jira/browse/FOR-480">FOR-480</link>,
+        the generated mirror.html will end up in forrest/main/site/mirrors.html
+        rather than in the project's build directory.
+      </note>
     </section>
   </steps>
 </howto>

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-buildPlugin.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-buildPlugin.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-buildPlugin.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-buildPlugin.xml Mon Apr  9 20:48:52 2007
@@ -19,344 +19,372 @@
 <howto>
   <header>
     <title>How to Build a Plugin</title>
-
     <version>0.1</version>
-
-    <abstract>This How-To describes the steps necessary to build a plugin for 
-    Forrest. Forrest uses plugins to add new input formats, output formats
-    and to change its default behaviour. Since plugins are downloaded when
-    needed and can be hosted at any location, plugin code can be developed 
-    independently of Apache Forrest. This how-to describes each of the major
-    steps in creating a plugin and then works through some examples of 
-    plugin creation in order to illustrate the materials.</abstract>
-
+    <abstract>
+      This How-To describes the steps necessary to build a plugin for Forrest.
+      Forrest uses plugins to add new input formats, output formats and to
+      change its default behaviour. Since plugins are downloaded when needed and
+      can be hosted at any location, plugin code can be developed independently
+      of Apache Forrest. This how-to describes each of the major steps in
+      creating a plugin and then works through some examples of plugin creation
+      in order to illustrate the materials.
+    </abstract>
     <last-modified-content-date date="2005-04-12" />
   </header>
-
   <audience title="Intended Audience">
-    <p>Users needing to add additional input formats or output formats or
-    to change the operation of the Forrest internals.</p>
-    
-    <warning>The Plugin Infrastructure is still at an early stage of design 
-    and implementation, consequently this How-To <em>may</em> be out of date
-    and/or incomplete. If you are having problems with any of the steps 
-    described, please ask for help on the developers mailing list (and then
-    provide patches for this document).</warning>
-    <warning>Please make sure that you are using forrest 0.7 if you want use 
-    plugins. Forrest 0.6 will not work!!!</warning>
+    <p>
+      Users needing to add additional input formats or output formats or to
+      change the operation of the Forrest internals.
+    </p>
+    <warning>
+      The Plugin Infrastructure is still at an early stage of design and
+      implementation, consequently this How-To <em>may</em> be out of date
+      and/or incomplete. If you are having problems with any of the steps
+      described, please ask for help on the developers mailing list (and then
+      provide patches for this document).
+    </warning>
+    <warning>
+      Please make sure that you are using forrest 0.7 if you want use plugins.
+      Forrest 0.6 will not work!!!
+    </warning>
   </audience>
-
   <purpose title="Purpose">
-    <p>This How-To will illustrate how to build a plugin, publish a plugin
-    and configure a Forrest project to use their plugin.</p>
+    <p>
+      This How-To will illustrate how to build a plugin, publish a plugin and
+      configure a Forrest project to use their plugin.
+    </p>
   </purpose>
-
   <prerequisites title="Prerequisites">
-    <p>Plugin developers should have:</p>
-    
+    <p>
+      Plugin developers should have:
+    </p>
     <ul>
       <li>a basic knowledge of XML, XSLT and Cocoon pipelines</li>
       <li>a clear use-case for extending Forrest</li>
       <li>read
-        <a href="site:plugins/infrastructure">Plugin Infrastructure</a>
-      </li>
+        <a href="site:plugins/infrastructure">Plugin Infrastructure</a></li>
       <li>verified with the Apache Forrest developer community that the
       requried functionality does not already exist</li>
     </ul>
   </prerequisites>
-
   <steps title="Steps">
-    <p>Here is how to proceed.</p>
-
+    <p>
+      Here is how to proceed.
+    </p>
     <section id="typeOfPlugin">
       <title>Type of Plugin</title>
-
-      <p>There are three types of plugin, each with a clear purpose, you
-      must first decide which 
-      <a href="site:plugins/infrastructure">type of plugin</a>
-      you need to build.</p>
-      
+      <p>
+        There are three types of plugin, each with a clear purpose, you must
+        first decide which <a href="site:plugins/infrastructure">type of
+        plugin</a> you need to build.
+      </p>
     </section>
-    
     <section id="ant">
       <title>Make ant available on the command-line</title>
       <p>
         The following instructions rely heavily on
-        <a href="http://ant.apache.org/">Apache Ant</a>
-        to automate some steps in the process. Since ant
-        is distributed as part of Forrest, all you need to do
-        is add the ant executable directory to your system path. The
-        name of this directory is <code>tools/ant/bin</code>
-        in your Forrest program directory.
-        (Alternatively you can prefix all calls to ant in
-        the following instructions with the full path of the ant binary directory.)
+        <a href="http://ant.apache.org/">Apache Ant</a> to automate some steps
+        in the process. Since ant is distributed as part of Forrest, all you
+        need to do is add the ant executable directory to your system path. The
+        name of this directory is <code>tools/ant/bin</code> in your Forrest
+        program directory. (Alternatively you can prefix all calls to ant in the
+        following instructions with the full path of the ant binary directory.)
         Also clear the ANT_HOME environment variable.
       </p>
       <p>
-        If instead you really want to use your own version of Ant,
-        then you will need to copy
-        forrest/lib/core/xml-commons-resolver.jar
-        to $ANT_HOME/lib directory, otherwise your plugins will go across
-        the network to get the DTDs on every parse.
+        If instead you really want to use your own version of Ant, then you will
+        need to copy forrest/lib/core/xml-commons-resolver.jar to $ANT_HOME/lib
+        directory, otherwise your plugins will go across the network to get the
+        DTDs on every parse.
       </p>
     </section>
-
     <section id="seed">
       <title>Seed a New Plugin</title>
-      <p>Regardless of the type of plugin you are building, the directory
-      structure is almost identical, as are most of the requried
-      configuration files. In this How-To we will assume that you are creating a 
-      plugin in the Forrest source tree. All plugins are developed in the
-      <code>forrest/plugins</code> directory.</p>
-      
-      <p class="instruction">Run the following set of commands:</p>
-      
+      <p>
+        Regardless of the type of plugin you are building, the directory
+        structure is almost identical, as are most of the requried configuration
+        files. In this How-To we will assume that you are creating a plugin in
+        the Forrest source tree. All plugins are developed in the
+        <code>forrest/plugins</code> directory.
+      </p>
+      <p class="instruction">
+        Run the following set of commands:
+      </p>
       <source>
       cd [path_to_forrest]/plugins
       ant seedPlugin
-      </source>      
-      
-      <p>The above ant target will ask you the name of the plugin and will
-      build a minimal plugin directory structure and configuration. You will 
-      need to customise these files to build your plugin.</p>
-      
-      <note>Although you can name your project anything you like we do have 
-      some <a href="site:plugins/infrastructure">naming 
-      conventions</a> that we recommend you follow. Plugins intended to be
-      held at forrest.apache.org must follow the naming convention.</note> 
-      
-      <note>If you plan on building your plugin elsewhere you can copy the
-      <code>build.xml</code> build file to your own plugin work directory and 
-      use it there.</note>
-      
-      <p>See 
-      <a href="site:plugins/infrastructure">Plugin
-      Infrastructure</a> for more information about the plugin
-      directory structure and configuration files.</p>
-    
+      </source>
+      <p>
+        The above ant target will ask you the name of the plugin and will build
+        a minimal plugin directory structure and configuration. You will need to
+        customise these files to build your plugin.
+      </p>
+      <note>
+        Although you can name your project anything you like we do have some
+        <a href="site:plugins/infrastructure">naming conventions</a> that we
+        recommend you follow. Plugins intended to be held at forrest.apache.org
+        must follow the naming convention.
+      </note>
+      <note>
+        If you plan on building your plugin elsewhere you can copy the
+        <code>build.xml</code> build file to your own plugin work directory and
+        use it there.
+      </note>
+      <p>
+        See <a href="site:plugins/infrastructure">Plugin Infrastructure</a> for
+        more information about the plugin directory structure and configuration
+        files.
+      </p>
       <section id="edit-template">
         <title>Edit the Plugin Template</title>
-        <p>You now have a skeleton plugin project. However, it doesn't do 
-        anything useful yet. Now is a good time to edit some of the files
-        provided.</p>
-
+        <p>
+          You now have a skeleton plugin project. However, it doesn't do
+          anything useful yet. Now is a good time to edit some of the files
+          provided.
+        </p>
         <note>
-          For plugins intended to be held at forrest.apache.org please
-          adjust the skinconf.xml etc to be in accordance with the other
-          forrest plugins. See <a href="#hosted">notes</a> below.
+          For plugins intended to be held at forrest.apache.org please adjust
+          the skinconf.xml etc to be in accordance with the other forrest
+          plugins. See <a href="#hosted">notes</a> below.
         </note>
-
-        <p>Here are some general notes:</p>
-        
+        <p>
+          Here are some general notes:
+        </p>
         <section id="status">
           <title>status.xml</title>
-          <p>This file is used to track changes to the plugin
-          project and to manage lists of things that still need to be done.
-          At this stage you should correct the <code>person</code> entry
-          near the top of the file. It is also a good idea to add a few key
-          milestones in the task list towards the bottom of the file.</p>
-          
-          <p>As you work on the plugin you should record all major changes in
-          this file so that it can then be used as a changelog for your
-          plugin.</p>
+          <p>
+            This file is used to track changes to the plugin project and to
+            manage lists of things that still need to be done. At this stage you
+            should correct the <code>person</code> entry near the top of the
+            file. It is also a good idea to add a few key milestones in the task
+            list towards the bottom of the file.
+          </p>
+          <p>
+            As you work on the plugin you should record all major changes in
+            this file so that it can then be used as a changelog for your
+            plugin.
+          </p>
         </section>
-        
         <section id="forrest-properties">
           <title>forrest.properties</title>
-          
-          <p>This file defines many configuration parameters for Forrest. It
-          does not need to be customised in most cases. However, see
-          for more details.</p>
+          <p>
+            This file defines many configuration parameters for Forrest. It does
+            not need to be customised in most cases. However, see for more
+            details.
+          </p>
         </section>
-        
         <section id="skinconf">
           <title>src/documentation/skinconf.xml</title>
-          <p>This configures the skin for your plugins documentation. There
-          are some items that need to be configured in here, for example, the
-          copyright information. The file is heavily commented so probably
-          best to read through it, changing what you need to.</p>
+          <p>
+            This configures the skin for your plugins documentation. There are
+            some items that need to be configured in here, for example, the
+            copyright information. The file is heavily commented so probably
+            best to read through it, changing what you need to.
+          </p>
         </section>
-        
         <section id="doc">
           <title>Documentation</title>
-          <p>It is also a good idea to start writing the documentation at this
-          stage. The above process created a very simple plugin documentation
-          site for you. All you have to do is add the content.</p>
+          <p>
+            It is also a good idea to start writing the documentation at this
+            stage. The above process created a very simple plugin documentation
+            site for you. All you have to do is add the content.
+          </p>
         </section>
-        
         <section id="hosted">
           <title>Style notes for plugins hosted at forrest.apapche.org</title>
           <p>
-            After seeding a new plugin, copy the configuration from an
-            exisiting plugin (e.g. org.apache.forrest.plugin.input.projectInfo).
-            Copy src/documentation/skinconf.xml and 
+            After seeding a new plugin, copy the configuration from an exisiting
+            plugin (e.g. org.apache.forrest.plugin.input.projectInfo). Copy
+            src/documentation/skinconf.xml and
             src/documentation/content/xdocs/images/project-logo.gif
           </p>
         </section>
       </section>
     </section>
-    
     <section id="edit-sitemap">
       <title>Edit the Plugin sitemap file(s)</title>
-      <p>The plugin <code>xmap</code> file is a Cocoon sitemap that is mounted
-      at a strategic place in the Forrest pipeline. It is in this file
-      that you will instruct Forrest how to operate. An input plugin
-      must provide a <code>input.xmap</code> file, an output plugin
-      must provide a <code>output.xmap</code> file, whilst an internal
-      plugin provides a <code>internal.xmap</code> file. In addition, an
-      input plugin may provide a <code>resources.xmap</code> file to
-      allow the plugin to handle items such as JavaScript files.</p>
-      
-      <p>It is beyond the scope of this How-To to give details about how to 
-      build your plugins XMap. See the 
-      <a href="site:v0.70//documentation/developers/sitemap-ref">Sitemap Reference</a> for general
-      information. See also 
-      <a href="site:plugins/infrastructure">Plugin Infrastructure</a>
-      for some hints and tips on creating plugin sitemaps. In addition, as with
-      all development work on Forrest, you will find
-      the <a href="site:mail-lists/forrest-dev">developer mailing list</a>
-      a very good resource (check the archives before posting, please).</p>
-      
+      <p>
+        The plugin <code>xmap</code> file is a Cocoon sitemap that is mounted at
+        a strategic place in the Forrest pipeline. It is in this file that you
+        will instruct Forrest how to operate. An input plugin must provide a
+        <code>input.xmap</code> file, an output plugin must provide a
+        <code>output.xmap</code> file, whilst an internal plugin provides a
+        <code>internal.xmap</code> file. In addition, an input plugin may
+        provide a <code>resources.xmap</code> file to allow the plugin to handle
+        items such as JavaScript files.
+      </p>
+      <p>
+        It is beyond the scope of this How-To to give details about how to build
+        your plugins XMap. See the
+        <a href="site:v0.70//documentation/developers/sitemap-ref">Sitemap
+        Reference</a> for general information. See also
+        <a href="site:plugins/infrastructure">Plugin Infrastructure</a> for some
+        hints and tips on creating plugin sitemaps. In addition, as with all
+        development work on Forrest, you will find the
+        <a href="site:mail-lists/forrest-dev">developer mailing list</a> a very
+        good resource (check the archives before posting, please).
+      </p>
       <section id="components">
         <title>Components, Actions and Resources</title>
-        <p>If your plugin uses any components (i.e. generators, transformers or
-        serializers), actions or resources they must
-        be defined in either the xmap for this plugin or one of its parents. The parents
-        of an <code>input.xmap</code> are <code>sitemap.xmap</code> and
-        <code>forrest.xmap</code>, whilst the parent of both 
-        <code>output.xmap</code> and <code>internal.xmap</code> are 
-        <code>sitemap.xmap</code></p>
-        <p>If you want to use the realpath where the sitemap.xmap of your plugin 
-        resides then you need to use 
-        <code>{forrest:forrest.plugins}/PLUGIN_NAME</code> instead of <code>{realpath:/}</code>.
+        <p>
+          If your plugin uses any components (i.e. generators, transformers or
+          serializers), actions or resources they must be defined in either the
+          xmap for this plugin or one of its parents. The parents of an
+          <code>input.xmap</code> are <code>sitemap.xmap</code> and
+          <code>forrest.xmap</code>, whilst the parent of both
+          <code>output.xmap</code> and <code>internal.xmap</code> are
+          <code>sitemap.xmap</code>
+        </p>
+        <p>
+          If you want to use the realpath where the sitemap.xmap of your plugin
+          resides then you need to use
+          <code>{forrest:forrest.plugins}/PLUGIN_NAME</code> instead of
+          <code>{realpath:/}</code>.
+        </p>
+        <p>
+          See the examples below for more details.
         </p>
-        <p>See the examples below for more details.</p>
       </section>
     </section>
-    
     <section id="resources">
       <title>Create the Necessary Resource Files</title>
-      <fixme author="rdg">Discuss the XSL files and other such resources</fixme>
+      <fixme author="rdg">
+        Discuss the XSL files and other such resources
+      </fixme>
     </section>
-    
     <section id="samples">
       <title>Create Samples in the Documentation</title>
-      <p>Plugin documentation should provide (as a minimum) an
-      index page that provides an overview and a set of samples that demonstrate
-      the functionality of the plugin. Typically these samples will be
-      provided in a <code>samples</code> subdirectory in the plugin 
-      documentation and will be referenced from both <code>site.xml</code>
-      and <code>tabs.xml</code> configuration files.</p>
-      
-      <p>Try to provide a sample for all the major functions of your plugin
-      and document any configuration that is available.</p>
+      <p>
+        Plugin documentation should provide (as a minimum) an index page that
+        provides an overview and a set of samples that demonstrate the
+        functionality of the plugin. Typically these samples will be provided in
+        a <code>samples</code> subdirectory in the plugin documentation and will
+        be referenced from both <code>site.xml</code> and <code>tabs.xml</code>
+        configuration files.
+      </p>
+      <p>
+        Try to provide a sample for all the major functions of your plugin and
+        document any configuration that is available.
+      </p>
     </section>
-    
     <section id="test">
       <title>Testing a Plugin</title>
-      <p>Since your documentation for the plugin illustrates all of its 
-      functionality, you can use that site for testing the plugin. However, you
-      must first deploy in your local install of Forrest. Each plugin contains
-      a buildfile that includes a <code>test</code> target. This target, by
-      default, builds the documentation for your plugin.</p>
-      
-      <p class="instruction">Run the command <code>ant test</code> in
-      the plugins directory.</p>
-      
-      <p>Of course, the build should complete without errors.</p>
-      
-      <note>You can also use <code>forrest run</code> to interactively examine
-      your documentation (point your browser at 
-      <a href="http://localhost:8888">http://localhost:8888</a>).</note>
-      
-      <p>It is also a really good idea to build proper tests for your 
-      plugins using a suitable testing framework, for example, 
-      <a href="http://webtest.canoo.com/">WebTest</a>. We recommend that you
-      extend the <code>test</code> target in your plugins build file because
-      this target is also used when performing integration tests on Forrest.
-      In addition, we recommend that you use the samples in your documentation 
-      for your tests, this way you are documenting your plugin at the same time 
-      as writing your tests.</p>
-
-      <p>Ensure that your sitemaps are robust and handle matches for files
-      in sub-directories, as well as those at the root level.</p>
+      <p>
+        Since your documentation for the plugin illustrates all of its
+        functionality, you can use that site for testing the plugin. However,
+        you must first deploy in your local install of Forrest. Each plugin
+        contains a buildfile that includes a <code>test</code> target. This
+        target, by default, builds the documentation for your plugin.
+      </p>
+      <p class="instruction">
+        Run the command <code>ant test</code> in the plugins directory.
+      </p>
+      <p>
+        Of course, the build should complete without errors.
+      </p>
+      <note>
+        You can also use <code>forrest run</code> to interactively examine your
+        documentation (point your browser at
+        <a href="http://localhost:8888">http://localhost:8888</a>).
+      </note>
+      <p>
+        It is also a really good idea to build proper tests for your plugins
+        using a suitable testing framework, for example,
+        <a href="http://webtest.canoo.com/">WebTest</a>. We recommend that you
+        extend the <code>test</code> target in your plugins build file because
+        this target is also used when performing integration tests on Forrest.
+        In addition, we recommend that you use the samples in your documentation
+        for your tests, this way you are documenting your plugin at the same
+        time as writing your tests.
+      </p>
+      <p>
+        Ensure that your sitemaps are robust and handle matches for files in
+        sub-directories, as well as those at the root level.
+      </p>
     </section>
-    
     <section id="release">
       <title>Releasing a Plugin</title>
-    
       <section id="register">
         <title>Register the Plugin with Apache Forrest</title>
-        <fixme author="rdg">Describe the plugins.xml file</fixme>
-        <fixme author="rdg">Describe making a request of Forrest devs for 
-        inclusion</fixme>
+        <fixme author="rdg">
+          Describe the plugins.xml file
+        </fixme>
+        <fixme author="rdg">
+          Describe making a request of Forrest devs for inclusion
+        </fixme>
       </section>
-      
       <section id="deploy">
         <title>Deploying the Plugin</title>
-        <p>To deploy the plugin so that others can use it, it must be made 
-        available as a zip from the URL indicated in the 
-        <code>plugins.xml</code> file. The plugins build file provides targets 
-        to assist with this task.</p>
-        
-        <p class="instruction">To deploy a plugin simply run the command
-        <code>ant deploy</code> from within the plugin directory.</p>
-        
-        <p>This command will, by default, deploy to the Apache Forrest web site.
-        In order to do this you need commit access to Forrest. If you want to
-        deploy your plugin to a different location you 
-        can build the zip of your plugin with <code>ant dist</code>
-        and then copy the zip file from <code>build/dist</code> to wherever
-        you intend to host the plugin.</p>
-        
-        <note>Running this command on any plugin will also deploy any
-        changes to the <code>plugins.xml</code> file. If you are deploying to
-        your own website you will have to request changes to the 
-        <code>plugins.xml</code> and ask the Forrest committers to publish the new
-        document.</note>
-        
-        <warning>Running the <code>deploy</code> or <code>dist</code> targets
-        will always run the <code>test</code> target first. This is to ensure
-        that your only deploy working plugins. This adds a little time to
-        the deploy cycle, but we feel the peace of mind is worth it.</warning>
-        
+        <p>
+          To deploy the plugin so that others can use it, it must be made
+          available as a zip from the URL indicated in the
+          <code>plugins.xml</code> file. The plugins build file provides targets
+          to assist with this task.
+        </p>
+        <p class="instruction">
+          To deploy a plugin simply run the command <code>ant deploy</code> from
+          within the plugin directory.
+        </p>
+        <p>
+          This command will, by default, deploy to the Apache Forrest web site.
+          In order to do this you need commit access to Forrest. If you want to
+          deploy your plugin to a different location you can build the zip of
+          your plugin with <code>ant dist</code> and then copy the zip file from
+          <code>build/dist</code> to wherever you intend to host the plugin.
+        </p>
+        <note>
+          Running this command on any plugin will also deploy any changes to the
+          <code>plugins.xml</code> file. If you are deploying to your own
+          website you will have to request changes to the
+          <code>plugins.xml</code> and ask the Forrest committers to publish the
+          new document.
+        </note>
+        <warning>
+          Running the <code>deploy</code> or <code>dist</code> targets will
+          always run the <code>test</code> target first. This is to ensure that
+          your only deploy working plugins. This adds a little time to the
+          deploy cycle, but we feel the peace of mind is worth it.
+        </warning>
       </section>
     </section>
-    
     <section id="examples">
       <title>Examples</title>
-      <p>This section will provide some example plugins to help illustrate the
-      steps discussed above.</p>
-        <section id="input">
-          <title>Input Plugin</title>
-          <fixme author="RDG">Discuss OpenOffice.org plugin here</fixme>
-        </section>
-        
-        <section id="output">
-          <title>Output Plugin</title>
-          <fixme author="RDG">Discuss s5 plugin here</fixme>
-        </section>
-        
-        <section id="internal">
-          <title>Internal Plugin</title>
-          <fixme author="RDG">Discuss IMSManifest plugin here</fixme>
-        </section>
+      <p>
+        This section will provide some example plugins to help illustrate the
+        steps discussed above.
+      </p>
+      <section id="input">
+        <title>Input Plugin</title>
+        <fixme author="RDG">
+          Discuss OpenOffice.org plugin here
+        </fixme>
+      </section>
+      <section id="output">
+        <title>Output Plugin</title>
+        <fixme author="RDG">
+          Discuss s5 plugin here
+        </fixme>
+      </section>
+      <section id="internal">
+        <title>Internal Plugin</title>
+        <fixme author="RDG">
+          Discuss IMSManifest plugin here
+        </fixme>
+      </section>
     </section>
-
     <section id="extension">
       <title>Further Reading</title>
-      
       <ul>
         <li><a href="site:plugins/infrastructure">Plugin Infrastrucuture Documentation</a> for Developers</li>
         <li><a href="site:plugins">Plugins Documentation</a> for users</li>
       </ul>
     </section>
-
     <section id="summarise">
       <title>Summarise the Entire Process</title>
-
-      <fixme author="rdg">In a few sentences, remind the reader what they have just learned.
-      This helps to reinforce the main points of your How-To.</fixme>
+      <fixme author="rdg">
+        In a few sentences, remind the reader what they have just learned. This
+        helps to reinforce the main points of your How-To.
+      </fixme>
     </section>
   </steps>
 </howto>



Mime
View raw message