| <!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.9-dev"> |
| <meta name="Forrest-skin-name" content="pelt"> |
| <title>How to do development with Apache Forrest</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 Software Foundation</a> > <a href="http://forrest.apache.org/">Apache 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="tasks.html" title="Tasks to keep the project flowing">Project tasks</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="menupage"> |
| <div class="menupagetitle">Development tips</div> |
| </div> |
| <div class="menuitem"> |
| <a href="howto-forrestbot-svn.html" title="Publish documentation with Forrestbot svn workstage">Forrestbot svn</a> |
| </div> |
| <div class="menuitem"> |
| <a href="howto-forrestbot-scp.html" title="Publish documentation with Forrestbot scp workstage">Forrestbot scp</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_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div> |
| <div id="menu_1.3.7" class="menuitemgroup"> |
| <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="menuitem"> |
| <a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest Website">Publishing Forrest documentation</a> |
| </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://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a> |
| </div> |
| </div> |
| <!--+ |
| |end Menu |
| +--> |
| <!--+ |
| |start content |
| +--> |
| <div id="content"> |
| <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 do development with Apache Forrest</h1> |
| <div id="front-matter"> |
| <div class="abstract"> |
| This How-To provides some tips and procedures for efficiently developing with Forrest. |
| </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="#Development-techniques-and-scenarios">Development techniques and scenarios</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#dev-environment">Development environment</a> |
| </li> |
| <li> |
| <a href="#svn">Using Subversion</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#multiple">Multiple working copies</a> |
| </li> |
| <li> |
| <a href="#svn-email">Watch email notifications for svn differences</a> |
| </li> |
| <li> |
| <a href="#svn-find-break">Updating svn backwards to find where something broke</a> |
| </li> |
| <li> |
| <a href="#svn-merge">Reverting Changes using SVN Merge</a> |
| </li> |
| <li> |
| <a href="#svn-patch">Creating patches</a> |
| </li> |
| <li> |
| <a href="#tips-svn">Tips</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#edit">Editing content</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#code-style">Code style guidelines</a> |
| </li> |
| <li> |
| <a href="#whitespace">Whitespace</a> |
| </li> |
| <li> |
| <a href="#line-length">Line length</a> |
| </li> |
| <li> |
| <a href="#review">Use 'forrest run' for immediate gratification</a> |
| </li> |
| <li> |
| <a href="#tips-edit">Tips</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#sitemap">Understanding the Cocoon sitemap</a> |
| </li> |
| <li> |
| <a href="#debug">Debugging and profiling techniques</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#debug-logfiles">View logfiles</a> |
| </li> |
| <li> |
| <a href="#debug-intermediate">View intermediate processing</a> |
| </li> |
| <li> |
| <a href="#debug-cocoon-profiler">Using Cocoon sitemap profiler</a> |
| </li> |
| <li> |
| <a href="#debug-sitemap-exec">Using Cocoon sitemap execution logger</a> |
| </li> |
| <li> |
| <a href="#debug-logtransformer">Using Cocoon LogTransformer</a> |
| </li> |
| <li> |
| <a href="#debug-validation">Using Cocoon Validation Transformers</a> |
| </li> |
| <li> |
| <a href="#validate-intermediate">Validate all intermediate xml content</a> |
| </li> |
| <li> |
| <a href="#debug-java">Java code</a> |
| </li> |
| <li> |
| <a href="#debug-links">Finding broken internal links</a> |
| </li> |
| <li> |
| <a href="#tips-debug">Tips</a> |
| </li> |
| <li> |
| <a href="#profile-yourkit">Profiling Forrest with YourKit</a> |
| </li> |
| <li> |
| <a href="#profile-netbeans">Profiling Forrest with Netbeans</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#find">Finding the relevant sources</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#find-scenario-1">Scenario: How does i18n work</a> |
| </li> |
| <li> |
| <a href="#tips-find">Tips</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#faqs">Frequently Asked Questions</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#faq-general">1 General issues</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#1.1+FAQ+1">1.1 FAQ 1</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#faq-other">2 Other issues</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#2.1+FAQ+2.1">2.1 FAQ 2.1</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#Tips">Tips</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#tip-howto">Explanations about howto topics on the mailing lists</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#References">References</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <a name="Intended-Audience"></a> |
| <h2 class="underlined_10">Intended Audience</h2> |
| <div class="section"> |
| <div class="warning"> |
| <div class="label">Warning</div> |
| <div class="content"> |
| This document is under initial development. |
| </div> |
| </div> |
| <p> |
| People who are ready to go beyond the basics of using Forrest. This might |
| be to utilise Forrest for your advanced needs, debugging, creating a new |
| plugin, enhancing an existing plugin, enhancing the core capabilities, |
| contributing such enhancements back to the Apache Forrest project, etc. In |
| all cases, this is what we mean by "developer". |
| </p> |
| <p> |
| Actually, users will also find that some parts of this document are |
| useful. For example, the section about debugging and the section about |
| editing content. |
| </p> |
| </div> |
| <a name="Purpose"></a> |
| <h2 class="underlined_10">Purpose</h2> |
| <div class="section"> |
| <p> |
| This How-To provides some tips and procedures for being an Apache Forrest |
| developer. Ideally a developer would also contribute back to the project, |
| so these notes assume that. Various key development tasks are used as |
| worked examples. |
| </p> |
| <p> |
| This document is intended to be an introduction to developing in Forrest, |
| specifically, for those developers without a strong Cocoon background. |
| Some key concepts in Forrest like sitemaps, pipelines, and locationmaps |
| can be challenging enough to understand without also struggling with the |
| fundamental development chores of debugging, extension methods, etc. The |
| goal of this document is to reduce the steep learning curve by providing |
| answers to some really practical Forrest development questions. |
| </p> |
| </div> |
| <a name="Prerequisites"></a> |
| <h2 class="underlined_10">Prerequisites</h2> |
| <div class="section"> |
| <ul> |
| |
| <li> |
| You have achieved the basic level of using Forrest. You have Forrest |
| installed and can create a new site with 'forrest seed'. |
| You have followed at least the first parts of the |
| <a href="docs_0_90/your-project.html">Using Forrest</a> |
| document. |
| </li> |
| |
| <li> |
| You will enventually see that understanding of the Cocoon |
| <a href="docs_0_90/sitemap-ref.html">sitemap</a> |
| is important. For the initial examples below, you can do without that. |
| However please explore the sitemap soon. |
| </li> |
| |
| </ul> |
| </div> |
| <a name="Development-techniques-and-scenarios"></a> |
| <h2 class="underlined_10">Development techniques and scenarios</h2> |
| <div class="section"> |
| <p> |
| Various scenarios are utilised to describe aspects of development. Bear in |
| mind that there are many ways to do things. Each developer has different |
| tools and habits, and different operating systems are used. So you will |
| need to glean the principles and apply them to your own situation. |
| </p> |
| <p> |
| This document assumes that you intend to contribute some parts of your |
| work back to the project. Techniques for network-based collaborative |
| development are encouraged. |
| </p> |
| <a name="dev-environment"></a> |
| <h3 class="underlined_5">Development environment</h3> |
| <p> |
| There is no *proper* dev environment. It really depends on your personal |
| preferences. In an opensource project there is huge variety of |
| environments. This makes it quite a challenge to keep sources consistent |
| (see discussion below). |
| </p> |
| <p> |
| Some people use vi or emacs, others use graphical editors, others use |
| integrated development environments such as Eclipse or IDEA. |
| </p> |
| <p> |
| Ensure to <a href="docs_0_90/catalog.html">configure</a> your xml editor to take |
| advantage of the local sets of DTDs provided by Forrest. This also |
| explains how to use xml validators such as 'xmllint'. If your editor of |
| choice doesn't validate XML, then most XML validation issues can be |
| discovered using <span class="codefrag">forrest validate-xdocs</span> |
| |
| </p> |
| <p> |
| There really isn't much Java code in Forrest, but a Java Development |
| Environment such as Eclipse or any text editor of your choice will work |
| just fine. If you point Eclipse at the Forrest build file it will make |
| life easy for you. |
| </p> |
| <a name="svn"></a> |
| <h3 class="underlined_5">Using Subversion</h3> |
| <p> |
| The Subversion source control system is used for all ASF projects. You |
| can leverage this to ease your own development. |
| </p> |
| <p> |
| The "trunk" is where all new development and bugfixing happens. We aim |
| to keep the trunk usable at all times. |
| </p> |
| <p> |
| Each version release is a "branch", such as "forrest_07_branch". Crucial |
| bugfixes are also applied to the relevant release branch. |
| </p> |
| <p> |
| Branches are also used for developing complex new code which would |
| otherwise disrupt the trunk. When the new work is suitable, then that |
| branch is merged back to the trunk as soon as possible. |
| </p> |
| <p> |
| To get started, see the <a href="docs_0_90/howto/../build.html">instructions</a> for |
| obtaining the Apache Forrest sources via SVN. |
| </p> |
| <p> |
| Whether you use the svn command-line client or a fancy client, then you |
| still need to make sure you know how to operate SVN properly. |
| <a href="http://svnbook.red-bean.com/" rel="nofollow">http://svnbook.red-bean.com</a> |
| is a must. |
| </p> |
| <a name="multiple"></a> |
| <h4>Multiple working copies</h4> |
| <p> |
| Most developers would have a number of separate SVN working copies. |
| Hopefully you are brave enough to use the trunk for all your sites. |
| Sometimes that is not possible, for example when you are |
| co-operativley managing a site with other people who are not so brave, |
| so you need to use a specific release. However consider using the SVN |
| release branch, rather than the release archive (tar or zip). This |
| enables you to easily keep up with bugfixes. You can also easily see |
| what local changes that you have made by using 'svn status; svn diff'. |
| </p> |
| <p> |
| Here is one layout ... |
| </p> |
| <pre class="code"> |
| [localhost]$ ls /svn/asf |
| forrest_07_branch |
| forrest-trunk |
| </pre> |
| <a name="svn-email"></a> |
| <h4>Watch email notifications for svn differences</h4> |
| <p> |
| Either subscribe to the project's |
| <a href="mail-lists.html#forrest-svn">svn mailing list</a> or monitor |
| it via one of the mail archives. This enables you to be immediately |
| up-to-date with changes to the repositories. The svn differences |
| (diffs) are automatically sent whenever a committer makes some |
| changes. |
| </p> |
| <a name="svn-find-break"></a> |
| <h4>Updating svn backwards to find where something broke</h4> |
| <p> |
| Sometimes the addition of new features will break something. Often it |
| is difficult to find where the break occurred and what caused it. |
| Updating your svn backwards will enable this. |
| </p> |
| <p> |
| Look at the svn@ mail list to guess which change might be the culprit, |
| e.g. svn revision 406862. |
| </p> |
| <pre class="code"> |
| Update backwards to just before the upgrade: |
| svn update -r 406861 |
| ... do 'build clean; build' and test. |
| |
| Go back further if it still doesn't work. |
| After success, start upgrading forward. |
| |
| Looking at the svn@ mailing list shows that |
| could jump forward past minor changes such as doc edits. |
| e.g. just after the upgrade: |
| svn update -r 406863 |
| ... do 'build clean; build' and test. |
| |
| If it still works, move a bit further on: |
| svn update -r 407260 |
| ... do 'build clean; build' and test. |
| |
| After finding the break, move back to head of trunk |
| svn update -r HEAD. |
| </pre> |
| <a name="svn-merge"></a> |
| <h4>Reverting Changes using SVN Merge</h4> |
| <p> |
| Two examples of using SVN Merge. |
| </p> |
| <pre class="code"> |
| $ svn merge -r 400:300 /site-author/content/xdocs/index.xml /site-author/content/xdocs/index.xml |
| |
| or |
| |
| $ svn merge -r 303:302 |
| |
| ... then commit as usual. |
| </pre> |
| <p> |
| More information can be found at |
| <a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2" rel="nofollow">Common |
| use-cases for merging</a> section of the Red Bean SVN Book. |
| </p> |
| <a name="svn-patch"></a> |
| <h4>Creating patches</h4> |
| <p> |
| See <a href="contrib.html#patch">instructions</a> for creating and |
| contributing patches. Make sure to do three things before creating the |
| patch: |
| </p> |
| <ul> |
| |
| <li>Do 'svn update' to be in sync with the repository in case someone else changed your files in SVN.</li> |
| |
| <li>Do 'svn status' to ensure that you are not including unnecessary changes.</li> |
| |
| <li>Do 'svn diff' to ensure that changes are what you expect.</li> |
| |
| </ul> |
| <p> |
| After creating the patch, open it with a text editor and review it. |
| </p> |
| <a name="tips-svn"></a> |
| <h4>Tips</h4> |
| <ul> |
| |
| <li> |
| Keep a copy of this book, or the online version, close at hand: |
| <a href="http://svnbook.red-bean.com/" rel="nofollow">Version Control with Subversion</a> |
| - the opensource SVN book. |
| </li> |
| |
| <li> |
| See all available branches and other repositories: |
| <a href="http://svn.apache.org/repos/asf/forrest/">http://svn.apache.org/repos/asf/forrest/</a> |
| </li> |
| |
| <li> |
| Use online repository browsers to quickly see past activity for |
| the files that you are working on: |
| <a href="http://svn.apache.org/viewcvs.cgi/forrest/trunk/">http://svn.apache.org/viewcvs.cgi/forrest/trunk/</a> |
| </li> |
| |
| <li> |
| Use 'svn log foo.xsl' for a summary of recent activity and to |
| see dates and revision numbers for changes. |
| </li> |
| |
| </ul> |
| <a name="edit"></a> |
| <h3 class="underlined_5">Editing content</h3> |
| <p> |
| See the <a href="docs_0_90/faq.html#edit-content">FAQ</a>. Basically any editor |
| can be used, because Forrest treats the editing of content as a separate |
| concern. Be sure to configure the editor to find local copies of DTDs. |
| </p> |
| <a name="code-style"></a> |
| <h4>Code style guidelines</h4> |
| <p> |
| Consistent code makes everyone's life easier. See the |
| <a href="http://cocoon.apache.org/community/committer.html">Apache |
| Cocoon tips</a>. We don't get too hung up on style, but those few |
| basic things are important. However we know that coding style is |
| mixed, so just follow the same style as that which exists in the file |
| you are editing. We can occasionally clean up later. |
| </p> |
| <p> |
| Don't change anything that is not necessary. Remember that people need |
| to be able to read the differences on the svn@forrest mailing list. |
| </p> |
| <a name="whitespace"></a> |
| <h4>Whitespace</h4> |
| <p> |
| For new files, use spaces instead of tabs (java files have four-space |
| indentation, xml files and other text files have two-space |
| indentation). |
| </p> |
| <p> |
| Don't let your editor automatically change the whitespace for existing |
| files. |
| </p> |
| <p> |
| We know that many files in SVN do not have consistent whitespace. This |
| issue is continually being addressed. Please don't attempt to rectify |
| whitespace mixed up with other changes. This makes the important |
| changes difficult to see. Occasionally committers will rectify |
| whitespace for a set of files, when they know that no-one else is |
| working on that set. |
| </p> |
| <div class="fixme"> |
| <div class="label">Fixme (open)</div> |
| <div class="content"> |
| The issues of whitespace and line endings needs to be very clearly |
| described. See some |
| <a href="http://marc.theaimsgroup.com/?l=forrest-dev&m=112450886218545" rel="nofollow">mail |
| discussion</a> references. |
| </div> |
| </div> |
| <a name="line-length"></a> |
| <h4>Line length</h4> |
| <p> |
| If each paragraph of an xml source document is one enourmous long |
| line, then it is extremely difficult to know the changes with the SVN |
| diffs. Developers and especially committers, need to be able to |
| efficiently review the changes. Fold long lines to a sensible |
| line-length (normally 80-characters wide but not more than 120 |
| characters). |
| </p> |
| <a name="review"></a> |
| <h4>Use 'forrest run' for immediate gratification</h4> |
| <p> |
| Edit documentation content and immediately view it in the browser. |
| When you are satisifed, then do 'forrest site' to ensure that the |
| whole documentation set hangs together and there are no broken |
| references. |
| </p> |
| <p> |
| In the dynamic 'forrest run' mode, you will get some feedback about |
| some xml validation errors. However, it is better to treat validation |
| as a separate concern. Use an xml editor or command-line tools such as |
| "xmllint". As a last resort, you can use 'forrest validate-xdocs'. |
| </p> |
| <a name="tips-edit"></a> |
| <h4>Tips</h4> |
| <ul> |
| |
| <li> |
| #### |
| </li> |
| |
| </ul> |
| <a name="sitemap"></a> |
| <h3 class="underlined_5">Understanding the Cocoon sitemap</h3> |
| <p> |
| The Cocoon sitemap is essential for Forrest developers. See some |
| introductions .... |
| </p> |
| <ul> |
| |
| <li> |
| <a href="docs_0_90/sitemap-ref.html">Forrest sitemap reference</a>.</li> |
| |
| <li>Introduction to Pipelines in this |
| <a href="docs_0_90/howto/howto-custom-html-source.html">How-to</a>.</li> |
| |
| <li>About |
| <a href="docs_0_90/project-sitemap.html">Forrest project sitemaps</a>.</li> |
| |
| <li> |
| <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Cocoon concepts</a>.</li> |
| |
| <li> |
| <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html">Cocoon sitemap</a>.</li> |
| |
| <li> |
| <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#Protocols">Cocoon protocols</a>, i.e. cocoon:/ and |
| cocoon:// and context:// and resource:// etc. and the |
| <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#file-url">file://</a> |
| </li> |
| |
| </ul> |
| <a name="debug"></a> |
| <h3 class="underlined_5">Debugging and profiling techniques</h3> |
| <a name="debug-logfiles"></a> |
| <h4>View logfiles</h4> |
| <p> |
| The log files in WEB-INF/logs are indispensible when it comes to |
| debugging sitemaps. While ERRORs will generally always print in the |
| log files, while you're debugging something you may find it useful to |
| also customize log output in the "logkit.xconf" in webapp/WEB-INF and |
| raise the level of some loggers to WARN. |
| </p> |
| <p> |
| This <a href="docs_0_90/faq.html#logs">FAQ</a> describes the location of the |
| Cocoon logfiles and their configuration. |
| </p> |
| <a name="debug-intermediate"></a> |
| <h4>View intermediate processing</h4> |
| <p> |
| Perhaps the easiest way to "debug" Forrest is to be aware of all the |
| processing steps between taking in the source and outputting the end |
| result. When you know these you can do 'forrest run' and request the |
| intermediate documents, such as |
| "<span class="codefrag">http://localhost:8888/body-index.html</span>" |
| which will return the intermediate processing of the body part of the |
| <span class="codefrag">/index.html</span> document, and |
| "<span class="codefrag">http://localhost:8888/index.xml</span>" |
| which will return the intermediate xml. |
| </p> |
| <p> |
| The techniques described below help you to be aware of the |
| intermediate processing steps. |
| </p> |
| <p> |
| The <a href="tools/forrestbar.html">ForrestBar</a> also provides easy access |
| to various internal data to assist with both understanding how the |
| processing works and with debugging. |
| </p> |
| <p> |
| See also the <a href="docs_0_90/faq.html#version">FAQ</a> |
| which explains access to version and all "properties" information. |
| </p> |
| <a name="debug-cocoon-profiler"></a> |
| <h4>Using Cocoon sitemap profiler</h4> |
| <p> |
| Cocoon provides a simple profiler to analyse itself. This enables us |
| to list the various sitemap pipelines and components that are being |
| used, how much time was used by each, whether each component uses the |
| Cocoon cache, and show the actual xml data. |
| </p> |
| <p> |
| Note that the profiler is not used by default. To switch it on, edit |
| <span class="codefrag">main/webapp/sitemap.xmap</span> and search for "profiler". |
| Follow the instructions there to replace the standard "map:pipe" |
| components with the profiling pipes. |
| </p> |
| <p> |
| Now start your application as normal using 'forrest run' and request |
| localhost:8888/index.html three or four times to populate the profiler |
| with data. |
| </p> |
| <p> |
| Now request the special uri localhost:8888/cprofile.html to see the |
| results. Start at the "index.html" request, then follow the |
| processing. (If the table is empty, then you either forgot to do some |
| requests before looking for results, or forgot to switch on the |
| profiler in sitemap.) |
| </p> |
| <p> |
| NOTE: Do not forget to turn off the profiler in |
| <span class="codefrag">main/webapp/sitemap.xmap</span> when finished. |
| </p> |
| <a name="debug-sitemap-exec"></a> |
| <h4>Using Cocoon sitemap execution logger</h4> |
| <p> |
| In main/webapp/WEB-INF/cocoon.xconf search for "sitemap |
| execution" and uncomment the component. For each sitemap component |
| that is executed, a message will go to WEB-INF/logs/sitemap-execution.log |
| </p> |
| <div class="fixme"> |
| <div class="label">Fixme (open)</div> |
| <div class="content"> |
| See <a href="https://issues.apache.org/jira/browse/FOR-1109">FOR-1109</a> - Not available in Cocoon-2.1 |
| </div> |
| </div> |
| <a name="debug-logtransformer"></a> |
| <h4>Using Cocoon LogTransformer</h4> |
| <p> |
| LogTransformers can be inserted in the sitemaps. This will write the |
| sax events at that point into a named log file. Here is an example |
| (the logfile will be written relative to this particular sitemap) ... |
| </p> |
| <pre class="code"> |
| |
| <map:match pattern="*.html"> |
| <map:generate src="sources/{1}.xml"/><strong> |
| |
| <map:transform type="log"> |
| <map:parameter name="logfile" value="my-1.log"/> |
| <map:parameter name="append" value="no"/> |
| </map:transform></strong> |
| |
| <map:transform src="stylesheets/source-to-table.xsl"/> |
| <map:transform src="stylesheets/table-to-page.xsl"/><strong> |
| |
| <map:transform type="log"> |
| <map:parameter name="logfile" value="my-2.log"/> |
| <map:parameter name="append" value="no"/> |
| </map:transform></strong> |
| |
| <map:transform src="stylesheets/page-to-html.xsl"/> |
| <map:serialize type="html"/> |
| </map:match> |
| |
| </pre> |
| <p> |
| Another use for this technique is when you are not sure which path is |
| being taken through the sitemap. Add various LogTransformers with |
| different filenames and see which one gets triggered. |
| </p> |
| <a name="debug-validation"></a> |
| <h4>Using Cocoon Validation Transformers</h4> |
| <p> |
| Validating Transformers can be inserted in the sitemaps to validate |
| the xml stream at that stage. Enables RELAX NG validation and W3C XML |
| Schema validation using Jing and Xerces. |
| </p> |
| <p> |
| The Validation Block is already added to Forrest and configured. To |
| use it simply add entries to your sitemap like this and followed by a serializer: |
| </p> |
| <pre class="code"> |
| ... |
| <map:transform type="validation-report" |
| src="{forrest:forrest.context}/resources/schema/relaxng/unstable/any.rng"/> |
| ... |
| </pre> |
| <p> |
| That can be added at any point where you want to validate the xml. |
| There is a default validation by reqesting the URI |
| '<span class="codefrag">*.validation.xml</span>' |
| e.g. <span class="codefrag">http://localhost:8888/index.validation.xml</span> |
| |
| </p> |
| <p> |
| See <a href="http://marc.theaimsgroup.com/?t=112541971900003">Pier's |
| note to cocoon-dev</a> and Cocoon documentation: |
| <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/684.html">ValidatingTransformer</a> |
| and |
| <a href="http://cocoon.zones.apache.org/daisy/documentation/components/1058/g2/691.html">ValidationReportTransformer</a>. |
| See <a href="http://cocoon.zones.apache.org/demos/21branch/samples/blocks/validation/welcome">Validation Block Samples</a> demos at the Cocoon zone. |
| See <a href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/validation/Validator.html">API</a> docs. |
| </p> |
| <a name="validate-intermediate"></a> |
| <h4>Validate all intermediate xml content</h4> |
| <p> |
| Add a text file at <span class="codefrag">src/documentation/conf/uris.txt</span> |
| which contains the line <span class="codefrag">linkmap.validation-start.xml</span> |
| (and any other extra URIs that you want Cocoon to process). |
| </p> |
| <p> |
| Add the line |
| <span class="codefrag">project.urifile=${project.home}/src/documentation/conf/uris.txt</span> |
| to your project's <span class="codefrag">forrest.properties</span> file. |
| </p> |
| <p> |
| After generating the complete site with '<span class="codefrag">forrest site</span>' |
| see the document <span class="codefrag">build/tmp/validation-reports.html</span> |
| |
| </p> |
| <a name="debug-java"></a> |
| <h4>Java code</h4> |
| <p> |
| There are two ways to debug your java code. The first is through |
| embedded logging, the second is by tracing the codes execution. |
| </p> |
| <p> |
| You may find <span class="codefrag">getLogger().debug()</span> useful for understanding |
| the processing that goes on. You can then open the page that will use |
| the selected code and use the log files mentioned above to look for |
| the information message. |
| </p> |
| <p> |
| To step through the java code you need to run forrest with Java |
| debugging turned on. The <span class="codefrag">forrest.jvmargs</span> property in |
| the <span class="codefrag">forrest.properties</span> file can be used to start forrest |
| in debug mode on a specific port. For example: |
| </p> |
| <pre class="code">forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</pre> |
| <a name="debug-links"></a> |
| <h4>Finding broken internal links</h4> |
| <p> |
| Do 'forrest site' to produce the whole documentation set. Cocoon will |
| report its progress and reveal any problems. This |
| <a href="docs_0_90/faq.html#build_msg_a">FAQ</a> explains the messages that |
| Cocoon sends to standard output. Broken links are also reported to a |
| special file, which also shows the source file containing the break. |
| The location of this file is reported when Cocoon starts. |
| </p> |
| <p> |
| Broken links are also reported in 'forrest run' mode. Use your mouse |
| to point to each link. The browser status bar will show "error:..." |
| instead of the actual URL. |
| </p> |
| <p> |
| The most common cause is that the entry is missing in the site.xml |
| configuration file or the link in your source document is not using |
| the correct name for the "site:..." value. Use the "localhost:8888/abs-menulinks" |
| resource or via <a href="tools/forrestbar.html">ForrestBar</a>. |
| </p> |
| <a name="tips-debug"></a> |
| <h4>Tips</h4> |
| <ul> |
| |
| <li> |
| Doing 'forrest -v' will provide verbose build messages to the |
| standard output. |
| </li> |
| |
| </ul> |
| <div class="note"> |
| <div class="label">Note</div> |
| <div class="content"> |
| The next two sections describe the configuration of profiling tools but |
| they are not integrated with the IDE. If you can figure out how to |
| properly configure them for integrated operation with the IDE, please |
| provide a documentation patch. |
| </div> |
| </div> |
| <a name="profile-yourkit"></a> |
| <h4>Profiling Forrest with YourKit</h4> |
| <p> |
| Assuming you have the YourKit software installed you simply need to do |
| two things to profile a particular Forrest Project. First, you need to |
| add *YourKit Home*\bin\win32 to your PATH environment variable - where |
| *YourKit Home* is the installation directory of that software. Next |
| you need to add the following to your forrest.properties file for the |
| project. |
| </p> |
| <pre class="code">forrest.jvmargs=-agentlib:yjpagent</pre> |
| <p> |
| You are now all set, simply type 'forrest run', then open up YourKit |
| and select "Connect to locally running profiled application...". If |
| you don't see the types of objects that you expected, check the |
| current filters - YourKit seems to filter out org.apache.* namespaces |
| by default. |
| </p> |
| <a name="profile-netbeans"></a> |
| <h4>Profiling Forrest with Netbeans</h4> |
| <p> |
| Assuming you have the Netbeans IDE installed, you simply need to do a |
| couple things to profile a particular Forrest Project. First, you need |
| to add *Netbeans Home*\profiler1\lib\deployed\jdk142\windows to your |
| path. Obviously, this needs to be slightly modified for a Unix |
| machine. Now, you need to add the following line to your |
| forrest.properties file for the project (replacing *NetbeansHome* with |
| the path to your install). |
| </p> |
| <pre class="code">forrest.jvmargs=-agentpath:C:\*NetbeansHome*\\profiler1\\lib\\deployed\\jdk15\\windows\\ |
| profilerinterface.dll=\C:\\*NetbeansHome*\\profiler1\\lib\\,5140</pre> |
| <p> |
| You are now all set, simply type 'forrest run', then open up the |
| Netbeans IDE with your Forrest project. Click Profile->Attach Profiler |
| and make selections appropriate to what you are trying to achieve. |
| </p> |
| <a name="find"></a> |
| <h3 class="underlined_5">Finding the relevant sources</h3> |
| <p> |
| You will need to be able to find which sources, sitemaps, stylesheets |
| are responsible for certain processing. |
| </p> |
| <a name="find-scenario-1"></a> |
| <h4>Scenario: How does i18n work</h4> |
| <p> |
| We will do a search for "i18n" to start with, then refine that after |
| exploring some of the sources. |
| </p> |
| <p> |
| The UNIX tools find, grep, and sed are very powerful. We need a helper |
| script, otherwise 'find' is going to report matches for the hidden |
| .svn files and also files in /build/ directories. |
| </p> |
| <pre class="code"> |
| echo "sed '/\.svn/d;/\/build\//d;/\/work\//d'" > ~/bin/exclude-find-svn |
| chmod +x ~/bin/exclude-find-svn</pre> |
| <p> |
| Now we will run find, use grep to search for the pattern in each file |
| and list the filenames. However, there is a stack of |
| forrest.properties files from the plugins, and there is i18n:text |
| being used in the viewHelper plugin, and some DTDs. So weed them out |
| ... |
| </p> |
| <pre class="code"> |
| cd /svn/asf/forrest-trunk |
| find . -type f | xargs grep -l "i18n" | ~/bin/exclude-find-svn \ |
| | grep -v "forrest.properties" | grep -v viewHelper | grep -v "\/schema\/"</pre> |
| <p> |
| The list of files shows that there is an FAQ about i18n, there are |
| various sitemaps in main/webapp/, some stylesheets in |
| main/webapp/skins/common/ and pelt, some other stylesheets in |
| main/webapp/resources/stylesheets/ ... we will look at the sitemaps |
| first. Use grep to list the actual matches and the filenames. |
| </p> |
| <pre class="code"> |
| cd main/webapp |
| grep i18n *.*</pre> |
| <p> |
| Shows that five sitemaps are involved in some way. Always start with |
| sitemap.xamp and forrest.xmap as they do initial processing and then |
| delegate to other sitemaps. Open each file in your editor, and search |
| within for each "i18n" match. See that the xslt transformer is |
| declared to use i18n, then further down the page the "skinit" pipeline |
| uses the i18n transformer only if i18n is switched on. |
| </p> |
| <a name="tips-find"></a> |
| <h4>Tips</h4> |
| <ul> |
| |
| <li> |
| #### |
| </li> |
| |
| </ul> |
| </div> |
| <a name="faqs"></a> |
| <h2 class="underlined_10">Frequently Asked Questions</h2> |
| <div class="section"> |
| <a name="faq-general"></a> |
| <h3 class="underlined_5">1 General issues</h3> |
| <a name="1.1+FAQ+1"></a> |
| <h4>1.1 FAQ 1</h4> |
| <p> |
| #### |
| </p> |
| <a name="faq-other"></a> |
| <h3 class="underlined_5">2 Other issues</h3> |
| <a name="2.1+FAQ+2.1"></a> |
| <h4>2.1 FAQ 2.1</h4> |
| <p> |
| ### |
| </p> |
| </div> |
| <a name="Tips"></a> |
| <h2 class="underlined_10">Tips</h2> |
| <div class="section"> |
| <p> |
| This is a collection of general tips that do not fit in the sections |
| above. |
| </p> |
| <a name="tip-howto"></a> |
| <h3 class="underlined_5">Explanations about howto topics on the mailing lists</h3> |
| <p> |
| Often there are useful discussions on the mailing lists which explain |
| how to do certain tasks. If you don't have time to summarise that and |
| add to this howto document, then please consider just adding a tip which |
| links to the email discussion. Later someone else can summarise. |
| </p> |
| </div> |
| <a name="References"></a> |
| <h2 class="underlined_10">References</h2> |
| <div class="section"> |
| <p> |
| These are some other documents that are useful for developers. |
| </p> |
| <ul> |
| |
| <li> |
| ### |
| </li> |
| |
| </ul> |
| </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-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a> |
| <br> |
| Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest |
| logos are trademarks of The Apache Software Foundation. |
| </div> |
| <!--+ |
| |end bottomstrip |
| +--> |
| </div> |
| </body> |
| </html> |
