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 2005/06/23 07:36:34 UTC
svn commit: r193078 [7/65] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/
docs_0_60/howto/bugzilla-patch/my-images/ docs_0_60/howto/multi/
docs_0_60/images/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/
docs_0...
Added: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html (added)
+++ forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,521 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>How to Contribute a Patch via Bugzilla (v0.6)</title>
+<link type="text/css" href="../../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../../skin/profile.css" rel="stylesheet">
+<script src="../../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../../../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../../../skin/')" id="menu_1.1Title" class="menutitle">How-Tos</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../index.html">Index</a>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="howto-bugzilla-patch.pdf"><img alt="PDF -icon" src="../../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>How to Contribute a Patch via Bugzilla</h1>
+<div class="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.
+ </div>
+<div id="motd-area">
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#1.+Create+your+Bugzilla+Account">1. Create your Bugzilla Account</a>
+</li>
+<li>
+<a href="#2.+Enter+a+new+bug+report">2. Enter a new bug report</a>
+<ul class="minitoc">
+<li>
+<a href="#Specify+Version">Specify Version</a>
+</li>
+<li>
+<a href="#Specify+Component">Specify Component</a>
+</li>
+<li>
+<a href="#Specify+Platform">Specify Platform</a>
+</li>
+<li>
+<a href="#Specify+Operating+System+%28OS%29">Specify Operating System (OS)</a>
+</li>
+<li>
+<a href="#Specify+Severity">Specify Severity</a>
+</li>
+<li>
+<a href="#Specify+Initial+State">Specify Initial State</a>
+</li>
+<li>
+<a href="#Specify+Assigned+To">Specify Assigned To</a>
+</li>
+<li>
+<a href="#Specify+URL">Specify URL</a>
+</li>
+<li>
+<a href="#Carefully+choose+the+Summary">Carefully choose the Summary</a>
+</li>
+<li>
+<a href="#Description">Description</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#3.+Send+the+patch+report">3. Send the patch report</a>
+</li>
+<li>
+<a href="#4.+Create+an+attachment+of+the+actual+patch">4. Create an attachment of the actual patch</a>
+<ul class="minitoc">
+<li>
+<a href="#Specify+the+file+to+be+uploaded">Specify the file to be uploaded</a>
+</li>
+<li>
+<a href="#Describe+the+attachment">Describe the attachment</a>
+</li>
+<li>
+<a href="#Specify+the+contentType+of+the+attachment">Specify the contentType of the attachment</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#5.+Submit+the+attachment">5. Submit the attachment</a>
+</li>
+<li>
+<a href="#6.+Be+patient">6. Be patient</a>
+</li>
+<li>
+<a href="#7.+Add+more+description+or+attachments+if+necessary">7. Add more description or attachments if necessary</a>
+</li>
+<li>
+<a href="#8.+Adding+subsequent+patches+to+the+same+document+or+program">8. Adding subsequent patches to the same document or program</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Real World Extension">Real World Extension</a>
+</li>
+<li>
+<a href="#Tips">Tips</a>
+<ul class="minitoc">
+<li>
+<a href="#Setting+user+preferences">Setting user preferences</a>
+</li>
+<li>
+<a href="#Review+the+bugzilla+documentation">Review the bugzilla documentation</a>
+</li>
+<li>
+<a href="#Search+Bugzilla">Search Bugzilla</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#References">References</a>
+</li>
+</ul>
+</div>
+<a name="N10010"></a><a name="Intended Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<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>
+</div>
+<a name="N1001B"></a><a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<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
+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>
+</div>
+<a name="N1002F"></a><a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>
+Here is how to proceed. Go to
+<a target="_blank" href="http://issues.apache.org/bugzilla/">Bugzilla</a>
+in another browser window.
+</p>
+<a name="N1003B"></a><a name="1.+Create+your+Bugzilla+Account"></a>
+<h3 class="underlined_5">1. Create your Bugzilla Account</h3>
+<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>
+<a name="N10048"></a><a name="2.+Enter+a+new+bug+report"></a>
+<h3 class="underlined_5">2. Enter a new bug report</h3>
+<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 alt="Bugzilla Screen" height="342" src="my-images/bugzilla-screen.gif" width="479"></p>
+<a name="N10058"></a><a name="Specify+Version"></a>
+<h4>Specify Version</h4>
+<p>
+This is the version of Cocoon that you prepared your patch against. Choose
+<span class="codefrag">Current CVS</span> 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>
+<a name="N10065"></a><a name="Specify+Component"></a>
+<h4>Specify Component</h4>
+<p>
+Follow the "Component" link for description of the available
+components. If you do not know which component is relevant, then just use
+<span class="codefrag">core</span>.
+</p>
+<a name="N10072"></a><a name="Specify+Platform"></a>
+<h4>Specify Platform</h4>
+<p>
+This is really meant for bug reporting. Perhaps it could be relevant for a
+patch. You would usually specify the <span class="codefrag">All</span> option.
+</p>
+<a name="N1007F"></a><a name="Specify+Operating+System+%28OS%29"></a>
+<h4>Specify Operating System (OS)</h4>
+<p>
+Really meant for bug reporting. Perhaps it could be relevant for a patch.
+You would usually specify the <span class="codefrag">All</span> option.
+</p>
+<a name="N1008C"></a><a name="Specify+Severity"></a>
+<h4>Specify Severity</h4>
+<p>
+The impact that would arise if your patch is not applied. For a documentation
+patch, the severity would usually be the default <span class="codefrag">Normal</span>.
+However, if it addressed some serious lack or fixed a misguided configuration
+statement, then the impact could be <span class="codefrag">major</span>.
+</p>
+<p>
+
+
+(The <span class="codefrag">enhancement</span> 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>
+<a name="N100A6"></a><a name="Specify+Initial+State"></a>
+<h4>Specify Initial State</h4>
+<p>
+Use the <span class="codefrag">New</span> option.
+</p>
+<a name="N100B3"></a><a name="Specify+Assigned+To"></a>
+<h4>Specify Assigned To</h4>
+<p>
+Leave it blank. Your patch will be automatically assigned to the
+<span class="codefrag">cocoon-dev</span> 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 <span class="codefrag">cocoon-dev</span> mailing list, so you do not need
+to Cc anyone there.
+</p>
+<a name="N100C6"></a><a name="Specify+URL"></a>
+<h4>Specify URL</h4>
+<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>
+<a name="N100D0"></a><a name="Carefully+choose+the+Summary"></a>
+<h4>Carefully choose the Summary</h4>
+<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 <span class="codefrag">[PATCH]</span> 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>
+<a name="N100E0"></a><a name="Description"></a>
+<h4>Description</h4>
+<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>
+
+If this were a bug report, then it would need extensive description.
+</p>
+<a name="N100F3"></a><a name="3.+Send+the+patch+report"></a>
+<h3 class="underlined_5">3. Send the patch report</h3>
+<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
+<span class="codefrag">cocoon-dev</span> 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>
+<a name="N10106"></a><a name="4.+Create+an+attachment+of+the+actual+patch"></a>
+<h3 class="underlined_5">4. Create an attachment of the actual patch</h3>
+<p>
+You will be presented with a status screen saying that your bug report
+was accepted and that email was sent to <span class="codefrag">cocoon-dev</span> 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>
+<a name="N10115"></a><a name="Specify+the+file+to+be+uploaded"></a>
+<h4>Specify the file to be uploaded</h4>
+<p>
+Provide the local pathname to your patchfile, e.g.
+<span class="codefrag">/home/me/work/cocoon/patch/howto-bugzilla.tar.gz</span>
+
+</p>
+<a name="N10122"></a><a name="Describe+the+attachment"></a>
+<h4>Describe the attachment</h4>
+<p>
+Provide a concise one line description, e.g.
+<span class="codefrag">Gzipped TAR archive with new docs and diffs</span>
+
+</p>
+<a name="N1012F"></a><a name="Specify+the+contentType+of+the+attachment"></a>
+<h4>Specify the contentType of the attachment</h4>
+<p>
+If it is a Gzipped TAR archive (*.tar.gz) or a .zip archive, then select
+"<span class="codefrag">Binary file (application/octet-stream)</span>".
+If it is just a single xml document, then select
+"<span class="codefrag">Plain text (text/plain)</span>".
+If the patch is just a single diff file, then select
+"<span class="codefrag">Patch file (text/plain, diffs)</span>".
+</p>
+<a name="N10143"></a><a name="5.+Submit+the+attachment"></a>
+<h3 class="underlined_5">5. Submit the attachment</h3>
+<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 <span class="codefrag">cocoon-dev</span> mailing list.
+</p>
+<a name="N10153"></a><a name="6.+Be+patient"></a>
+<h3 class="underlined_5">6. Be patient</h3>
+<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>
+<a name="N1015D"></a><a name="7.+Add+more+description+or+attachments+if+necessary"></a>
+<h3 class="underlined_5">7. Add more description or attachments if necessary</h3>
+<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>
+<a name="N10167"></a><a name="8.+Adding+subsequent+patches+to+the+same+document+or+program"></a>
+<h3 class="underlined_5">8. Adding subsequent patches to the same document or program</h3>
+<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>
+</div>
+<a name="N10171"></a><a name="Real World Extension"></a>
+<h2 class="underlined_10">Real World Extension</h2>
+<div class="section">
+<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>
+</div>
+<a name="N1017B"></a><a name="Tips"></a>
+<h2 class="underlined_10">Tips</h2>
+<div class="section">
+<a name="N10180"></a><a name="Setting+user+preferences"></a>
+<h3 class="underlined_5">Setting user preferences</h3>
+<p>
+You can configure certain preferences, though the Bugzilla defaults work just
+fine.
+</p>
+<a name="N1018A"></a><a name="Review+the+bugzilla+documentation"></a>
+<h3 class="underlined_5">Review the bugzilla documentation</h3>
+<p>
+There are various explanations of terminology and procedures ... follow the
+links should you need to know more.
+</p>
+<a name="N10194"></a><a name="Search+Bugzilla"></a>
+<h3 class="underlined_5">Search Bugzilla</h3>
+<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>
+</div>
+<a name="N1019E"></a><a name="References"></a>
+<h2 class="underlined_10">References</h2>
+<div class="section">
+<ul>
+
+<li>
+Bugzilla is at
+<a href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</a>
+
+</li>
+
+<li>
+Helpful Bug Writing Guidelines are available directly from the
+Bug entry interface.
+</li>
+
+</ul>
+</div>
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/howto/bugzilla-patch/my-images/bugzilla-screen.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: forrest/site/docs_0_60/howto/howto-asf-mirror.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-asf-mirror.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-asf-mirror.html (added)
+++ forrest/site/docs_0_60/howto/howto-asf-mirror.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,396 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Generate an ASF mirrors page using interactive web form (v0.6)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">0.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.14', '../../skin/')" id="menu_selected_1.1.14Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.14" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-howto.html">Single Page</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Download mirror</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16.2', '../../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="howto-asf-mirror.pdf"><img alt="PDF -icon" src="../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Generate an ASF mirrors page using interactive web form</h1>
+<div class="abstract">Use ihtml (interpreted html) to include html form elements
+ into a forrest-generated html page. For example, this enables building
+ automated download mirror pages for ASF project websites.
+ </div>
+<div id="motd-area">
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#cgi">Add the mirrors.cgi as a raw file</a>
+</li>
+<li>
+<a href="#ihtml">Add the mirrors.ihtml to xdocs directory</a>
+</li>
+<li>
+<a href="#menu">Add a menu entry for Download</a>
+</li>
+<li>
+<a href="#link">Cause the mirrors.ithml to be processed as an extra file</a>
+</li>
+<li>
+<a href="#forrest">Run 'forrest' to build your site</a>
+</li>
+<li>
+<a href="#explain">Explanation of the process</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<a name="N10010"></a><a name="Intended Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<ul>
+
+<li>Any Apache project that uses Forrest to generate their website
+ will need to have a mirrors page.</li>
+
+<li>Also anyone interested in the use of ihtml to embed html form
+ elements into a generated Forrest page.</li>
+
+</ul>
+</div>
+<a name="N1001E"></a><a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<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. The processed page
+ includes html "form" elements that are not included in the xdocs DTDs.
+ </p>
+<p>This process has many exciting applications, beyond the scope of
+ this document.
+ </p>
+</div>
+<a name="N10029"></a><a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<ul>
+
+<li>Followed the documentation about
+ <a href="http://www.apache.org/~bodewig/mirror.html">Making your
+ downloads mirrorable</a> and
+ <a href="http://www.apache.org/dev/mirrors.html">Apache Mirroring Information</a>
+ .
+ </li>
+
+<li>Established your ASF distribution space as described.</li>
+
+<li>Already building your project website with Forrest.</li>
+
+</ul>
+</div>
+<a name="N10042"></a><a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<a name="N10047"></a><a name="cgi"></a>
+<h3 class="underlined_5">Add the mirrors.cgi as a raw file</h3>
+<p>As explained in the mirrors document, there will be a two-line CGI
+ wrapper script at the top-level of your website called
+ <span class="codefrag">mirrors.cgi</span>
+</p>
+<p>Utilising the Forrest concept of raw un-processed content,
+ add the file as <span class="codefrag">src/documentation/mirrors.cgi</span>
+ (copy the Forrest project's
+ <a href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/mirrors.cgi">mirrors.cgi</a>)
+ </p>
+<a name="N1005D"></a><a name="ihtml"></a>
+<h3 class="underlined_5">Add the mirrors.ihtml to xdocs directory</h3>
+<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 <span class="codefrag">src/documentation/xdocs/mirrors.html</span>
+ (Use the Forrest project's
+ <a href="http://svn.apache.org/repos/asf/forrest/trunk/src/documentation/content/xdocs/mirrors.ihtml">mirrors.html</a>
+ as a template and edit it to suit.)
+ </p>
+<a name="N10071"></a><a name="menu"></a>
+<h3 class="underlined_5">Add a menu entry for Download</h3>
+<p>Add an entry to your site.xml navigation. For example ...
+ </p>
+<pre class="code">
+ <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 -->
+ ...</pre>
+<a name="N1007F"></a><a name="link"></a>
+<h3 class="underlined_5">Cause the mirrors.ithml to be processed as an extra file</h3>
+<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
+ (<a href="http://cocoon.apache.org/2.1/userdocs/offline/">CLI</a>)
+ to the rescue. Add an entry to your project's cli.xconf by copying the
+ default one from
+ <span class="codefrag">$FORREST_HOME/context/WEB-INF/cli.xconf</span> to your
+ <span class="codefrag">src/documentation/conf/</span> directory (or wherever
+ ${forrest.conf-dir} points). Add the following entry ...
+ </p>
+<pre class="code">
+<uris name="mirrors" follow-links="false">
+ <uri type="append" src="mirrors.html"/>
+</uris></pre>
+<a name="N1009A"></a><a name="forrest"></a>
+<h3 class="underlined_5">Run 'forrest' to build your site</h3>
+<p>
+ That is all that you need to do, Forrest will take care of it from
+ there. Run the '<span class="codefrag">forrest</span>' command. The mirrors.html page
+ will be generated with the skin applied.
+ </p>
+<a name="N100A7"></a><a name="explain"></a>
+<h3 class="underlined_5">Explanation of the process</h3>
+<p>Forrest automatically reads ihtml files and transforms the html source
+ to the forrest xdocs intermediate format. It mainly detects heading
+ elements (h1, h2, etc.) and converts them to "sections". The remainder
+ of the html elements are copied over as-is. With this technique the
+ html form elements are copied over to the output.
+ </p>
+</div>
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/howto/howto-asf-mirror.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-asf-mirror.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-asf-mirror.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/howto/howto-asf-mirror.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_60/howto/howto-howto.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-howto.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-howto.html (added)
+++ forrest/site/docs_0_60/howto/howto-howto.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,483 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>How to write a How-To (v0.6)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">0.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.14', '../../skin/')" id="menu_selected_1.1.14Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.14" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Single Page</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Write a How-to</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16.2', '../../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="howto-howto.pdf"><img alt="PDF -icon" src="../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>How to write a How-To</h1>
+<div class="abstract">This How-To describes the steps necessary to write a How-To
+ document. Writing documentation is a valuable way to give back to the
+ community.</div>
+<div id="motd-area">
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#overview">Write the Overview</a>
+</li>
+<li>
+<a href="#audience">Describe your Intended Audience</a>
+</li>
+<li>
+<a href="#purpose">State the Purpose</a>
+</li>
+<li>
+<a href="#prerequisites">List any Prerequisites</a>
+</li>
+<li>
+<a href="#steps">Describe the Steps of your How-To</a>
+</li>
+<li>
+<a href="#extension">Extend the Learning</a>
+</li>
+<li>
+<a href="#summarize">Summarize the Entire Process</a>
+</li>
+<li>
+<a href="#tips">Additional Tips or FAQs</a>
+</li>
+<li>
+<a href="#references">References</a>
+</li>
+<li>
+<a href="#contribute">Submit via the project issue tracker</a>
+</li>
+<li>
+<a href="#feedback">Get some feedback</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Extension">Extension</a>
+</li>
+<li>
+<a href="#Frequently Asked Questions">Frequently Asked Questions</a>
+<ul class="minitoc">
+<li>
+<a href="#1+What+is+the+difference+between+a+How-To+and+a+tutorial%3F">1 What is the difference between a How-To and a tutorial?</a>
+</li>
+<li>
+<a href="#2+What+spelling+convention+should+I+follow%3F">2 What spelling convention should I follow?</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Tips">Tips</a>
+<ul class="minitoc">
+<li>
+<a href="#tip-dtd">How-To dtd</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#References">References</a>
+</li>
+</ul>
+</div>
+<a name="N10013"></a><a name="Intended Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<p>Users who are ready to share their knowledge and experiences with the
+ community.</p>
+</div>
+<a name="N1001B"></a><a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<p>These guidelines are based on successful how-to document structures
+ used by other open source projects with diverse author groups. Following
+ these tried and true guidelines will help to insure the effectiveness of
+ your work.</p>
+</div>
+<a name="N10023"></a><a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<p>How-To authors should have:</p>
+<ul>
+
+<li>A unique How-To topic, related to using Forrest, which fulfills a
+ specific need. Check out existing How-Tos to find a niche for your work.
+ Consider posting your idea for the How-To to user mailing list, to make
+ sure another author's draft is not already in process.</li>
+
+
+<li>A sufficient ability in English to write the FAQ. However, we would
+ rather that you just make a start, as the community can help to
+ fine-tune the document.</li>
+
+
+<li>Copy this template document "howto-howto.xml" to be modified with
+ your own content as necessary.</li>
+
+
+<li>An understanding of the How-To document structure. Just use this
+ template document and you will be safe.
+ Make sure you run '<span class="codefrag">forrest validate-xdocs</span>' before
+ contributing your document.</li>
+
+</ul>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">See the <a href="../../docs_0_80/../dtdx/howto-v13.dtdx.html">DTD documentation</a>
+ which explains the document structure.</div>
+</div>
+</div>
+<a name="N10044"></a><a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>Here is how to proceed.</p>
+<a name="N1004C"></a><a name="overview"></a>
+<h3 class="underlined_5">Write the Overview</h3>
+<p>An overview helps potential readers to determine quickly if a
+ particular How-To matches their interests or needs. In a few sentences,
+ summarize the main points of your How-To. Make sure to include any
+ critical definitions which will help readers evaluate the utility of
+ your How-To. Consider writing the overview last, after you have
+ completed all other sections.</p>
+<a name="N10056"></a><a name="audience"></a>
+<h3 class="underlined_5">Describe your Intended Audience</h3>
+<p>If your How-To is targetted at a specific audience, describe it here.
+ For example, potential readers will have different levels of skill using
+ Forrest. They will also bring different areas of expertise and
+ backgrounds to their How-To learning experience. When you clarify your
+ target audience up front, you will save all other readers time and
+ confusion.</p>
+<a name="N10060"></a><a name="purpose"></a>
+<h3 class="underlined_5">State the Purpose</h3>
+<p>State the purpose of your How-To. Explain how the reader will benefit
+ by reading it. Give your reader an incentive or two to continue.</p>
+<a name="N1006A"></a><a name="prerequisites"></a>
+<h3 class="underlined_5">List any Prerequisites</h3>
+<p>Inform your reader about any required knowledge, configuration, or
+ resources they may need before stepping through your How-To. Assist them
+ in this preparation by linking to other useful resources on the Forrest
+ site or the web. Helping your readers to prepare increases the
+ likelihood that they will continue reading your How-To.</p>
+<a name="N10074"></a><a name="steps"></a>
+<h3 class="underlined_5">Describe the Steps of your How-To</h3>
+<p>In a precise, step-by-step approach, walk your reader through the
+ process. Make sure your reader can reproduce your intended result by
+ following your exact steps. Make the learning process efficient by
+ supplying sample code snippets or configuration details as
+ necessary.</p>
+<a name="N1007E"></a><a name="extension"></a>
+<h3 class="underlined_5">Extend the Learning</h3>
+<p>Provide your reader with a few real-world examples of how the
+ techniques or capabilities gained from your How-To could be applied.
+ Reward the reader for successfully completing the How-To with a few
+ ideas about how it will pay off.</p>
+<a name="N10088"></a><a name="summarize"></a>
+<h3 class="underlined_5">Summarize the Entire Process</h3>
+<p>In a few sentences, remind the reader what they have just learned.
+ This helps to reinforce the main points of your How-To.</p>
+<a name="N10092"></a><a name="tips"></a>
+<h3 class="underlined_5">Additional Tips or FAQs</h3>
+<p>In some cases, step-by-step instructions simply aren't enough. Use
+ this section to pass on any other tips or frequently asked questions.
+ Anticipating the needs of your readers will increase the overall success
+ of your writing effort.</p>
+<a name="N1009C"></a><a name="references"></a>
+<h3 class="underlined_5">References</h3>
+<p>Remember to acknowledge any third-party resources or individuals who
+ contributed to the development of your How-To. Consider providing links
+ for those motivated readers who want to learn more.</p>
+<a name="N100A6"></a><a name="contribute"></a>
+<h3 class="underlined_5">Submit via the project issue tracker</h3>
+<p>Create an attachment for your How-To document, and submit it via the
+ project <a href="http://issues.apache.org/jira/secure/BrowseProject.jspa?id=12310000">issue tracker</a>.</p>
+<a name="N100B4"></a><a name="feedback"></a>
+<h3 class="underlined_5">Get some feedback</h3>
+<p>When the committers have added your document then it will be
+ available for everyone to to build upon and enhance. Feedback will
+ happen via the <a href="../../mail-lists.html">mailing lists</a>.</p>
+</div>
+<a name="N100C2"></a><a name="Extension"></a>
+<h2 class="underlined_10">Extension</h2>
+<div class="section">
+<p>Solutions can be extended to cover many different problem domains. A
+ nearly unlimited number of potential How-To topics, from simple to
+ complex, are available right now, limited only by your imagination.</p>
+</div>
+<a name="N100CA"></a><a name="Frequently Asked Questions"></a>
+<h2 class="underlined_10">Frequently Asked Questions</h2>
+<div class="section">
+<a name="N100CE"></a><a name="1+What+is+the+difference+between+a+How-To+and+a+tutorial%3F"></a>
+<h3 class="underlined_5">1 What is the difference between a How-To and a tutorial?</h3>
+<p>The goal of a How-To is to help the reader to accomplish a specific
+ task with clear and consise instructions. While tutorials may contain
+ How-To-like instructions and content, they also include additional
+ background and conceptual content to help teach their readers higher
+ order concepts along the way. How-Tos are concerned about filling an
+ immediate, short-term need. Tutorials often provide long-term
+ knowledge which can be applied across a range of needs.</p>
+<a name="N100D6"></a><a name="2+What+spelling+convention+should+I+follow%3F"></a>
+<h3 class="underlined_5">2 What spelling convention should I follow?</h3>
+<p>Use whatever spelling convention (American, British, etc.) that is
+ most intuitive to you.</p>
+</div>
+<a name="N100DE"></a><a name="Tips"></a>
+<h2 class="underlined_10">Tips</h2>
+<div class="section">
+<a name="N100E3"></a><a name="tip-dtd"></a>
+<h3 class="underlined_5">How-To dtd</h3>
+<p>The document structure is likely to change soon. Please note that
+ this HOWTO page is likely to change as well.</p>
+</div>
+<a name="N100ED"></a><a name="References"></a>
+<h2 class="underlined_10">References</h2>
+<div class="section">
+<p>This is not the first, nor will it be the last, How-To on writing
+ How-Tos. For other ideas and opinions on the matter, check out the
+ following sources.</p>
+<ul>
+
+<li>Joel D. Canfield's <a href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
+ to Write a How-To</a> on evolt.org.</li>
+
+
+<li>The Linux Documentation Project's <a href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</a>
+ index page provides many excellent How-To documents to inspire your
+ efforts.</li>
+
+</ul>
+</div>
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/howto/howto-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-howto.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-howto.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/howto/howto-howto.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_60/howto/howto-pdf-tab.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-pdf-tab.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/howto/howto-pdf-tab.html (added)
+++ forrest/site/docs_0_60/howto/howto-pdf-tab.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,520 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>How to create a PDF document for each tab (v0.6)</title>
+<link type="text/css" href="../../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../../skin/profile.css" rel="stylesheet">
+<script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../contrib.html">Project</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="breadtrail">
+
+
+ </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">0.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.14', '../../skin/')" id="menu_selected_1.1.14Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.14" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-howto.html">Single Page</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Create tab PDF</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16.2', '../../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="howto-pdf-tab.pdf"><img alt="PDF -icon" src="../../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>How to create a PDF document for each tab</h1>
+<div class="abstract">This How-To describes the generation of a PDF document for each
+ group of documents that is defined by a tab.
+ </div>
+<div id="motd-area">
+ This is documentation for past version v0.6
+ (<a href="/versions/index.html">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Intended Audience">Intended Audience</a>
+</li>
+<li>
+<a href="#Purpose">Purpose</a>
+</li>
+<li>
+<a href="#Prerequisites">Prerequisites</a>
+</li>
+<li>
+<a href="#Steps">Steps</a>
+<ul class="minitoc">
+<li>
+<a href="#sitemap">Create your project's main sitemap.xmap</a>
+</li>
+<li>
+<a href="#aggregator">Create the aggregator sitemap pdf-tab.xmap</a>
+</li>
+<li>
+<a href="#workaround-202">Edit project sitemap.xmap</a>
+</li>
+<li>
+<a href="#mount">Edit project sitemap.xmap to mount pdf-tab.xmap</a>
+</li>
+<li>
+<a href="#edit-aggregator">Edit the file pdf-tab.xmap</a>
+</li>
+<li>
+<a href="#edit-site">Edit your site.xml</a>
+</li>
+<li>
+<a href="#explain">Explanation of the operation</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Feedback and further development of this How-To">Feedback and further development of this How-To</a>
+</li>
+</ul>
+</div>
+<a name="N10010"></a><a name="Intended Audience"></a>
+<h2 class="underlined_10">Intended Audience</h2>
+<div class="section">
+<p>
+ Users who need to generate one printable document aggregated from a
+ group of documents.
+ </p>
+</div>
+<a name="N10018"></a><a name="Purpose"></a>
+<h2 class="underlined_10">Purpose</h2>
+<div class="section">
+<p>
+ By default Forrest generates a pdf file for each separate document of
+ your project.
+ As well you can create a pdf of the whole site. But sometimes it may
+ be necessary to generate a pdf file out of selected tab, i.e. only for
+ certain parts of the site.
+ </p>
+</div>
+<a name="N10020"></a><a name="Prerequisites"></a>
+<h2 class="underlined_10">Prerequisites</h2>
+<div class="section">
+<ul>
+
+<li>Understand how to create project-specific sitemaps by following the
+ <a href="../../docs_0_60/your-project.html">Using Forrest</a> document.</li>
+
+</ul>
+</div>
+<a name="N1002F"></a><a name="Steps"></a>
+<h2 class="underlined_10">Steps</h2>
+<div class="section">
+<p>The procedure outlined below will define a project
+ <span class="codefrag">sitemap.xmap</span> and create a new
+ <span class="codefrag">pdf-tab.xmap</span> based on the <span class="codefrag">aggregate.xmap</span>
+
+</p>
+<a name="N10040"></a><a name="sitemap"></a>
+<h3 class="underlined_5">Create your project's main sitemap.xmap</h3>
+<p>
+ Simply copy the sitemap.xmap from the Forrest sitemaps at
+ <span class="codefrag">${FORREST_HOME}/context/sitemap.xmap</span> into your
+ <span class="codefrag">src/documentation</span> directory (or wherever
+ ${project.sitemap-dir} points to).
+ </p>
+<a name="N10050"></a><a name="aggregator"></a>
+<h3 class="underlined_5">Create the aggregator sitemap pdf-tab.xmap</h3>
+<p>
+ Copy the aggregate.xmap from Forrest sitemaps into your
+ ${project.sitemap-dir} and rename it to pdf-tab.xmap
+ </p>
+<a name="N1005A"></a><a name="workaround-202"></a>
+<h3 class="underlined_5">Edit project sitemap.xmap</h3>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ This is a workaround for Issue FOR-202
+ </div>
+</div>
+<p>
+ Edit the project <span class="codefrag">sitemap.xmap</span> to comment-out the match
+ for the sitemap like this:
+ </p>
+<pre class="code">
+<!--
+<map:pipeline internal-only="false">
+<map:select type="exists">
+ <map:when test="{project:sitemap}">
+ <map:mount uri-prefix="" src="{project:sitemap}" check-reload="yes" />
+ </map:when>
+</map:select>
+</map:pipeline
+-->
+ </pre>
+<a name="N1006E"></a><a name="mount"></a>
+<h3 class="underlined_5">Edit project sitemap.xmap to mount pdf-tab.xmap</h3>
+<p>
+ Insert the following lines after the
+ <span class="codefrag"><map:match pattern="site.xml"></span>
+ pipeline in the section called "SOURCE FORMATS".
+ </p>
+<pre class="code">
+...
+<map:match pattern="pdf-tab.xml">
+ <map:mount uri-prefix="" src="pdf-tab.xmap" check-reload="yes" />
+</map:match>
+...
+ </pre>
+<a name="N1007F"></a><a name="edit-aggregator"></a>
+<h3 class="underlined_5">Edit the file pdf-tab.xmap</h3>
+<p>
+ The <span class="codefrag"><map:match pattern="*.xml"></span> element
+ should look like the following:
+ </p>
+<pre class="code">
+<map:match pattern="*.xml">
+ <map:generate src="cocoon://abs-linkmap"/>
+ <map:transform type="xpath">
+ <map:parameter name="include" value="//*[@wholesite='true']"/>
+ <map:parameter name="exclude" value="//*[@wholesite='false']"/>
+ </map:transform>
+ <map:transform src="resources/stylesheets/site2book.xsl" />
+ <map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl">
+ <map:parameter name="title"
+ value="{conf:project-name}: Still My Foo Site"/>
+ </map:transform>
+ <map:transform type="cinclude"/>
+ <map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/>
+ <map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/>
+ <map:serialize type="xml"/>
+</map:match>
+ </pre>
+<a name="N10092"></a><a name="edit-site"></a>
+<h3 class="underlined_5">Edit your site.xml</h3>
+<p>Add the following entry to your site.xml in the
+ <span class="codefrag"><about></span> element
+ </p>
+<pre class="code">...
+<whole_foosite href="pdf-tab.html" label="sub site" />
+ </pre>
+<p>
+ Your site.xml should look like this ...
+ </p>
+<pre class="code">...
+<about label="About">
+ <index label="Index" href="index.html" description="Welcome to MyProj"/>
+ <changes label="Changes" href="changes.html"
+ description="History of Changes" />
+ <todo label="Todo" href="todo.html" description="Todo List" />
+ <whole_foosite href="pdf-tab.html" label="pdf-tab" />
+</about>
+...
+ </pre>
+<p>
+ This allows you to link to it via a
+ <span class="codefrag"><link href="site:v0.60//whole_foosite"></span>
+ reference.
+ </p>
+<p>Add to every element that should be included in the pdf-tab.pdf
+ the attribute <span class="codefrag">wholesite="true"</span>
+</p>
+<pre class="code">
+<sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" wholesite="true"/>
+ </pre>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">This attribute will be inherited by all children of the element.
+ Do not use it in the parent element that contains the
+ <span class="codefrag"><whole_foosite href="pdf-tab.html" label="pdf-tab" /></span>
+ as the child (will cause a <span class="codefrag">stack overflow</span> if you do)!!!
+ </div>
+</div>
+<a name="N100C2"></a><a name="explain"></a>
+<h3 class="underlined_5">Explanation of the operation</h3>
+<p>
+ Line 4 of our example
+ <br>
+
+<span class="codefrag"><map:parameter name="include" value="//*[@wholesite='true']"/></span>
+ looks at your site.xml and will match every element containing the
+ <span class="codefrag">wholesite="true"</span> attribute. For example, to use the "samples"
+ tab ...
+ </p>
+<pre class="code">
+...
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+...
+</samples>
+...
+ </pre>
+<p>
+ It matches <strong>all</strong> of the elements that contain
+ <span class="codefrag">wholesite="true"</span>
+ (in our example <span class="codefrag"><samples></span>
+ and its "children") for the content of the pdf file to be generated.
+ </p>
+<pre class="code">
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+ <sample2 label="Static content" href="sample2.html"
+ description="More Samples" wholesite='false'/>
+ <sample-wiki label="Wiki page" href="wiki-sample.html"
+ description="wiki-sample" />
+ <sample-ihtml label="ihtml page" href="ihtml-sample.html"
+ description="Test iHTML page" />
+</samples>
+ </pre>
+<p>
+ This example shows that you can as well exclude site(s) from the aggregation
+ by using the <span class="codefrag">wholesite="false"</span> attribute. This attribute will be as well inherited
+ by all children of the element.
+ </p>
+<p>
+ Line 8 defines the title of the pdf file by taking the content
+ of the project-name variable in
+ <span class="codefrag">skinconf.xml</span> and adding some funny text:
+ <br>
+
+<span class="codefrag"><map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/></span>
+
+</p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">
+ In the original <span class="codefrag">aggregate.xmap</span> there is the line
+ <br>
+
+<span class="codefrag"><map:parameter name="ignore" value="{1}"/></span>
+
+<br>
+ just before the title definition
+ (<span class="codefrag"><map:parameter name="title" value=".../></span>).
+ Be sure to delete it or comment it out if you like to generate a
+ pdf-file for specific sites. You only need it for the generation of
+ one pdf-file for the whole project (this is what
+ <span class="codefrag">aggregate.xmap</span> usually does).
+ </div>
+</div>
+</div>
+<a name="N1010C"></a><a name="Feedback and further development of this How-To"></a>
+<h2 class="underlined_10">Feedback and further development of this How-To</h2>
+<div class="section">
+<p>
+ Please provide feedback about this document via the
+ <a href="../../mail-lists.html">mailing lists</a>.
+ </p>
+<p>
+ In the future, this ability will probably be incorporated into the
+ main Forrest process.
+ </p>
+<div class="frame fixme">
+<div class="label">Fixme (open)</div>
+<div class="content">
+ This document will need to be modified when Issue FOR-202 is solved.
+ </div>
+</div>
+</div>
+</div>
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/howto/howto-pdf-tab.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/howto/howto-pdf-tab.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/howto/howto-pdf-tab.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/howto/howto-pdf-tab.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf