You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Tim Williams <wi...@gmail.com> on 2005/08/20 14:48:40 UTC
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
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 <cr...@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"/>
>
>
>
Re: doc howto: be a developer (Was: svn commit: r233994)
Posted by David Crossley <cr...@apache.org>.
Tim Williams wrote:
> David Crossley wrote:
> > Tim Williams wrote:
> > > This is essentially what I was hoping the Developers Guide would
> > > eventually be.
> >
> > Tim refers to site-author/content/xdocs/developer-guide.xml
> >
> > We talked a while ago about providing such documentation
> > and today we both added our partially finished work.
>
> Sorry, I should have communicated better, when I changed laptops a
> while back my original doc got blasted and I had to recreate what I
> could remember.
Oh that is a shame. We need to get any work on
docs committed ASAP, even if it is half-finished.
Fixme notes are okay in published documents.
By the way, my comment was no criticism.
> > So now there is docs_0_80/howto/howto-dev.html
> >
> > > I'm in favor of just removing the developers guide.
> > > This is good stuff.
> >
> > We can merge the content. It seems to complement the howto.
>
> I'll remove mine as it's duplicative.
I have kept a copy so that i can reuse some of its text.
> > Are people happy with the Howto format for this document?
> >
> > The document will eventually grow too big, so some of the
> > topics should be split off into their own document.
> >
> > We should also revise the contrib.html document. It was
> > borrowed from Cocoon and some sections removed to get it
> > published quickly. It could refer to these howto docs.
>
> I like the content, but I think it should get promoted out of a how-to
> and somewhere on the main site. This is for a couple reasons: 1) it's
> not really a how-to in a typical sense (i.e. step-by-step instructions
> towards a specific end-state)
The more complex topics will eventually get
split out into separate documents. Some would be
step-by-step docs.
Sure, this high-level one could be a normal doc,
but list the intended audience, purpose, pre-requisites,
etc as sections.
> and 2) it isn't really version specific content,
Some of it could easily be version-specific.
However in general, i agree. We could probably denote
any variations.
> and 3) people wouldn't look for such a document in the
> product documentation, they'd look for it in the project
> documentation.
We can have howto documents at the top-level.
> It looks great...
Thanks. It is good to just get some the tips written
down somewhere.
-David
Re: doc howto: be a developer (Was: svn commit: r233994)
Posted by Tim Williams <wi...@gmail.com>.
On 8/22/05, David Crossley <cr...@apache.org> wrote:
> Tim Williams wrote:
> > This is essentially what I was hoping the Developers Guide would
> > eventually be.
>
> Tim refers to site-author/content/xdocs/developer-guide.xml
>
> We talked a while ago about providing such documentation
> and today we both added our partially finished work.
Sorry, I should have communicated better, when I changed laptops a
while back my original doc got blasted and I had to recreate what I
could remember.
> So now there is docs_0_80/howto/howto-dev.html
>
> > I'm in favor of just removing the developers guide.
> > This is good stuff.
>
> We can merge the content. It seems to complement the howto.
I'll remove mine as it's duplicative.
> Are people happy with the Howto format for this document?
>
> The document will eventually grow too big, so some of the
> topics should be split off into their own document.
>
> We should also revise the contrib.html document. It was
> borrowed from Cocoon and some sections removed to get it
> published quickly. It could refer to these howto docs.
I like the content, but I think it should get promoted out of a how-to
and somewhere on the main site. This is for a couple reasons: 1) it's
not really a how-to in a typical sense (i.e. step-by-step instructions
towards a specific end-state) and 2) it isn't really version specific
content, and 3) people wouldn't look for such a document in the
product documentation, they'd look for it in the project
documentation.
It looks great...
--tim
doc howto: be a developer (Was: svn commit: r233994)
Posted by David Crossley <cr...@apache.org>.
Tim Williams wrote:
> This is essentially what I was hoping the Developers Guide would
> eventually be.
Tim refers to site-author/content/xdocs/developer-guide.xml
We talked a while ago about providing such documentation
and today we both added our partially finished work.
So now there is docs_0_80/howto/howto-dev.html
> I'm in favor of just removing the developers guide.
> This is good stuff.
We can merge the content. It seems to complement the howto.
Are people happy with the Howto format for this document?
The document will eventually grow too big, so some of the
topics should be split off into their own document.
We should also revise the contrib.html document. It was
borrowed from Cocoon and some sections removed to get it
published quickly. It could refer to these howto docs.
-David