forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Williams <william...@gmail.com>
Subject Re: svn commit: r233994 - in /forrest/trunk/site-author/content/xdocs: docs_0_80/howto/howto-dev.xml docs_0_80/howto/index.xml site.xml
Date Sat, 20 Aug 2005 12:48:40 GMT
This is essentially what I was hoping the Developers Guide would
eventually be.  I'm in favor of just removing the developers guide. 
This is good stuff.
--tim

On 8/19/05, crossley@apache.org <crossley@apache.org> wrote:
> Author: crossley
> Date: Fri Aug 19 20:14:35 2005
> New Revision: 233994
> 
> URL: http://svn.apache.org/viewcvs?rev=233994&view=rev
> Log:
> Add the beginnings of "How be a Forrest developer".
> 
> Added:
>     forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml   (with props)
> Modified:
>     forrest/trunk/site-author/content/xdocs/docs_0_80/howto/index.xml
>     forrest/trunk/site-author/content/xdocs/site.xml
> 
> Added: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml
> URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml?rev=233994&view=auto
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml (added)
> +++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml Fri Aug 19
20:14:35 2005
> @@ -0,0 +1,453 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<!--
> +  Copyright 2002-2004 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 howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
> +  "http://forrest.apache.org/dtd/howto-v20.dtd">
> +<howto>
> +  <header>
> +    <title>How be a Forrest developer</title>
> +
> +    <version>0.1</version>
> +
> +    <abstract>
> +      This How-To provides some tips and procedures for being a
> +      Forrest developer.
> +    </abstract>
> +
> +    <last-modified-content-date date="2005-07-24" />
> +  </header>
> +  <audience title="Intended Audience">
> +<warning>
> +This document is under initial development.
> +</warning>
> +    <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>
> +    <p>
> +      See also the companion document "How to be a committer".
> +    </p>
> +  </audience>
> +
> +  <purpose title="Purpose">
> +    <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>
> +  </purpose>
> +
> +  <prerequisites title="Prerequisites">
> +    <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="site:v0.80//documentation/your-project">Using Forrest</a>
> +        document.
> +      </li>
> +      <li>
> +        You will enventually see that understanding of the Cocoon
> +        <a href="site:v0.80//documentation/developers/sitemap-ref">sitemap</a>
> +        is important. For the initial examples below, you can do without that.
> +        However please explore the sitemap soon.
> +      </li>
> +    </ul>
> +  </prerequisites>
> +
> +  <steps title="Development techniques and scenarios">
> +    <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>
> +
> +    <section id="svn">
> +      <title>Using Subversion</title>
> +      <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="site:v0.80//documentation/developers/build">instructions</a>
> +        for obtaining the Apache Forrest sources via SVN.
> +      </p>
> +
> +      <section id="multiple">
> +        <title>Multiple working copies</title>
> +        <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>
> +        <source>
> +[localhost]$ ls /svn/asf
> +forrest_07_branch
> +forrest-trunk
> +        </source>
> +      </section>
> +
> +      <section id="svn-email">
> +        <title>Watch email notifications for svn differences</title>
> +        <p>
> +          Either subscribe to the project's
> +          <a href="site:mail-lists/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>
> +      </section>
> +
> +      <section id="tips-svn">
> +        <title>Tips</title>
> +        <ul>
> +          <li>
> +            Keep a copy of this book, or the online version, close at hand:
> +            <a href="http://svnbook.red-bean.com/">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>
> +      </section>
> +    </section>
> +
> +    <section id="edit">
> +      <title>Editing content</title>
> +      <p>
> +        See the
> +        <a href="site:v0.80//documentation/faq/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>
> +
> +      <section id="code-style">
> +        <title>Code style guidelines</title>
> +        <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 a few basic things are important.
> +        </p>
> +      </section>
> +
> +      <section id="whitespace">
> +        <title>Whitespace</title>
> +        <p>
> +          Use spaces instead of tabs (java files have four-space indentation,
> +          xml files and other text files have two-space indentation).
> +          Don't let your editor automatically change the whitespace.
> +        </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.
> +        </p>
> +      </section>
> +
> +      <section id="line-length">
> +        <title>Line length</title>
> +        <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>
> +      </section>
> +
> +      <section id="review">
> +        <title>Use 'forrest run' for immediate gratification</title>
> +        <p>
> +          Edit 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>
> +      </section>
> +
> +      <section id="tips-edit">
> +        <title>Tips</title>
> +
> +        <ul>
> +          <li>
> +####
> +          </li>
> +        </ul>
> +      </section>
> +    </section>
> +
> +    <section id="debug">
> +      <title>Debugging techniques</title>
> +      <p>
> +        This <a href="site:v0.80//documentation/faq/logs">FAQ</a>
> +        describes the location of the Cocoon logfiles and their
> +        configuration.
> +      </p>
> +
> +      <section id="debug-links">
> +        <title>Finding broken internal links</title>
> +        <p>
> +          Do 'forrest site' to produce the whole documentation set.
> +          Cocoon will report its progress and reveal any problems.
> +          This <a href="site:v0.80//documentation/faq/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.
> +        </p>
> +      </section>
> +
> +      <section id="tips-debug">
> +        <title>Tips</title>
> +        <ul>
> +          <li>
> +            Doing 'forrest -v' will provide verbose build messages to the
> +            standard output.
> +          </li>
> +        </ul>
> +      </section>
> +    </section>
> +
> +    <section id="find">
> +      <title>Finding the relevant sources</title>
> +      <p>
> +        You will need to be able to find which sources, sitemaps, stylesheets
> +        are responsible for certain processing.
> +      </p>
> +      <section id="find-scenario-1">
> +        <title>Scenario: How does i18n work</title>
> +        <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>
> +
> +        <source>
> +echo "sed '/\.svn/d;/\/build\//d;/\/work\//d'" > ~/bin/exclude-find-svn
> +chmod +x ~/bin/exclude-find-svn</source>
> +        <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>
> +
> +        <source>
> +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\/"</source>
> +
> +        <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>
> +        <source>
> +cd main/webapp
> +grep i18n *.*</source>
> +        <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>
> +      </section>
> +
> +      <section id="tips-find">
> +        <title>Tips</title>
> +        <ul>
> +          <li>
> +####
> +          </li>
> +        </ul>
> +      </section>
> +    </section>
> +
> +<!-- template
> +    <section id="foo">
> +      <title>Foo</title>
> +      <p>
> +####
> +      </p>
> +      <section id="foo-1">
> +        <title>foo</title>
> +        <p>
> +####
> +        </p>
> +      </section>
> +
> +      <section id="tips-foo">
> +        <title>Tips</title>
> +        <ul>
> +          <li>
> +####
> +          </li>
> +        </ul>
> +      </section>
> +    </section>
> +-->
> +
> +  </steps>
> +
> +  <extension title="Extension">
> +    <p>
> +####
> +    </p>
> +  </extension>
> +
> +  <faqs id="faqs">
> +    <title>Frequently Asked Questions</title>
> +    <faqsection id="faq-general">
> +      <title>General issues</title>
> +      <faq id="faq-difference">
> +        <question>FAQ 1
> +        </question>
> +
> +        <answer>
> +          <p>
> +####
> +          </p>
> +        </answer>
> +      </faq>
> +    </faqsection>
> +
> +    <faqsection id="faq-other">
> +      <title>Other issues</title>
> +      <faq id="faq-2-1">
> +        <question>FAQ 2.1</question>
> +
> +        <answer>
> +          <p>
> +###
> +          </p>
> +        </answer>
> +      </faq>
> +    </faqsection>
> +  </faqs>
> +
> +  <tips title="Tips">
> +    <p>
> +      This is a collection of general tips that do not fit in the sections above.
> +    </p>
> +
> +    <section id="tip-1">
> +      <title>Tip 1</title>
> +
> +      <p>
> +###
> +      </p>
> +    </section>
> +  </tips>
> +
> +  <references title="References">
> +    <p>
> +      These are some other documents that are useful for developers.
> +    </p>
> +
> +    <ul>
> +      <li>
> +###
> +      </li>
> +    </ul>
> +  </references>
> +</howto>
> 
> Propchange: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/howto-dev.xml
> ------------------------------------------------------------------------------
>     svn:eol-style = native
> 
> Modified: forrest/trunk/site-author/content/xdocs/docs_0_80/howto/index.xml
> URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs_0_80/howto/index.xml?rev=233994&r1=233993&r2=233994&view=diff
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/docs_0_80/howto/index.xml (original)
> +++ forrest/trunk/site-author/content/xdocs/docs_0_80/howto/index.xml Fri Aug 19 20:14:35
2005
> @@ -1,6 +1,6 @@
>  <?xml version="1.0" encoding="UTF-8"?>
>  <!--
> -  Copyright 2002-2005 The Apache Software Foundation or its licensors,
> +  Copyright 2002-2004 The Apache Software Foundation or its licensors,
>    as applicable.
> 
>    Licensed under the Apache License, Version 2.0 (the "License");
> @@ -42,8 +42,15 @@
>      </section>
> 
>      <section>
> -      <title>Using Forrest</title>
> +      <title>Using and developing with Forrest</title>
> +      <p>
> +        You will soon see that there is not much distinction between
> +        users and developers.
> +      </p>
>        <ul>
> +        <li><link href="site:v0.80//howto/forrest-dev">How to be a Forrest
developer</link>
> +          - Describes tips and procedures for efficiently developing with Forrest.
> +        </li>
>          <li><link href="site:v0.80//howto/pdf-tab">How to create a PDF document
for each tab</link>
>            - Describes the generation of a PDF document for each
>            group of documents that is defined by a tab.
> 
> Modified: forrest/trunk/site-author/content/xdocs/site.xml
> URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/site.xml?rev=233994&r1=233993&r2=233994&view=diff
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/site.xml (original)
> +++ forrest/trunk/site-author/content/xdocs/site.xml Fri Aug 19 20:14:35 2005
> @@ -214,6 +214,7 @@
>          <howto label="How-To" href="howto/">
>            <overview label="Overview" href="index.html"/>
>            <write-howto label="Write a How-to" href="howto-howto.html"/>
> +          <forrest-dev label="Be a developer" href="howto-dev.html"/>
>            <asf-mirror label="Download mirror" href="howto-asf-mirror.html"/>
>            <pdf-tab label="Create tab PDF" href="howto-pdf-tab.html"/>
>            <editcss label="Edit CSS (WYSIWYG)" href="howto-editcss.html"/>
> 
> 
>

Mime
View raw message