Author: diwaker Date: Mon Aug 8 23:35:28 2005 New Revision: 230990 URL: http://svn.apache.org/viewcvs?rev=230990&view=rev Log: Automatic publish from forrestbot Added: forrest/site/committed-1.png (with props) forrest/site/committed.html (with props) forrest/site/committed.pdf (with props) Modified: forrest/site/docs_0_60/linking.pdf forrest/site/docs_0_60/your-project.pdf forrest/site/docs_0_70/linking.pdf forrest/site/docs_0_70/primer.pdf forrest/site/docs_0_70/your-project.pdf forrest/site/docs_0_80/faq.html forrest/site/docs_0_80/faq.pdf forrest/site/docs_0_80/faq.xml forrest/site/docs_0_80/howto/howto-buildPlugin.html forrest/site/docs_0_80/linking.pdf forrest/site/docs_0_80/primer.pdf forrest/site/dtdx/document-v12.pdf forrest/site/dtdx/document-v13.pdf forrest/site/dtdx/document-v20.pdf forrest/site/linkmap.pdf forrest/site/live-sites.html forrest/site/live-sites.pdf forrest/site/pluginDocs/plugins_0_80/pluginInfrastructure.html forrest/site/skin/basic.css forrest/site/skin/images/rc-b-l-15-1body-2menu-3menu.png forrest/site/skin/images/rc-b-r-15-1body-2menu-3menu.png forrest/site/skin/images/rc-b-r-5-1header-2tab-selected-3tab-selected.png forrest/site/skin/images/rc-t-l-5-1header-2searchbox-3searchbox.png forrest/site/skin/images/rc-t-l-5-1header-2tab-selected-3tab-selected.png forrest/site/skin/images/rc-t-l-5-1header-2tab-unselected-3tab-unselected.png forrest/site/skin/images/rc-t-r-15-1body-2menu-3menu.png forrest/site/skin/images/rc-t-r-5-1header-2searchbox-3searchbox.png forrest/site/skin/images/rc-t-r-5-1header-2tab-selected-3tab-selected.png forrest/site/skin/images/rc-t-r-5-1header-2tab-unselected-3tab-unselected.png forrest/site/versions/index.html Added: forrest/site/committed-1.png URL: http://svn.apache.org/viewcvs/forrest/site/committed-1.png?rev=230990&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/committed-1.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: forrest/site/committed.html URL: http://svn.apache.org/viewcvs/forrest/site/committed.html?rev=230990&view=auto ============================================================================== --- forrest/site/committed.html (added) +++ forrest/site/committed.html Mon Aug 8 23:35:28 2005 @@ -0,0 +1,285 @@ + + + + + + + +Becoming an Apache Forrest committer + + + + + + + + + +
+
+apache > forrest +
+
+ + + + +
+
+
+
+
+ +
+
+ +   +
+ +
+ +
+Font size: +   +   +   +
+

Becoming an Apache Forrest committer

+
This is a discussion of how users can progress to + become committers within the Apache Forrest project.
+ + + +

What is a committer?

+
+
+
Warning
+
+ This document is under development and does not yet represent + the view of our community. +
+
+
+
Note
+
Content is being gleaned from various current and past + discussions on the Forrest dev mailing list, in particular + this. + Further editing of this page is needed and would + be greatly appreciated.
+
+

Committer is an Apache term used to signify someone who is + committed to a particular project and who is invited to be part of + the core group within the project that ensures the project's vitality + (represented by the PMC, Project Management Committee).

+

One thing + that is sometimes hard to understand when you are new to the + Apache Way1 + is that we don't really care about code, it is the + community we care about. This is because a strong and healthy + community will usually generate strong and healthy code. As a result + of the Apache focus on community it is more important for people here + to discuss and explore within the community.

+
+ + +

Contributing to the Project - CoPDoC

+
+

The foundation of a project and how the community contributes + to it is known by the acronym CoPDoC:

+
    + +
  • (Co)mmunity - one must interact with others, and share vision + and knowledge
  • + +
  • (P)roject - a clear vision and consensus are needed
  • + +
  • (Do)cumentation - without it, the stuff remains only in the + minds of the authors
  • + +
  • (C)ode - discussion goes nowhere without code
  • + +
+
+ + +

Becoming a Committer

+
+

There is nothing at The Apache Software Foundation that says you must write code + in order to be a committer. Anyone who is supportive of the community + and works in any of the CoPDoC areas is a likely candidate for + committership.

+

Apache is a meritocracy. That is, once someone has + contributed sufficiently to any area of CoPDoC they can be voted in + as a committer. Being a committer does not mean you commit code, it + means you are committed to the project.

+

One of the key contributions + people can make to the community is through the support of a wide + user base by assisting users on the user list, writing user oriented + docs and ensuring the user viewpoint is understood by all developers. A + main idea behind being a committer is the ability to be a mentor and + to work cooperatively with your peers.

+

The following diagram shows the progression of a user to a + committer/mentor.

+

+committer path

+

Meritocracy progresses this way + ------------> ------------------------> +

+

Note that this is not a hierarchy, it is a progression from a + broad user base from which those that wish to to contribute to the + ongoing development of the project (again, through any aspect of + CoPDoC, not just coding) can become involved as developers. From + these developers are those who take on additional roles of mentoring + and more fully commit themselves to the project.

+
+ + +

Adding to the discussions

+
+

Discussion leads to a clearer community understanding of the + project's goals and objectives and also of how the community works.

+

+ Of course, there needs to be a balance between too much chat and not + enough code. If something is easy to do in code and does not impact + the overall product (such as a bug fix) then just go ahead and do it. + However, if something is to introduce a new feature, then it is best to + introduce your idea to the community via an email to the dev mail + list first. In this introduction you should outline why you want to + do something, how you propose to do it (pseudo code is a good way of + expressing this) and ask for comments. Any comments received will + help to fine tune the design and, in many cases, produce a quicker, + more elegant solution (this is the benefit of many eyes on a + solution).

+

The absence of comments from others does not + mean it is not a good idea, in fact the reverse is true, it means + nobody has any objection or anything to add. It is only if people + respond that you need to discuss further. Once the discussion reaches + consensus then coding can accelerate. Once you have implicit or explicit + approval for your contribution, just go ahead and do it. Be sure to + document what you have done whilst you are at it. Without + documentation (comments in code, mailing list discussion and user + docs) your code is next to useless - nobody knows it is there and + nobody knows how it works.

+

Online discussion is important for community building. + Offline discussion and one-to-one conversations deny the + community the chance to become involved and lead to solutions + that are not ideal. So please do as much discussion as possible + on the dev or user mailing list.

+
+ + +

References

+
+

+1 See more information about "the Apache Way" in the + ASF How it works.

+

+ Apache Forrest + project guidelines. +

+
+ +
+
 
+
+ + + Propchange: forrest/site/committed.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/committed.pdf URL: http://svn.apache.org/viewcvs/forrest/site/committed.pdf?rev=230990&view=auto ============================================================================== Binary file - no diff available. Propchange: forrest/site/committed.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Modified: forrest/site/docs_0_60/linking.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/linking.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_60/your-project.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/your-project.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_70/linking.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/linking.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_70/primer.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/primer.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_70/your-project.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_70/your-project.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_80/faq.html URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.html?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/docs_0_80/faq.html (original) +++ forrest/site/docs_0_80/faq.html Mon Aug 8 23:35:28 2005 @@ -347,13 +347,17 @@ 2.14. Does Forrest handle accents for non-English languages?
  • -2.15. How can I make Forrest properly clean up the build/site-directory? +2.15. How to use XML entities, for example string + replacement?
  • -2.16. How can I internationalise (i18n) my content? +2.16. How can I make Forrest properly clean up the build/site-directory?
  • -2.17. How can I include HTML content that is not to be skinned by Forrest? +2.17. How can I internationalise (i18n) my content? +
  • +
  • +2.18. How can I include HTML content that is not to be skinned by Forrest?
  • @@ -424,7 +428,7 @@ 5.1. What is the relationship between site.xml and book.xml?
  • -5.2. How do I use DocBook as the xml documentation format? +5.2. How do I use DocBook as the XML documentation format?
  • 5.3. How to report which version of Forrest is being used and the properties that are @@ -539,9 +543,9 @@ ^
    -

    If you are using the Apache Forrest xml document format - or DocBook or other xml document types, then you can use any text editor or even a - dedicated xml editor. You must ensure valid xml. See our configuration notes for various editors.

    +

    If you are using the Apache Forrest XML document format + or DocBook or other XML document types, then you can use any text editor or even a + dedicated XML editor. You must ensure valid XML. See our configuration notes for various editors.

    There are content management systems like Apache Lenya.

    Remember that Forrest can also use other source formats, such as OpenOffice.org docs or JSPWiki. Use the appropriate editor for those document types and ensure that the document @@ -559,7 +563,7 @@

    The site.xml configuration file is used for two different purposes: - defining the left-hand navigation menus, and as a method for defining references + defining the navigation menus, and as a method for defining references to be used when linking between documents. This file is fully explained in Menus and Linking. Here is a precis: @@ -601,10 +605,11 @@

    There are examples in the 'forrest seed site' and also the Forrest website documents - are included with the distribution (cd forrest/site-author; forrest run). + are included with the distribution (cd forrest/site-author; + forrest run).

    - +

    2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?

    ^ @@ -624,7 +629,7 @@

    This assumes that you use the site.xml method for your site structure and navigation, rather than the old book.xml method.

    - +

    2.5. How do I insert page breaks into documents?

    ^ @@ -642,10 +647,17 @@ skinconf.xml

    -
     .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
    -          margin-bottom: 0; page-break-after: always; } 
    +
     
    +          .pageBreakBefore { 
    +            margin-bottom: 0; 
    +            page-break-before: always; 
    +          } 
    +          .pageBreakAfter {
    +            margin-bottom: 0; 
    +            page-break-after: always; 
    +            } 
    - +

    2.6. How can I generate html-pages to show a 'clickable' email-address (of the author-element)?

    @@ -656,7 +668,7 @@ $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl and edit the "headers/authors" template.

    - +

    2.7. How do I link to raw files such as config.txt and brochure.pdf?

    ^ @@ -666,7 +678,7 @@ Upgrading to Apache Forrest 0.7 for all the details.

    - +

    2.8. Images don't display in PDFs. How do I fix this?

    ^ @@ -690,7 +702,7 @@

    Alternatively you can use JAI (Java Advanced Imaging API at - http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages + http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages

    @@ -698,7 +710,7 @@
    Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.
    - +

    2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the linked-to directory. How do I fix this?

    @@ -717,7 +729,7 @@ <map:redirect-to uri="manual/Introduction.html"/> </map:match>
    - +

    2.10. I need help with the interaction between tabs.xml and site.xml

    ^ @@ -727,7 +739,7 @@ See the tips.

    - +

    2.11. How can I change the default file name that Forrest will look for when I request a URL like http://myserver or http://myserver/mydir/ ?

    @@ -757,7 +769,7 @@
    - +

    2.12. How can I use a start-up-page other than index.html?

    ^ @@ -788,7 +800,7 @@
    - +

    2.13. How to use special characters in the labels of the site.xml file?

    ^ @@ -800,7 +812,7 @@

    See the XHTML Character Entities and see more discussion at Issue FOR-244.

    - +

    2.14. Does Forrest handle accents for non-English languages?

    ^ @@ -816,8 +828,8 @@
  • tildes: ã ñ Ä© õ Å©
  • -

    This is because sources for Forrest docs are xml documents, which can include any of - these, provided the encoding declared by the xml doc matches the actual encoding used in +

    This is because sources for Forrest docs are XML documents, which can include any of + these, provided the encoding declared by the XML doc matches the actual encoding used in the file. For example if you declare the default encoding:

    <?xml version="1.0" encoding="UTF-8"?>

    but the file content is actually using ISO-8859-1 then you will receive validation @@ -835,7 +847,7 @@

    [localhost]$ export LANG=en_US.UTF-8

    Of course the appropriate way to set the encoding depends on the editor/OS, but ultimately relys on the user preferences. So you can use the encoding you prefer, as long - as the encoding attribute of the xml declaration matches the actual encoding + as the encoding attribute of the XML declaration matches the actual encoding of the file. This means that if you are not willing to abandon ISO-8859-1 you can always use the following declaration instead:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    @@ -847,8 +859,24 @@ Schlabach and Alan Wood's Unicode resources.

    - -

    2.15. How can I make Forrest properly clean up the build/site-directory?

    + +

    2.15. How to use XML entities, for example string + replacement?

    +
    +^ +
    +
    +

    + A set of symbols is available. See the demonstration + in a fresh 'forrest seed' site (at samples/xml-entities.html). + For example, use "&myp-t;" to represent the + project name together with trademark symbol + "My Project Name™". + Avoid lengthy typing and potential spelling errors. +

    +
    + +

    2.16. How can I make Forrest properly clean up the build/site-directory?

    ^
    @@ -859,8 +887,8 @@

    To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest will delete all build directories before creating new content.

    - -

    2.16. How can I internationalise (i18n) my content?

    + +

    2.17. How can I internationalise (i18n) my content?

    ^
    @@ -873,8 +901,8 @@ by the Cocoon i18n Transformer. You can see an example of how it works in the above linked issue.

    - -

    2.17. How can I include HTML content that is not to be skinned by Forrest?

    + +

    2.18. How can I include HTML content that is not to be skinned by Forrest?

    ^
    @@ -895,9 +923,9 @@ </map:match> - +

    3. Technical

    - +

    3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I do?

    @@ -908,7 +936,7 @@ proxy.host and proxy.port accordingly (the port will default to port 80).

    - +

    3.2. How can I generate html-pages to show the revision tag of cvs?

    ^ @@ -921,7 +949,7 @@

    This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47 $

    - +

    3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include other additional ones.

    @@ -959,7 +987,7 @@ foo/** to match that.
    - +

    3.4. How do I stop Forrest breaking on links to external files that may not exist, like javadocs?

    @@ -970,7 +998,7 @@ cli.xconf Cocoon config file, and defining patterns for URLs to exclude.

    - +

    3.5. Some of my files are not being processed because they use common filenames.

    ^ @@ -986,7 +1014,7 @@ with this issue (FOR-217).

    - +

    3.6. What do the symbols and numbers mean when Forrest lists each document that it has built?

    @@ -1019,7 +1047,7 @@

    - +

    3.7. When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.

    @@ -1032,7 +1060,7 @@
    forrest -Dforrest.jvmargs=-Djava.awt.headless=true site

    See also Cocoon FAQ.

    - +

    3.8. The project logo that is generated from SVG is truncating my project name.

    @@ -1052,7 +1080,7 @@ SVG resources.

    - +

    3.9. How do i configure my favourite XML editor or parser to find the local Forrest DTDs?

    @@ -1062,7 +1090,7 @@

    Notes are provided for various tools at Using Catalog Entity Resolver for local DTDs.

    - +

    3.10. How to make the site look better and change its skin?

    ^ @@ -1074,7 +1102,7 @@

    See notes about configuration of the skins. Some projects may have special needs and can define their own skin.

    - +

    3.11. How do I enable XSP processing?

    ^ @@ -1122,7 +1150,7 @@

    See also the AddingXSPToForrest Wiki page.

    - +

    3.12. How do breadcrumbs work? Why don't they work locally?

    ^ @@ -1141,7 +1169,7 @@ are viewing the site locally, there is no domain and so there will be no extra breadcrumbs, only the ones that are specified in skinconf.xml.

    - +

    3.13. How do I make forrest run listen on a different port?

    ^ @@ -1157,9 +1185,9 @@

    - +

    4. Older version: 0.6

    - +

    4.1. Some of my files are not being processed because they use common filenames.

    ^ @@ -1175,9 +1203,9 @@ with this issue (FOR-217).

    - +

    5. General

    - +

    5.1. What is the relationship between site.xml and book.xml?

    ^ @@ -1191,8 +1219,8 @@ site.xml-generated menus aren't appropriate. See Menus and Linking.

    - -

    5.2. How do I use DocBook as the xml documentation format?

    + +

    5.2. How do I use DocBook as the XML documentation format?

    ^
    @@ -1232,12 +1260,12 @@

    You can also use a mixture of the two methods, some handled automatically by Forrest and some directly using DocBook stylesheets. You can also have a mixture of source files as "document-v*" DTD and DocBook.

    -

    Ensure that the document type declaration in your xml instance is well specified. Use a +

    Ensure that the document type declaration in your XML instance is well specified. Use a public identifier. The DTD will then be properly resolved by Forrest. If you need to use different DTDs, then see Using Forrest for configuration guidance.

    - +

    5.3. How to report which version of Forrest is being used and the properties that are set?

    @@ -1250,7 +1278,7 @@ watch the build messages. Doing 'forrest -v' will provide verbose build messages.

    - +

    5.4. Where are the log files to find more infomation about errors?

    ^ @@ -1269,7 +1297,7 @@

    Doing 'forrest -v' will provide verbose build messages to the standard output.

    - +

    5.5. How to help?

    ^ @@ -1280,7 +1308,7 @@ particularly from newcomers—often, close proximity blinds software developers to faults that are obvious to everyone else. Don't be shy!

    - +

    5.6. How to contribute a patch?

    ^ Modified: forrest/site/docs_0_80/faq.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_80/faq.xml URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.xml?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/docs_0_80/faq.xml (original) +++ forrest/site/docs_0_80/faq.xml Mon Aug 8 23:35:28 2005 @@ -52,9 +52,9 @@ value you set it to is dependant on your JVM, but something like ANT_OPTS=-Xmx500M will probably work.

    2. Content Creation
    2.1. What tools can be used to edit the content? -

    If you are using the Apache Forrest xml document format - or DocBook or other xml document types, then you can use any text editor or even a - dedicated xml editor. You must ensure valid xml. See our configuration notes for various editors.

    +

    If you are using the Apache Forrest XML document format + or DocBook or other XML document types, then you can use any text editor or even a + dedicated XML editor. You must ensure valid XML. See our configuration notes for various editors.

    There are content management systems like Apache Lenya.

    Remember that Forrest can also use other source formats, such as OpenOffice.org docs or JSPWiki. Use the appropriate editor for those document types and ensure that the document @@ -66,7 +66,7 @@

    The site.xml configuration file is used for two different purposes: - defining the left-hand navigation menus, and as a method for defining references + defining the navigation menus, and as a method for defining references to be used when linking between documents. This file is fully explained in Menus and Linking. Here is a precis: @@ -104,7 +104,8 @@

    There are examples in the 'forrest seed site' and also the Forrest website documents - are included with the distribution (cd forrest/site-author; forrest run). + are included with the distribution (cd forrest/site-author; + forrest run).

    2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?

    Add the following entries to your site.xml file:

    @@ -132,8 +133,15 @@ the following to the extra-css element in your projects skinconf.xml

    - .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter { - margin-bottom: 0; page-break-after: always; } + + .pageBreakBefore { + margin-bottom: 0; + page-break-before: always; + } + .pageBreakAfter { + margin-bottom: 0; + page-break-after: always; + }
    2.6. How can I generate html-pages to show a 'clickable' email-address (of the author-element)?

    You would override @@ -157,7 +165,7 @@ $FORREST/lib/optional/jimi-1.0.jar.

    Alternatively you can use JAI (Java Advanced Imaging API at - http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages + http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages

    Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.
    2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the @@ -226,8 +234,8 @@ <li>diereses: ä ë ï ö ü</li> <li>tildes: ã ñ ĩ õ ũ</li> </ul> - <p>This is because sources for Forrest docs are xml documents, which can include any of - these, provided the encoding declared by the xml doc matches the actual encoding used in + <p>This is because sources for Forrest docs are XML documents, which can include any of + these, provided the encoding declared by the XML doc matches the actual encoding used in the file. For example if you declare the default encoding:</p> <source xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?></source> <p>but the file content is actually using ISO-8859-1 then you will receive validation @@ -245,7 +253,7 @@ <source xml:space="preserve">[localhost]$ export LANG=en_US.UTF-8</source> <p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but ultimately relys on the user preferences. So you can use the encoding you prefer, as long - as the <code>encoding</code> attribute of the xml declaration matches the actual encoding + as the <code>encoding</code> attribute of the XML declaration matches the actual encoding of the file. This means that if you are not willing to abandon ISO-8859-1 you can always use the following declaration instead:</p> <source xml:space="preserve"><?xml version="1.0" encoding="ISO-8859-1"?></source> @@ -256,13 +264,23 @@ <p>Here are some references which explain further: <link href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten Schlabach</link> and <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode resources</link>. </p> - </section><section id="cleanSite"><title>2.15. How can I make Forrest properly clean up the build/site-directory? +
    2.15. How to use XML entities, for example string + replacement? +

    + A set of symbols is available. See the demonstration + in a fresh 'forrest seed' site (at samples/xml-entities.html). + For example, use "&myp-t;" to represent the + project name together with trademark symbol + "My Project Name™". + Avoid lengthy typing and potential spelling errors. +

    +
    2.16. How can I make Forrest properly clean up the build/site-directory?

    Forrest for performance reasons doesn't clean out the build/site-directory each time you compile your project. This usually doesn't matter during development but might become a problem in a production environment.

    To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest will delete all build directories before creating new content.

    -
    2.16. How can I internationalise (i18n) my content? +
    2.17. How can I internationalise (i18n) my content?

    The i18n features of Forrest are still under development (as of 0.7) however there are some features available. For example, navigation menus can be i18n'd (see fresh-site for an example). Currently, work is underway to @@ -271,7 +289,7 @@

    All internationalistation of tokens in, for example, the skins and the menus, is carried out by the Cocoon i18n Transformer. You can see an example of how it works in the above linked issue.

    -
    2.17. How can I include HTML content that is not to be skinned by Forrest? +
    2.18. How can I include HTML content that is not to be skinned by Forrest?

    To server, for example, a legacy HTML site add something like the following to your projects sitemap:

    @@ -455,7 +473,7 @@ will be used to generate the menu. This supplement is useful in situations where site.xml-generated menus aren't appropriate. See Menus and Linking.

    -
    5.2. How do I use DocBook as the xml documentation format? +
    5.2. How do I use DocBook as the XML documentation format?

    There are two ways. Forrest has a simplifiedDocbook plugin which can transform the DocBook format into the Forrest "xdocs" format on-the-fly and then render that as normal Forrest documents. Be aware that the stylesheet that does this @@ -491,7 +509,7 @@

    You can also use a mixture of the two methods, some handled automatically by Forrest and some directly using DocBook stylesheets. You can also have a mixture of source files as "document-v*" DTD and DocBook.

    -

    Ensure that the document type declaration in your xml instance is well specified. Use a +

    Ensure that the document type declaration in your XML instance is well specified. Use a public identifier. The DTD will then be properly resolved by Forrest. If you need to use different DTDs, then see Using Forrest for configuration guidance.

    Modified: forrest/site/docs_0_80/howto/howto-buildPlugin.html URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/howto-buildPlugin.html?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/docs_0_80/howto/howto-buildPlugin.html (original) +++ forrest/site/docs_0_80/howto/howto-buildPlugin.html Mon Aug 8 23:35:28 2005 @@ -313,6 +313,11 @@
  • Testing a Plugin +
  • Releasing a Plugin @@ -437,7 +442,8 @@ cd [path_to_forrest]/plugins ant seedPlugin -

    The above ant target will ask you the name of the plugin and will +

    The above ant target will ask you the name of the plugin and some + additional information such as a breif description and will build a minimal plugin directory structure and configuration. You will need to customise these files to build your plugin.

    @@ -462,16 +468,8 @@

    You now have a skeleton plugin project. However, it doesn't do anything useful yet. Now is a good time to edit some of the files provided.

    -
    -
    Note
    -
    - For plugins intended to be held at forrest.apache.org please - adjust the skinconf.xml etc to be in accordance with the other - forrest plugins. See notes below. -
    -

    Here are some general notes:

    - +
    status.xml

    This file is used to track changes to the plugin project and to manage lists of things that still need to be done. @@ -481,23 +479,30 @@

    As you work on the plugin you should record all major changes in this file so that it can then be used as a changelog for your plugin.

    - +
    forrest.properties

    This file defines many configuration parameters for Forrest. It does not need to be customised in most cases. However, see for more details.

    - +
    src/documentation/skinconf.xml

    This configures the skin for your plugins documentation. There are some items that need to be configured in here, for example, the copyright information. The file is heavily commented so probably best to read through it, changing what you need to.

    - +
    Documentation

    It is also a good idea to start writing the documentation at this stage. The above process created a very simple plugin documentation site for you. All you have to do is add the content.

    - + +
    Component Configuraiton
    +

    If your plugin needs to provide additional Cocoon configuration + in the form of an xconf, or if some of the components + you are using need a configuraiton file (such as a JTidy config) + you should place them in a conf directory in the root + of your plugin.

    +
    Style notes for plugins hosted at forrest.apapche.org

    After seeding a new plugin, copy the configuration from an @@ -505,7 +510,7 @@ Copy src/documentation/skinconf.xml and src/documentation/content/xdocs/images/project-logo.gif

    - +

    Edit the Plugin sitemap file(s)

    The plugin xmap file is a Cocoon sitemap that is mounted at a strategic place in the Forrest pipeline. It is in this file @@ -524,7 +529,7 @@ all development work on Forrest, you will find the developer mailing list a very good resource (check the archives before posting, please).

    - +

    Components, Actions and Resources

    If your plugin uses any components (i.e. generators, transformers or serializers), actions or resources they must @@ -539,13 +544,13 @@ {forrest:plugins}/PLUGIN_NAME instead of {realpath:/}.

    See the examples below for more details.

    - +

    Create the Necessary Resource Files

    Fixme (rdg)
    Discuss the XSL files and other such resources
    - +

    Create Samples in the Documentation

    Plugin documentation should provide (as a minimum) an index page that provides an overview and a set of samples that demonstrate @@ -555,7 +560,7 @@ and tabs.xml configuration files.

    Try to provide a sample for all the major functions of your plugin and document any configuration that is available.

    - +

    Testing a Plugin

    Since your documentation for the plugin illustrates all of its functionality, you can use that site for testing the plugin. However, you @@ -581,9 +586,24 @@ as writing your tests.

    Ensure that your sitemaps are robust and handle matches for files in sub-directories, as well as those at the root level.

    - + +

    Testing During Development

    +

    In the current plugin system plugins are not used from their + src directories, they must first be deployed locally. To do this + run the command ant local-deploy.

    +
    +
    Note
    +
    The test target will do this deployment auotmatically for you. + You need only run it manually if you wish to test the plugin whilst + editing content in a live Forrest instance.
    +
    +

    In most cases you can locally deploy a plugin without having to + restart Forrest. However, if your plugin changes any configuration + files in the conf directory you will, most likely, have + to restart Forrest to see these changes.

    +

    Releasing a Plugin

    - +

    Register the Plugin with Apache Forrest

    Fixme (rdg)
    @@ -594,7 +614,7 @@
    Describe making a request of Forrest devs for inclusion
    - +

    Deploying the Plugin

    To deploy the plugin so that others can use it, it must be made available as a zip from the URL indicated in the @@ -623,29 +643,29 @@ that your only deploy working plugins. This adds a little time to the deploy cycle, but we feel the peace of mind is worth it.

  • - +

    Examples

    This section will provide some example plugins to help illustrate the steps discussed above.

    - +

    Input Plugin

    Fixme (RDG)
    Discuss OpenOffice.org plugin here
    - +

    Output Plugin

    Fixme (RDG)
    Discuss s5 plugin here
    - +

    Internal Plugin

    Fixme (RDG)
    Discuss IMSManifest plugin here
    - +

    Further Reading

    - +

    Summarise the Entire Process

    Fixme (rdg)
    Modified: forrest/site/docs_0_80/linking.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/linking.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/docs_0_80/primer.pdf URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/primer.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/dtdx/document-v12.pdf URL: http://svn.apache.org/viewcvs/forrest/site/dtdx/document-v12.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/dtdx/document-v13.pdf URL: http://svn.apache.org/viewcvs/forrest/site/dtdx/document-v13.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/dtdx/document-v20.pdf URL: http://svn.apache.org/viewcvs/forrest/site/dtdx/document-v20.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/linkmap.pdf URL: http://svn.apache.org/viewcvs/forrest/site/linkmap.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/live-sites.html URL: http://svn.apache.org/viewcvs/forrest/site/live-sites.html?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/live-sites.html (original) +++ forrest/site/live-sites.html Mon Aug 8 23:35:28 2005 @@ -334,6 +334,17 @@ DisCountDracula: bargains/deals on various products and services + +
  • +Central Florida Astronomical + Society: The Central Florida Astronomical Society, Inc. + (CFAS) is a 501(c)(3) organization operating in the Greater Orlando Metropolitan + area and surrounding communities.
  • + +
  • +uml2svg: an + XSLT-based tool for converting XMI-compliant UML Diagrams into + SVG.
  • Modified: forrest/site/live-sites.pdf URL: http://svn.apache.org/viewcvs/forrest/site/live-sites.pdf?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/pluginDocs/plugins_0_80/pluginInfrastructure.html URL: http://svn.apache.org/viewcvs/forrest/site/pluginDocs/plugins_0_80/pluginInfrastructure.html?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/pluginDocs/plugins_0_80/pluginInfrastructure.html (original) +++ forrest/site/pluginDocs/plugins_0_80/pluginInfrastructure.html Mon Aug 8 23:35:28 2005 @@ -278,7 +278,11 @@
     [plugin_name]
       |
    -  |-- config files (xmap, skinconf etc.)
    +  |-- plugin control files (xmap etc.)
    +  |
    +  |-- conf
    +  |   |
    +  |   `-- cocoon and component config files (e.g. *.xconf, jtidy)
       |
       |-- resources
           |
    @@ -286,9 +290,9 @@
           |   |
           |   |-- catalog.xcat
           |   |
    -      |   |-- dtd (DTDs etc.)
    +      |   `-- dtd (DTDs etc.)
           |
    -      |-- stylesheets (XSLs etc.)
    +      `-- stylesheets (XSLs etc.)
     

    The IMS Manifest Plugin

    Modified: forrest/site/skin/basic.css URL: http://svn.apache.org/viewcvs/forrest/site/skin/basic.css?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/skin/basic.css (original) +++ forrest/site/skin/basic.css Mon Aug 8 23:35:28 2005 @@ -50,22 +50,32 @@ padding: 5px 10px; } .note .content { - padding: 5px 10px; background: #F0F0FF; color: black; line-height: 120%; font-size: 90%; + padding: 5px 10px; } .warning .label { background: #C00; color: white; + font-weight: bold; + padding: 5px 10px; } .warning .content { background: #FFF0F0; color: black; + line-height: 120%; + font-size: 90%; + padding: 5px 10px; } .fixme .label { background: #C6C600; + font-weight: bold; + padding: 5px 10px; +} +.fixme .content { + padding: 5px 10px; } /** Modified: forrest/site/skin/images/rc-b-l-15-1body-2menu-3menu.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-b-l-15-1body-2menu-3menu.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-b-r-15-1body-2menu-3menu.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-b-r-15-1body-2menu-3menu.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-b-r-5-1header-2tab-selected-3tab-selected.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-b-r-5-1header-2tab-selected-3tab-selected.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-l-5-1header-2searchbox-3searchbox.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-l-5-1header-2searchbox-3searchbox.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-l-5-1header-2tab-selected-3tab-selected.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-l-5-1header-2tab-selected-3tab-selected.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-l-5-1header-2tab-unselected-3tab-unselected.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-l-5-1header-2tab-unselected-3tab-unselected.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-r-15-1body-2menu-3menu.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-r-15-1body-2menu-3menu.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-r-5-1header-2searchbox-3searchbox.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-r-5-1header-2searchbox-3searchbox.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-r-5-1header-2tab-selected-3tab-selected.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-r-5-1header-2tab-selected-3tab-selected.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/skin/images/rc-t-r-5-1header-2tab-unselected-3tab-unselected.png URL: http://svn.apache.org/viewcvs/forrest/site/skin/images/rc-t-r-5-1header-2tab-unselected-3tab-unselected.png?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== Binary files - no diff available. Modified: forrest/site/versions/index.html URL: http://svn.apache.org/viewcvs/forrest/site/versions/index.html?rev=230990&r1=230989&r2=230990&view=diff ============================================================================== --- forrest/site/versions/index.html (original) +++ forrest/site/versions/index.html Mon Aug 8 23:35:28 2005 @@ -39,8 +39,8 @@
  • Project
  • -
  • -Versioned Docs +
  • +Versioned Docs
  • Plugins