procedures/How_to_publish_docs.html - forrest - Git at Google

 <!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 Publish Forrest Documentation</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">
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">
 <a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
 </div>
 <!--+
     |header
     +-->
 <div class="header">
 <!--+
     |start group logo
     +-->
 <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>
 <!--+
     |end group logo
     +-->
 <!--+
     |start Project Logo
     +-->
 <div class="projectlogo">
 <a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
 </div>
 <!--+
     |end Project Logo
     +-->
 <!--+
     |start Search
     +-->
 <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">&nbsp;
                     <input name="Search" value="Search" type="submit">
 </form>
 </div>
 <!--+
     |end search
     +-->
 <!--+
     |start Tabs
     +-->
 <ul id="tabs">
 <li>
 <a class="unselected" href="../index.html">Welcome</a>
 </li>
 <li class="current">
 <a class="selected" href="../contrib.html">Developers</a>
 </li>
 <li>
 <a class="unselected" href="../versions/index.html">Versioned Docs</a>
 </li>
 <li>
 <a class="unselected" href="../pluginDocs/index.html">Plugins</a>
 </li>
 <li>
 <a class="unselected" href="../tools/index.html">Tools</a>
 </li>
 </ul>
 <!--+
     |end Tabs
     +-->
 </div>
 </div>
 <div id="main">
 <div id="publishedStrip">
 <!--+
     |start Subtabs
     +-->
 <div id="level2tabs"></div>
 <!--+
     |end Endtabs
     +-->
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">

              &nbsp;
            </div>
 <!--+
     |start Menu, mainarea
     +-->
 <!--+
     |start Menu
     +-->
 <div id="menu">
 <div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
 <div id="menu_1.1" class="menuitemgroup">
 <div class="menuitem">
 <a href="../contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
 </div>
 <div class="menuitem">
 <a href="../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
 </div>
 <div class="menuitem">
 <a href="../issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
 </div>
 <div class="menuitem">
 <a href="../forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
 </div>
 <div class="menuitem">
 <a href="../events.html" title="List of upcoming related conferences and meetings">Events</a>
 </div>
 <div onclick="SwitchMenu('menu_1.1.6', '../skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
 <div id="menu_1.1.6" class="menuitemgroup">
 <div class="menuitem">
 <a href="../guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
 </div>
 <div class="menuitem">
 <a href="../committed.html" title="Notes about contribution">Being committed</a>
 </div>
 <div class="menuitem">
 <a href="../roles.html" title="Tasks to keep the project flowing">Project roles</a>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
 <div id="menu_1.2" class="menuitemgroup">
 <div class="menuitem">
 <a href="../asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
 </div>
 <div class="menuitem">
 <a href="../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
 </div>
 <div class="menuitem">
 <a href="../issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
 </div>
 <div class="menuitem">
 <a href="../svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
 </div>
 <div class="menuitem">
 <a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
 </div>
 <div class="menuitem">
 <a href="../gump.html">Gump integration</a>
 </div>
 <div onclick="SwitchMenu('menu_1.2.7', '../skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
 <div id="menu_1.2.7" class="menuitemgroup">
 <div class="menuitem">
 <a href="../plan/index.html">Overview</a>
 </div>
 <div class="menuitem">
 <a href="../plan/internal-xhtml.html">Internal XHTML</a>
 </div>
 </div>
 <div class="menuitem">
 <a href="../todo.html">Todo</a>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_selected_1.3', '../skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Best Practices and Procedures</div>
 <div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
 <div class="menuitem">
 <a href="../howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
 </div>
 <div class="menuitem">
 <a href="../subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
 </div>
 <div class="menuitem">
 <a href="../documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
 </div>
 <div class="menuitem">
 <a href="../howto-howto.html" title="Instructions for writing             a new howto-document">Write a How-to</a>
 </div>
 <div onclick="SwitchMenu('menu_selected_1.3.5', '../skin/')" id="menu_selected_1.3.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Committer notes</div>
 <div id="menu_selected_1.3.5" class="selectedmenuitemgroup" style="display: block;">
 <div class="menuitem">
 <a href="../zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
 </div>
 <div class="menuitem">
 <a href="../procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
 </div>
 <div class="menupage">
 <div class="menupagetitle">Publishing Forrest documentation</div>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
 <div id="menu_1.4" class="menuitemgroup">
 <div class="menuitem">
 <a href="../proposal-asf-forrestbot.html">ASF Forrestbot</a>
 </div>
 </div>
 <div id="credit"></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>
 <!--+
   |alternative credits
   +-->
 <div id="credit2">
 <a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
 </div>
 </div>
 <!--+
     |end Menu
     +-->
 <!--+
     |start content
     +-->
 <div id="content">
 <div title="Portable Document Format" class="pdflink">
 <a class="dida" href="How_to_publish_docs.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
         PDF</a>
 </div>
 <div class="trail">Font size:
 	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
 	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
 	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
 </div>
 <h1>How to Publish Forrest Documentation</h1>
 <div class="abstract">
       This documents the steps that the Documentation Coordinator should follow
       to update the Forrest Website.
     </div>
 <div id="minitoc-area">
 <ul class="minitoc">
 <li>
 <a href="#About">Introduction</a>
 </li>
 <li>
 <a href="#forrestbot-local">Updating the site with a local forrestbot</a>
 </li>
 <li>
 <a href="#OrgDoc">original docs</a>
 </li>
 </ul>
 </div>

 <div class="fixme">
 <div class="label">Fixme (open)</div>
 <div class="content">
       This is work in progress!
     </div>
 </div>

 <a name="N10014"></a><a name="About"></a>
 <h2 class="underlined_10">Introduction</h2>
 <div class="section">
 <p>
         All documentation about Apache Forrest is managed as a Forrest-built
         project located in the site-author directory of forrest/trunk SVN. The
         Apapce Forrest website is updated by generating static pages from the
         site-author-project and committing them to the forrest/site SVN, which
         is then 'svn checkout' on the forrest.apache.org webserver to create the
         website.
       </p>
 <p>
         See other notes for the Documentation Coordinator
         <a href="../roles.html">role</a>.
       </p>
 </div>

 <a name="N10025"></a><a name="forrestbot-local"></a>
 <h2 class="underlined_10">Updating the site with a local forrestbot</h2>
 <div class="section">
 <p>
         Do once, create $FORREST_HOME/deploy.svn.settings file. These
         credentials are needed by forrestbot so that it can do your 'svn add'
         and 'svn commit' etc. to the forrest/site/ repository. The
         deploy.svn.settings file looks like:
       </p>
 <pre class="code">
 &lt;?xml version="1.0"?&gt;
 &lt;project&gt;
     &lt;property name="deploy.svn.user" value="myApacheUsername"/&gt;
     &lt;property name="deploy.svn.password" value="myPassword"/&gt;
 &lt;/project&gt;
       </pre>
 <p>
         Generating and publishing the main docs is very easy using a local
         forrestbot:
       </p>
 <pre class="code">cd site-author
 forrest -f publish.xml build
 forrest -f publish.xml deploy</pre>
 <p>
         This builds the documentation locally then deploys it by committing it
         to the
         <a href="https://svn.apache.org/repos/asf/forrest/site">forrest/site
         SVN</a>. Then a cronjob on the server will automatically publish it.
         However, if instant turnaround is required, then do this:
       </p>
 <pre class="code">ssh people.apache.org
 cd /www/forrest.apache.org
 svn update</pre>
 <p>
         Publishing documentation for a particular plugin is done by:
       </p>
 <pre class="code">cd plugins/myPluginName
 $FORREST_HOME/tools/ant/bin/ant deploy-docs</pre>
 <p>
         See further information in the
         <a href="../docs_0_80/howto/howto-buildPlugin.html">buildPlugin</a> doc.
       </p>
 <p>
         See some general notes about managing
         <a href="http://www.apache.org/dev/project-site.html">project
         websites</a>.
       </p>
 </div>

 <a name="N1005A"></a><a name="OrgDoc"></a>
 <h2 class="underlined_10">original docs</h2>
 <div class="section">
 <p>
         There have been a few explantions of our docs processing on the
         forrest-dev mail list. Need to glean the info from them. Here is the
         content of some:
       </p>
 <pre class="code">

                 To publish from trunk/site-author/

                 Do once:
                 # Create $FORREST_HOME/deploy.svn.settings file. These credentials
                 # are needed by forrestbot so that it can do your 'svn add'
                 # and 'svn commit' etc. to the forrest/site/ repository.
                 # The deploy.svn.settings file looks like:
                 &lt;?xml version="1.0"?&gt;
                 &lt;project&gt;
                     &lt;property name="deploy.svn.user" value="myApacheUsername"/&gt;
                     &lt;property name="deploy.svn.password" value="myPassword"/&gt;
                 &lt;/project&gt;


                 # Make changes to sources, and then test, then commit.
                 # Best to wait on committing the source changes until
                 # you have built and reviewed the docs.

                 # Please, please, ensure valid xml docs. Errors will be
                 # reported during the 'build' phase if you don't.
                 # Also it prevents other people from working with the docs,
                 # which goes against the collaborative development process.

                 # You can do 'forrest validate-xdocs" beforehand or use
                 # a validating editor (link: catalog.html) or for a single doc use
                 # xmllint (link: catalog.html) from the command-line, e.g.
                 # xmllint --noout --valid --catalogs faq.xml

                 # Use the forrestbot to build and then deploy to svn.apache.org ...

                 cd site-author
                 forrest -f publish.xml build
                 # ... verify files in build/forrest-docs
                 forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"

                 Now the files are in SVN at forrest/site
                 Periodically the real website files are updated from there.
                 You do not have to do anything else.

                 ----------------------
                 Note: The first time that you deploy, it will need to do
                 a long svn checkout first.

                 FIXME: That commit message technique does not work.
                 The second word is treated as an ant target to be called.
                 Just leave it out and forrestbot will use a default message.

       </pre>
 <p>
         Some more notes that need to be integrated above ...
       </p>
 <p>
         Note that forrestbot does not remove docs from the forrest/site SVN
         (FOR-392). So need to manually delete: 'cd /svn/forrest/site; svn delete
         oldDoc'. Then remove it from the forrestbot work directories: 'cd
         $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
         work/svn-deploy/forrest-docs/oldDoc'.
       </p>
 <p>
         The generated docs are in build/forrest-docs which is the name given to
         it in the forrestbot descriptor (site-author/publish.xml). Here is a
         trick for reviewing changes that forrestbot is ready to deploy ...
       </p>
 <pre class="code">
 forrest -f publish.xml build
 svn update work/svn-deploy/forrest-docs
 diff -rq build/forrest-docs work/svn-deploy/forrest-docs | grep -v "\.svn" | grep differ</pre>
 </div>

 </div>
 <!--+
     |end content
     +-->
 <div class="clearboth">&nbsp;</div>
 </div>
 <div id="footer">
 <!--+
     |start bottomstrip
     +-->
 <div class="lastmodified">
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <div class="copyright">
         Copyright &copy;
          2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
 </div>
 <!--+
     |end bottomstrip
     +-->
 </div>
 </body>
 </html>
	<!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 Publish Forrest Documentation</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">
	<!--+
	\|breadtrail
	+-->
	<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>
	<!--+
	\|header
	+-->
	<div class="header">
	<!--+
	\|start group logo
	+-->
	<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>
	<!--+
	\|end group logo
	+-->
	<!--+
	\|start Project Logo
	+-->
	<div class="projectlogo">
	<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
	</div>
	<!--+
	\|end Project Logo
	+-->
	<!--+
	\|start Search
	+-->
	<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 name="Search" value="Search" type="submit">
	</form>
	</div>
	<!--+
	\|end search
	+-->
	<!--+
	\|start Tabs
	+-->
	<ul id="tabs">
	<li>
	<a class="unselected" href="../index.html">Welcome</a>
	</li>
	<li class="current">
	<a class="selected" href="../contrib.html">Developers</a>
	</li>
	<li>
	<a class="unselected" href="../versions/index.html">Versioned Docs</a>
	</li>
	<li>
	<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
	</li>
	<li>
	<a class="unselected" href="../tools/index.html">Tools</a>
	</li>
	</ul>
	<!--+
	\|end Tabs
	+-->
	</div>
	</div>
	<div id="main">
	<div id="publishedStrip">
	<!--+
	\|start Subtabs
	+-->
	<div id="level2tabs"></div>
	<!--+
	\|end Endtabs
	+-->
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<!--+
	\|breadtrail
	+-->
	<div class="breadtrail">


	</div>
	<!--+
	\|start Menu, mainarea
	+-->
	<!--+
	\|start Menu
	+-->
	<div id="menu">
	<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
	<div id="menu_1.1" class="menuitemgroup">
	<div class="menuitem">
	<a href="../contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
	</div>
	<div class="menuitem">
	<a href="../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
	</div>
	<div class="menuitem">
	<a href="../issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
	</div>
	<div class="menuitem">
	<a href="../forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
	</div>
	<div class="menuitem">
	<a href="../events.html" title="List of upcoming related conferences and meetings">Events</a>
	</div>
	<div onclick="SwitchMenu('menu_1.1.6', '../skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
	<div id="menu_1.1.6" class="menuitemgroup">
	<div class="menuitem">
	<a href="../guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
	</div>
	<div class="menuitem">
	<a href="../committed.html" title="Notes about contribution">Being committed</a>
	</div>
	<div class="menuitem">
	<a href="../roles.html" title="Tasks to keep the project flowing">Project roles</a>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
	<div id="menu_1.2" class="menuitemgroup">
	<div class="menuitem">
	<a href="../asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
	</div>
	<div class="menuitem">
	<a href="../mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
	</div>
	<div class="menuitem">
	<a href="../issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
	</div>
	<div class="menuitem">
	<a href="../svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
	</div>
	<div class="menuitem">
	<a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
	</div>
	<div class="menuitem">
	<a href="../gump.html">Gump integration</a>
	</div>
	<div onclick="SwitchMenu('menu_1.2.7', '../skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
	<div id="menu_1.2.7" class="menuitemgroup">
	<div class="menuitem">
	<a href="../plan/index.html">Overview</a>
	</div>
	<div class="menuitem">
	<a href="../plan/internal-xhtml.html">Internal XHTML</a>
	</div>
	</div>
	<div class="menuitem">
	<a href="../todo.html">Todo</a>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_selected_1.3', '../skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Best Practices and Procedures</div>
	<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
	<div class="menuitem">
	<a href="../howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
	</div>
	<div class="menuitem">
	<a href="../subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
	</div>
	<div class="menuitem">
	<a href="../documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
	</div>
	<div class="menuitem">
	<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
	</div>
	<div onclick="SwitchMenu('menu_selected_1.3.5', '../skin/')" id="menu_selected_1.3.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Committer notes</div>
	<div id="menu_selected_1.3.5" class="selectedmenuitemgroup" style="display: block;">
	<div class="menuitem">
	<a href="../zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
	</div>
	<div class="menuitem">
	<a href="../procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
	</div>
	<div class="menupage">
	<div class="menupagetitle">Publishing Forrest documentation</div>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
	<div id="menu_1.4" class="menuitemgroup">
	<div class="menuitem">
	<a href="../proposal-asf-forrestbot.html">ASF Forrestbot</a>
	</div>
	</div>
	<div id="credit"></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>
	<!--+
	\|alternative credits
	+-->
	<div id="credit2">
	<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
	</div>
	</div>
	<!--+
	\|end Menu
	+-->
	<!--+
	\|start content
	+-->
	<div id="content">
	<div title="Portable Document Format" class="pdflink">
	<a class="dida" href="How_to_publish_docs.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
	PDF</a>
	</div>
	<div class="trail">Font size:
	<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 Publish Forrest Documentation</h1>
	<div class="abstract">
	This documents the steps that the Documentation Coordinator should follow
	to update the Forrest Website.
	</div>
	<div id="minitoc-area">
	<ul class="minitoc">
	<li>
	<a href="#About">Introduction</a>
	</li>
	<li>
	<a href="#forrestbot-local">Updating the site with a local forrestbot</a>
	</li>
	<li>
	<a href="#OrgDoc">original docs</a>
	</li>
	</ul>
	</div>

	<div class="fixme">
	<div class="label">Fixme (open)</div>
	<div class="content">
	This is work in progress!
	</div>
	</div>

	<a name="N10014"></a><a name="About"></a>
	<h2 class="underlined_10">Introduction</h2>
	<div class="section">
	<p>
	All documentation about Apache Forrest is managed as a Forrest-built
	project located in the site-author directory of forrest/trunk SVN. The
	Apapce Forrest website is updated by generating static pages from the
	site-author-project and committing them to the forrest/site SVN, which
	is then 'svn checkout' on the forrest.apache.org webserver to create the
	website.
	</p>
	<p>
	See other notes for the Documentation Coordinator
	<a href="../roles.html">role</a>.
	</p>
	</div>

	<a name="N10025"></a><a name="forrestbot-local"></a>
	<h2 class="underlined_10">Updating the site with a local forrestbot</h2>
	<div class="section">
	<p>
	Do once, create $FORREST_HOME/deploy.svn.settings file. These
	credentials are needed by forrestbot so that it can do your 'svn add'
	and 'svn commit' etc. to the forrest/site/ repository. The
	deploy.svn.settings file looks like:
	</p>
	<pre class="code">
	<?xml version="1.0"?>
	<project>
	<property name="deploy.svn.user" value="myApacheUsername"/>
	<property name="deploy.svn.password" value="myPassword"/>
	</project>
	</pre>
	<p>
	Generating and publishing the main docs is very easy using a local
	forrestbot:
	</p>
	<pre class="code">cd site-author
	forrest -f publish.xml build
	forrest -f publish.xml deploy</pre>
	<p>
	This builds the documentation locally then deploys it by committing it
	to the
	<a href="https://svn.apache.org/repos/asf/forrest/site">forrest/site
	SVN</a>. Then a cronjob on the server will automatically publish it.
	However, if instant turnaround is required, then do this:
	</p>
	<pre class="code">ssh people.apache.org
	cd /www/forrest.apache.org
	svn update</pre>
	<p>
	Publishing documentation for a particular plugin is done by:
	</p>
	<pre class="code">cd plugins/myPluginName
	$FORREST_HOME/tools/ant/bin/ant deploy-docs</pre>
	<p>
	See further information in the
	<a href="../docs_0_80/howto/howto-buildPlugin.html">buildPlugin</a> doc.
	</p>
	<p>
	See some general notes about managing
	<a href="http://www.apache.org/dev/project-site.html">project
	websites</a>.
	</p>
	</div>

	<a name="N1005A"></a><a name="OrgDoc"></a>
	<h2 class="underlined_10">original docs</h2>
	<div class="section">
	<p>
	There have been a few explantions of our docs processing on the
	forrest-dev mail list. Need to glean the info from them. Here is the
	content of some:
	</p>
	<pre class="code">

	To publish from trunk/site-author/

	Do once:
	# Create $FORREST_HOME/deploy.svn.settings file. These credentials
	# are needed by forrestbot so that it can do your 'svn add'
	# and 'svn commit' etc. to the forrest/site/ repository.
	# The deploy.svn.settings file looks like:
	<?xml version="1.0"?>
	<project>
	<property name="deploy.svn.user" value="myApacheUsername"/>
	<property name="deploy.svn.password" value="myPassword"/>
	</project>


	# Make changes to sources, and then test, then commit.
	# Best to wait on committing the source changes until
	# you have built and reviewed the docs.

	# Please, please, ensure valid xml docs. Errors will be
	# reported during the 'build' phase if you don't.
	# Also it prevents other people from working with the docs,
	# which goes against the collaborative development process.

	# You can do 'forrest validate-xdocs" beforehand or use
	# a validating editor (link: catalog.html) or for a single doc use
	# xmllint (link: catalog.html) from the command-line, e.g.
	# xmllint --noout --valid --catalogs faq.xml

	# Use the forrestbot to build and then deploy to svn.apache.org ...

	cd site-author
	forrest -f publish.xml build
	# ... verify files in build/forrest-docs
	forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"

	Now the files are in SVN at forrest/site
	Periodically the real website files are updated from there.
	You do not have to do anything else.

	----------------------
	Note: The first time that you deploy, it will need to do
	a long svn checkout first.

	FIXME: That commit message technique does not work.
	The second word is treated as an ant target to be called.
	Just leave it out and forrestbot will use a default message.

	</pre>
	<p>
	Some more notes that need to be integrated above ...
	</p>
	<p>
	Note that forrestbot does not remove docs from the forrest/site SVN
	(FOR-392). So need to manually delete: 'cd /svn/forrest/site; svn delete
	oldDoc'. Then remove it from the forrestbot work directories: 'cd
	$FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
	work/svn-deploy/forrest-docs/oldDoc'.
	</p>
	<p>
	The generated docs are in build/forrest-docs which is the name given to
	it in the forrestbot descriptor (site-author/publish.xml). Here is a
	trick for reviewing changes that forrestbot is ready to deploy ...
	</p>
	<pre class="code">
	forrest -f publish.xml build
	svn update work/svn-deploy/forrest-docs
	diff -rq build/forrest-docs work/svn-deploy/forrest-docs \| grep -v "\.svn" \| grep differ</pre>
	</div>

	</div>
	<!--+
	\|end content
	+-->
	<div class="clearboth"> </div>
	</div>
	<div id="footer">
	<!--+
	\|start bottomstrip
	+-->
	<div class="lastmodified">
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<div class="copyright">
	Copyright ©
	2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
	</div>
	<!--+
	\|end bottomstrip
	+-->
	</div>
	</body>
	</html>