forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From twilli...@apache.org
Subject svn commit: r233556 - /forrest/trunk/site-author/content/xdocs/developer-guide.xml
Date Fri, 19 Aug 2005 20:44:59 GMT
Author: twilliams
Date: Fri Aug 19 13:44:43 2005
New Revision: 233556

URL: http://svn.apache.org/viewcvs?rev=233556&view=rev
Log:
The beginnings of a Forrest Developers Guide.

Added:
    forrest/trunk/site-author/content/xdocs/developer-guide.xml   (with props)

Added: forrest/trunk/site-author/content/xdocs/developer-guide.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/developer-guide.xml?rev=233556&view=auto
==============================================================================
--- forrest/trunk/site-author/content/xdocs/developer-guide.xml (added)
+++ forrest/trunk/site-author/content/xdocs/developer-guide.xml Fri Aug 19 13:44:43 2005
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Developers Guide</title>
+  </header>
+  <body>
+    <section id="purpose">
+      <title>Purpose</title>
+      <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>
+    </section>
+    
+    <section id="general">
+      <title>General</title>
+      <p>Before getting to those really practical answers, here are some really general
thoughts.  I      
+      </p>
+      <p><strong>General Coding</strong>. In general, consider that many
hands have likely touched the code that
+        you are about to patch before you.  It looks like it was developed by a single developer,
doesn't
+        it?  The goal is to keep it that way.  Be considerate and try to follow the coding
style 
+        precedence that has been set.  
+      </p>
+      <p><strong>Community</strong>. Community is more important than code.
 While we hope that developers will
+        read this guide and reduce the technical learning curve to developing in Forrest,
above all 
+        we hope that you'll come away remembering that.  While the following document is
about Forrest
+        committership, it is also useful in understanding what we mean by community.
+        <link href="http://forrest.apache.org/committed.html">http://forrest.apache.org/committed.html</link>
+      </p>
+    </section>
+    
+    <section id="environment">
+      <title>Development Environment</title>
+      <p>There is no *proper* dev environment. It really depends on your personal
+        preferences. The most important thing is to have a good XML editor. If you don't
already
+        have strong personal preferences on XML and/or Java editors, you may want to consider
the 
+        information below.
+      </p>
+      <section id="xml">
+        <title>XML</title>
+        <p>JEdit, vi, Eclipse, and TextPad are among some of the editors used by various
developers.
+        </p>
+        <p>If your editor of choice doesn't validate XML, then most XML validation
issues can be
+          discovered using <code>forrest validate-xdocs</code> and, if that doesn't
work, then
+          try using 'xmllint' if available.
+        </p>
+      </section>
+      <section id="java">
+        <title>Java</title>
+        <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>
+      </section>
+      <section id="svn">
+        <title>Subversion</title>
+        <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.
+          <link href="http://svnbook.red-bean.com/">http://svnbook.red-bean.com</link>
is a must.
+        </p>
+        
+        <p>e.g. 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>
+      </section>
+      
+    </section>
+    
+    <section id="debugging">
+      <title>Debugging</title>
+      <p>There is no watch/trace/debug type functionlaity. Cocoon probably provides
some such 
+        functionality, but it is generally found unnecessary.
+      </p>
+      <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 "http://localhost:8888/body-index.xml"
+        which will return the intermediate processing of the body of the document.
+      </p>
+      <p><strong>Sitemap.</strong> The log files in WEB-INF/logs are indispensible
when it comes
+        to debugging sitemaps.  While true 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.  For more information, 
+        see: <link href="http://forrest.apache.org/docs_0_70/faq.html#logs">
+        http://forrest.apache.org/docs_0_70/faq.html#logs</link>
+      </p>
+      <p><strong>Java Code.</strong> Since there's really no way to "trace"
the java code through
+        the pipeline process, you may find <code>getLogger().debug()</code> 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>
+    </section>
+    
+    <section id="whitespace">
+      <title>Whitespace, line breaks, and tabs</title>
+      <p>These are simple, but essential, topics for contributing to Forrest.  
+      </p>
+      <ul>
+        <li>Thou shalt leave no trailing whitespace in your files.</li>
+        <li>Thou shalt convert all tabs to whitespace.</li>
+        <li>Thou shalt break lines at reasonable line length.</li>
+        <li>...</li>
+      </ul>
+      <p>To reduce the chances of you making poor whitespace, line break, or tab mistakes,
you 
+        should use the features of the text editor of your choice.  Many text editors have
options 
+        like: "Strip trailing whitespaces from lines when saving" and "Convert new tabs to
spaces."
+        It's helpful to everyone if you go ahead and configure your editor to prevent you
from making
+        lazy mistakes in the future.        
+      </p>
+      <fixme author="twilliams">I don't understand the whole dos2unix || unix2dos line
endings thing so 
+        someone that does needs to help clearly explain that properly. (See commented references
for 
+        source material) 
+      </fixme>
+      <!--
+      source material for line endings.  
+      http://marc.theaimsgroup.com/?t=111850048800001&r=1&w=2 
+      -->
+    </section>
+    
+    <section id="forrest">
+      <title>Forrest Oddities</title>
+      <p>This section is here to explain some randomly difficult peices of Forrest
development that 
+        didn't fit cleanly in any of the categories above.
+      </p>
+      
+      <section id="protocols">
+        <title>Protocols</title>
+        <fixme author="twilliams">Placeholder for cocoon:/ vs. cocoon://, context://,
resource://, and schemes 
+        site:, lm:, etc., once we understand them all;)</fixme>
+      </section>
+      
+      <section id="pipelines">
+        <title>Pipelines</title>
+        <p>There is an absolutely wonderful introduction to Cocoon Pipelines for Forrest
hidden in this 
+          <link href="http://forrest.apache.org/docs_0_80/howto/howto-custom-html-source.html">How-To</link>.
 
+          For a non-Cocooner trying to work with Forrest, it is a *must-read*.
+        </p>
+      </section>
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/site-author/content/xdocs/developer-guide.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message