You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2007/04/10 05:48:57 UTC
svn commit: r527010 [11/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_...
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/glossary.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/glossary.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/glossary.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/glossary.xml Mon Apr 9 20:48:52 2007
@@ -20,9 +20,10 @@
<glossary>
<title>Forrest Glossary</title>
<introduction>
- <p>This is a glossary of terms and their definitions for the
- Apache Forrest project. Some plugins also have a glossary, for example
- <link href="http://forrest.apache.org/pluginDocs/dev/org.apache.forrest.plugin.internal.dispatcher/">Dispatcher</link>.
+ <p>
+ This is a glossary of terms and their definitions for the Apache Forrest
+ project. Some plugins also have a glossary, for example
+ <link href="http://forrest.apache.org/pluginDocs/dev/org.apache.forrest.plugin.internal.dispatcher/">Dispatcher</link>.
</p>
</introduction>
<part id="a">
@@ -43,15 +44,15 @@
</definitions>
<notes>
<item-note>See Apache Cocoon
- <link href="http://wiki.apache.org/cocoon/AbbreviationsInMails">Abbreviations In Mails</link></item-note>
+ <link href="http://wiki.apache.org/cocoon/AbbreviationsInMails">Abbreviations In Mails</link>
+ </item-note>
</notes>
</item>
<item id="ASF">
<term>The Apache Software Foundation</term>
<acronym title="The Apache Software Foundation">ASF</acronym>
<definitions>
- <definition>
- <link href="http://apache.org/">The Apache Software Foundation</link> is the home of Apache
+ <definition><link href="http://apache.org/">The Apache Software Foundation</link> is the home of Apache
Forrest.</definition>
</definitions>
</item>
@@ -68,22 +69,23 @@
</definitions>
<notes>
<item-note>See
- <link href="http://www.w3.org/Style/CSS/">W3C</link></item-note>
+ <link href="http://www.w3.org/Style/CSS/">W3C</link>
+ </item-note>
<item-note>See
- <link href="http://www.csszengarden.com/">css Zen Garden</link></item-note>
+ <link href="http://www.csszengarden.com/">css Zen Garden</link>
+ </item-note>
</notes>
</item>
</part>
- <part id="r">
- <title>R</title>
- <item id="ReleaseCandidate">
- <term>Release Candidate</term>
- <definitions>
- <definition>A temporary Forrest package build from trunk during the <link href="site:howToRelease">release process</link> to be tested and evaluated.</definition>
-
- </definitions>
- </item>
- </part>
+ <part id="r">
+ <title>R</title>
+ <item id="ReleaseCandidate">
+ <term>Release Candidate</term>
+ <definitions>
+ <definition>A temporary Forrest package build from trunk during the <link href="site:howToRelease">release process</link> to be tested and evaluated.</definition>
+ </definitions>
+ </item>
+ </part>
<part id="s">
<title>S</title>
<item id="SoC">
@@ -94,12 +96,10 @@
concentrate on their separate, but well-integrated, area of concern.</definition>
</definitions>
<notes>
- <item-note>
- <link href="http://cocoon.apache.org/2.1/introduction.html#Separation+of+Concerns+(SoC)">
+ <item-note><link href="http://cocoon.apache.org/2.1/introduction.html#Separation+of+Concerns+(SoC)">
Introducing Apache Cocoon</link>
</item-note>
- <item-note>
- <link href="http://excalibur.apache.org/developing/introduction.html#Separation_of_Concerns">
+ <item-note><link href="http://excalibur.apache.org/developing/introduction.html#Separation_of_Concerns">
Apache Excalibur Introduction and Overview</link>
</item-note>
</notes>
@@ -111,15 +111,14 @@
</definitions>
</item>
<item id="StandardDocumentFormat">
- <term>Standard Document Format</term>
- <definitions>
- <definition>Forrests <em>internal</em> document format (defined by an XML-grammar). This format ist the common denominator
+ <term>Standard Document Format</term>
+ <definitions>
+ <definition>Forrests <em>internal</em> document format (defined by an XML-grammar). This format ist the common denominator
for all things going into or coming out of Forrest's core processing. All input-plugins will translate their supported documents into this
format, all output-plugins will create the output by transforming this format into something else. Currently Forrest uses <link href="site:document-v13-dtd">document-v13-dtd</link> as its internal format.
</definition>
- </definitions>
- </item>
-
+ </definitions>
+ </item>
</part>
<part id="x">
<title>X</title>
@@ -132,11 +131,9 @@
used as an input source format.</definition>
</definitions>
<notes>
- <item-note>
- <link href="site:dtd-docs">Reference docs</link>
+ <item-note><link href="site:dtd-docs">Reference docs</link>
</item-note>
- <item-note>
- <link href="site:samples-container/document-v20">Sample xdoc</link>
+ <item-note><link href="site:samples-container/document-v20">Sample xdoc</link>
</item-note>
</notes>
</item>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/book.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/book.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/book.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/book.xml Mon Apr 9 20:48:52 2007
@@ -16,16 +16,11 @@
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="Copyright 2002-2005 The Apache Software Foundation or its licensors, as applicable"
xmlns:xlink="http://www.w3.org/1999/xlink">
-
- <menu label="How-Tos">
+ <menu label="How-Tos">
<menu-item label="Index" href="../index.html"/>
</menu>
-
-
-
</book>
Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/howto-bugzilla-patch.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/howto-bugzilla-patch.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/bugzilla-patch/howto-bugzilla-patch.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/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 "patch",
though it does need separate treatment to a normal "diff".
</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>"Bugs"</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 "Open a new Bugzilla account".
-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 "Component" 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 "Open a new Bugzilla
+ account". 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 "Component" 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 "Back to Bug #XXXXX". If you forgot to mention something,
-then you can add more comments. From that screen, follow the link
-"Create a new attachment".
-Otherwise follow the link from this status screen to "Attach a file to
-this bug".
-</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
-"<code>Binary file (application/octet-stream)</code>".
-If it is just a single xml document, then select
-"<code>Plain text (text/plain)</code>".
-If the patch is just a single diff file, then select
-"<code>Patch file (text/plain, diffs)</code>".
-</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 "Back to Bug #XXXXX". If you forgot to mention
+ something, then you can add more comments. From that screen, follow the
+ link "Create a new attachment". Otherwise follow the link from
+ this status screen to "Attach a file to this bug".
+ </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 "<code>Binary file
+ (application/octet-stream)</code>". If it is just a single xml
+ document, then select "<code>Plain text
+ (text/plain)</code>". If the patch is just a single diff file,
+ then select "<code>Patch file (text/plain, diffs)</code>".
+ </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_80/howto/cvs-ssh/book.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/cvs-ssh/book.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/cvs-ssh/book.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/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: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_80/howto/cvs-ssh/howto-cvs-ssh.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/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_80/howto/howto-asf-mirror.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-asf-mirror.xml?view=diff&rev=527010&r1=527009&r2=527010
==============================================================================
--- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-asf-mirror.xml (original)
+++ forrest/trunk/site-author/content/xdocs/docs_0_80/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
@@ -37,20 +35,18 @@
elements into a generated Forrest page.</li>
</ul>
</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
@@ -63,60 +59,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
@@ -124,12 +125,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>
@@ -137,12 +139,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>