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 [EMAIL PROTECTED]:. $ 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 [EMAIL PROTECTED] </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:[EMAIL PROTECTED]:/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>[EMAIL PROTECTED]:/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>
