You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by David Crossley <cr...@apache.org> on 2005/05/05 04:40:57 UTC
whitespace changes (Was: svn commit: r167890)
If people want to do many whitespace changes, then please
try to keep them as separate commits to real content changes.
Committers have a duty to monitor the commits. When the
changes are mixed with whitespace changes, it is very
difficult to see what changed.
--David
> Author: ferdinand
> Date: Tue May 3 03:06:05 2005
> New Revision: 167890
>
> URL: http://svn.apache.org/viewcvs?rev=167890&view=rev
> Log:
> Added faqs defaultFileName,cleanSite,defaultStartPage
>
> Modified:
> forrest/trunk/site-author/content/xdocs/docs/faq.xml
>
> Modified: forrest/trunk/site-author/content/xdocs/docs/faq.xml
> URL: http://svn.apache.org/viewcvs/forrest/trunk/site-author/content/xdocs/docs/faq.xml?rev=167890&r1=167889&r2=167890&view=diff
> ==============================================================================
> --- forrest/trunk/site-author/content/xdocs/docs/faq.xml (original)
> +++ forrest/trunk/site-author/content/xdocs/docs/faq.xml Tue May 3 03:06:05 2005
> @@ -18,142 +18,91 @@
> <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "http://forrest.apache.org/dtd/faq-v12.dtd" [
> <!ENTITY s '<code>site.xml</code>'>
> ]>
> -
> <faqs title="Frequently Asked Questions">
> -
> <part id="getting_started">
> <title>Getting Started and Building Forrest</title>
> <faq id="overview">
> - <question>
> - Where can I read an overview about how to work with Forrest?
> - </question>
> + <question> Where can I read an overview about how to work with Forrest? </question>
> <answer>
> - <p>
> - See the <link href="site:your-project">Using Forrest</link> guide.
> - </p>
> + <p> See the <link href="site:your-project">Using Forrest</link> guide. </p>
> </answer>
> </faq>
> -
> <faq id="requirements">
> - <question>
> - What are the system requirements for Forrest?
> - </question>
> + <question> What are the system requirements for Forrest? </question>
> <answer>
> - <p>
> - Forrest includes everything necessary to build and run, except
> - of course for Java. In addition to all the Cocoon JARs, Forrest
> - includes and uses its own version of Ant. Java 1.4+ is required.
> - </p>
> + <p> Forrest includes everything necessary to build and run, except of course for Java. In
> + addition to all the Cocoon JARs, Forrest includes and uses its own version of Ant. Java
> + 1.4+ is required. </p>
> </answer>
> </faq>
> -
> <faq id="cvs">
> - <question>
> - The old xml-forrest CVS code repository seems to be stale. What happened?
> - </question>
> + <question> The old xml-forrest CVS code repository seems to be stale. What happened? </question>
> <answer>
> - <p>
> - Forrest switched from a CVS code repository to SVN (subversion)
> - code repository. The old CVS repository is not kept current.
> - </p>
> + <p> Forrest switched from a CVS code repository to SVN (subversion) code repository. The old
> + CVS repository is not kept current. </p>
> </answer>
> </faq>
> <faq id="svn">
> - <question>
> - How can I use SVN to keep up to date with the latest codebase?
> - </question>
> + <question> How can I use SVN to keep up to date with the latest codebase? </question>
> <answer>
> - <p>
> - Follow these <link href="site:build">Building Forrest</link> notes.
> - </p>
> - <p>
> - The <link href="site:your-project">Using Forrest</link> guide provides
> - further step-by-step assistance in getting started with Forrest for your project.
> - </p>
> + <p> Follow these <link href="site:build">Building Forrest</link> notes. </p>
> + <p> The <link href="site:your-project">Using Forrest</link> guide provides further
> + step-by-step assistance in getting started with Forrest for your project. </p>
> </answer>
> </faq>
> <faq id="single-document">
> - <question>
> - What is the best way to generate "standalone documents" using Forrest?
> - </question>
> + <question> What is the best way to generate "standalone documents" using Forrest? </question>
> <answer>
> - <p>
> - forrest site -Dproject.start-uri=myfile.pdf
> - </p>
> - <p>
> - The <link href="site:your-project">Using Forrest</link> guide provides
> - further step-by-step assistance in getting started with Forrest for your project.
> - </p>
> + <p> forrest site -Dproject.start-uri=myfile.pdf </p>
> + <p> The <link href="site:your-project">Using Forrest</link> guide provides further
> + step-by-step assistance in getting started with Forrest for your project. </p>
> </answer>
> </faq>
> -
> -
> <faq id="cygwin_mutex_error">
> - <question>
> - When running <code>./build.sh</code> in cygwin, I get an error:
> - <code>cygpath.exe: *** can't create title mutex, Win32 error 6</code>.
> - </question>
> + <question> When running <code>./build.sh</code> in cygwin, I get an error: <code>cygpath.exe:
> + *** can't create title mutex, Win32 error 6</code>. </question>
> <answer>
> - <p>
> - This
> - <link href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
> - to be a bug in cygwin</link>. Please use the .bat script instead.
> - </p>
> + <p> This <link href="http://issues.cocoondev.org/secure/ViewIssue.jspa?key=FOR-10">appears
> + to be a bug in cygwin</link>. Please use the .bat script instead. </p>
> </answer>
> </faq>
> -
> <faq id="maxmemory">
> - <question>
> - How can I specify the amount of memory to be used by Java?
> - </question>
> + <question> How can I specify the amount of memory to be used by Java? </question>
> <answer>
> - <p>
> - There are two ways to control this. If you get an OutOfMemoryError when Cocoon is generating pages,
> - see the first paragraph. If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
> - files), see the second paragraph.
> - </p>
> - <p>
> - The <code>maxmemory</code> property in the <code>forrest.properties</code> file controls how much
> - memory Cocoon uses. Like many other properties you can copy them from the default configuration at
> - <code>src/core/fresh-site/forrest.properties</code>
> - </p>
> - <p>
> - Set the <code>ANT_OPTS</code> environment variable before you run forrest. The exact value you set
> - it to is dependant on your JVM, but something like <code>ANT_OPTS=-Xmx500M</code> will probably work.
> - </p>
> + <p> There are two ways to control this. If you get an OutOfMemoryError when Cocoon is
> + generating pages, see the first paragraph. If you get an OutOfMemoryError when outside of
> + Cocoon (e.g., copying raw files), see the second paragraph. </p>
> + <p> The <code>maxmemory</code> property in the <code>forrest.properties</code> file controls
> + how much memory Cocoon uses. Like many other properties you can copy them from the default
> + configuration at <code>src/core/fresh-site/forrest.properties</code>
> + </p>
> + <p> Set the <code>ANT_OPTS</code> environment variable before you run forrest. The exact
> + value you set it to is dependant on your JVM, but something like
> + <code>ANT_OPTS=-Xmx500M</code> will probably work. </p>
> </answer>
> </faq>
> </part>
> -
> -
> -
> <part id="content_faqs">
> - <title>Content Creation</title><faq id="edit-content">
> + <title>Content Creation</title>
> + <faq id="edit-content">
> <question>What tools can be used to edit the content?</question>
> <answer>
> - <p>If you are using the Apache Forrest xml
> - <link href="site:dtd-docs">document format</link> 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
> - <link href="site:catalog">configuration notes</link>
> - for various editors.
> - </p>
> - <p>There are content management systems like
> - <link href="ext:lenya">Apache Lenya</link>.
> - </p>
> - <p>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 stucture is consistent.
> - Forrest can also use "html" as the source format, in which case you
> - can use text editors or "html editors" such as the one provided
> - with the Mozilla web browser.
> - </p>
> - </answer>
> - </faq><faq id="PDF-output">
> - <question>How can I generate one pdf-file out of
> - the whole site or selected pages of the site?</question>
> + <p>If you are using the Apache Forrest xml <link href="site:dtd-docs">document format</link>
> + 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 <link href="site:catalog"
> + >configuration notes</link> for various editors. </p>
> + <p>There are content management systems like <link href="ext:lenya">Apache Lenya</link>. </p>
> + <p>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
> + stucture is consistent. Forrest can also use "html" as the source format, in which case
> + you can use text editors or "html editors" such as the one provided with the Mozilla web
> + browser. </p>
> + </answer>
> + </faq>
> + <faq id="PDF-output">
> + <question>How can I generate one pdf-file out of the whole site or selected pages of the site?</question>
> <answer>
> - <p>Add the following entries to your site.xml file:</p>
> + <p>Add the following entries to your site.xml file:</p>
> <source><![CDATA[
> <about tab="home" label="About" href="">
> ...
> @@ -161,155 +110,136 @@
> <all_sitePDF label="Full PDF" href="wholesite.pdf"/>
> ...
> </about>]]></source>
> - <p>
> - In this case the menu labeled "About" will have 2 new items:
> - "Full PDF" and "Full HTML". (See also
> - <link href="site:howto/pdf-tab">How to create a PDF document for each tab</link>.)
> - </p>
> - <p>
> - This assumes that you use the
> - <link href="site:linking">site.xml</link> method for your site
> - structure and navigation, rather than the old book.xml method.
> - </p>
> - </answer>
> + <p> In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML".
> + (See also <link href="site:howto/pdf-tab">How to create a PDF document for each
> + tab</link>.) </p>
> + <p> This assumes that you use the <link href="site:linking">site.xml</link> method for your
> + site structure and navigation, rather than the old book.xml method. </p>
> + </answer>
> </faq>
> <faq id="pageBreaks">
> <question>How do I insert page breaks into documents?</question>
> <answer>
> - <p>Page breaks do not make a great deal of sense in HTML documents
> - intended for display on a screen. However, PDF documents are intended
> - for printing and therefore page breaks can be important.</p>
> - <p>To insert a page break in a PDF document simply add
> - <em>pageBreakBefore</em> or <em>pageBreakAfter</em> to the class
> - attribute of a section.</p>
> - <p>If you want these classes to be processed in your HTML documents
> - as well you should add the following to the <code>extra-css</code>
> - element in your projects <code>skinconf.xml</code></p>
> - <source>
> - .pageBreakBefore {
> - margin-bottom: 0;
> - page-break-before: always;
> - }
> -
> - .pageBreakAfter {
> - margin-bottom: 0;
> - page-break-after: always;
> - }
> - </source>
> + <p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
> + screen. However, PDF documents are intended for printing and therefore page breaks can be
> + important.</p>
> + <p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> or
> + <em>pageBreakAfter</em> to the class attribute of a section.</p>
> + <p>If you want these classes to be processed in your HTML documents as well you should add
> + the following to the <code>extra-css</code> element in your projects
> + <code>skinconf.xml</code>
> + </p>
> + <source> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
> + margin-bottom: 0; page-break-after: always; } </source>
> </answer>
> </faq>
> <faq id="clickable-email-address">
> - <question>How can I generate html-pages to show a
> - 'clickable' email-address (of the author-element)?</question>
> - <answer>
> - <p>You would override <code>
> - $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code>
> - and edit the "headers/authors" template.
> - </p>
> - </answer>
> + <question>How can I generate html-pages to show a 'clickable' email-address (of the
> + author-element)?</question>
> + <answer>
> + <p>You would override <code>
> + $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
> + "headers/authors" template. </p>
> + </answer>
> </faq>
> -
> <faq id="link_raw">
> - <question>How do I link to raw files such as config.txt and brochure.pdf?
> - </question>
> + <question>How do I link to raw files such as config.txt and brochure.pdf? </question>
> <answer>
> - <p>
> - Place them in the <code>src/documentation/content</code> directory
> - and they will get copied into the output tree where you can link to
> - them. You can also have sub-directories there to reflect your xdocs
> - tree. See the samples documents when you 'forrest seed' a new
> - project for a demonstration of this ability.
> - </p>
> - <p>
> - For example, if
> - <code>src/documentation/content/xdocs/tools/downloads.xml</code>
> - has a <code><link href="tool.zip"></code> then put
> - <code>tool.zip</code> in the
> - <code>src/documentation/content/tools/</code> directory.
> - </p>
> - <p>
> - See the explanation and demonstration of "linking" in your local
> - 'forrest seed' site.
> + <p> Place them in the <code>src/documentation/content</code> directory and they will get
> + copied into the output tree where you can link to them. You can also have sub-directories
> + there to reflect your xdocs tree. See the samples documents when you 'forrest seed' a new
> + project for a demonstration of this ability. </p>
> + <p> For example, if <code>src/documentation/content/xdocs/tools/downloads.xml</code> has a
> + <code><link href="tool.zip"></code> then put <code>tool.zip</code> in the
> + <code>src/documentation/content/tools/</code> directory. </p>
> + <p> See the explanation and demonstration of "linking" in your local 'forrest seed' site.
> </p>
> </answer>
> </faq>
> -
> <faq id="pdf_images">
> <question>Images don't display in PDFs. How do I fix this?</question>
> <answer>
> - <p>
> - Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
> - for rendering PDFs. FOP cannot handle all image types natively, and
> - requires third-party jars to be added. FOP natively handles BMP, GIF,
> - JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
> - (via Batik!and PNG (see below). For details, see
> - <link href="http://xml.apache.org/fop/graphics.html">FOP Graphics
> - formats</link>
> + <p> Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link> for rendering
> + PDFs. FOP cannot handle all image types natively, and requires third-party jars to be
> + added. FOP natively handles BMP, GIF, JPG, TIFF and EPS (with a few limitations). FOP can
> + also handle SVG (via Batik!and PNG (see below). For details, see <link
> + href="http://xml.apache.org/fop/graphics.html">FOP Graphics formats</link>
> </p>
> <p>To get PNGs working in PDFs with Jimi:</p>
> <ol>
> - <li>Download Jimi from
> - <link href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
> + <li>Download Jimi from <link href="http://java.sun.com/products/jimi/"
> + >http://java.sun.com/products/jimi/</link>
> + </li>
> <li>Unpack the Jimi distribution and copy JimiProClasses.zip to
> - <code>$FORREST/lib/optional/jimi-1.0.jar</code>.</li>
> + <code>$FORREST/lib/optional/jimi-1.0.jar</code>.</li>
> </ol>
> - <p>Alternatively you can use JAI (Java Advanced Imaging API at
> - http://java.sun.com/products/java-media/jai). For more
> - info, see
> - <link href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics
> - Packages</link>
> + <p>Alternatively you can use JAI (Java Advanced Imaging API at
> + http://java.sun.com/products/java-media/jai). For more info, see <link
> + href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics Packages</link>
> </p>
> - <note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
> - Forrest.</note>
> + <note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.</note>
> </answer>
> </faq>
> -
> <faq id="index.html">
> - <question>
> - The tab link in my site incorrectly assumes that 'index.html' is present in
> - the linked-to directory. How do I fix this?
> - </question>
> + <question> The tab link in my site incorrectly assumes that 'index.html' is present in the
> + linked-to directory. How do I fix this? </question>
> <answer>
> - <p>
> - In <code>tabs.xml</code>, use @href instead of @dir, and omit the
> - trailing '/'. Which file to serve is then a concern of the sitemap.
> - For example, if the "User Manual" tab should link to
> - <code>manual/Introduction.html</code> then
> - <code>tabs.xml</code> should contain:
> - </p>
> + <p> In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing '/'. Which
> + file to serve is then a concern of the sitemap. For example, if the "User Manual" tab
> + should link to <code>manual/Introduction.html</code> then <code>tabs.xml</code> should
> + contain: </p>
> <source><![CDATA[
> <tab label="User Manual" href="manual"/>]]></source>
> - <p>
> - and add this rule to the sitemap:
> - </p>
> + <p> and add this rule to the sitemap: </p>
> <source><![CDATA[
> <map:match pattern="manual">
> <map:redirect-to uri="manual/Introduction.html"/>
> </map:match>]]></source>
> - </answer>
> + </answer>
> + </faq>
> + <faq id="defaultFileName">
> + <question> How can I change the default file name that Forrest will look for when I request a
> + URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code>? </question>
> + <answer>
> + <p>Change the setting <![CDATA[<default-filename>index.html</default-filename>]]> in
> + cli.xconf.</p>
> + </answer>
> + </faq>
> + <faq id="defaultStartPage">
> + <question> How can I use a start-up-page other than index.html? </question>
> + <answer>
> + <p>Forrest by default assumes that the first page (home page) of your site is named
> + index.html. Which is good because most web servers are configured to look for index.html
> + when you call a url like http://myserver.</p>
> + <p>Like most settings in Forrest however this can be changed, for example when you want your
> + start-up-page for a CD-based documentation project to be named 'start.html'. </p>
> + <p>To change the start page of a site:</p>
> + <ol>
> + <li>Open the file 'sitemap.xmap' in your project's src-directory.</li>
> + <li>Add the following code just before the end of the pipelines-element:<![CDATA[
> + <map:pipeline>
> + <map:match pattern="">
> + <map:redirect-to uri="start.html" />
> + </map:match>
> + </map:pipeline>
> + ]]></li>
> + <li>Name the uri-attribute whatever you'd like your start page to be.</li>
> + <li>Don't forget to create that page and refer to it in your site.xml!</li>
> + </ol>
> + </answer>
> </faq>
> -
> -
> <faq id="label-entity">
> - <question>
> - How to use special characters in the labels of the site.xml file?
> - </question>
> + <question> How to use special characters in the labels of the site.xml file? </question>
> <answer>
> - <p>
> - Use the numeric values for character entities.
> - For example, rather than using
> - <code><![CDATA[ö]]></code> use
> - <code><![CDATA[ö]]></code>
> - </p>
> - <p>
> - See the
> - <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</link>
> - and see more discussion at
> - <link href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>.
> + <p> Use the numeric values for character entities. For example, rather than using
> + <code><![CDATA[ö]]></code> use <code><![CDATA[ö]]></code>
> </p>
> + <p> See the <link
> + href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities"
> + >XHTML Character Entities</link> and see more discussion at <link
> + href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>. </p>
> </answer>
> </faq>
> -
> <faq id="encoding">
> <question>Does Forrest handle accents for non-English languages?</question>
> <answer>
> @@ -319,107 +249,88 @@
> <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 the file.
> - For example if you declare the default encoding:</p>
> + <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><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></source>
> - <p>but the file content is actually using ISO-8859-1 then you will
> - receive validation errors, especially if
> - you include some non-ASCII characters.</p>
> - <p>
> - This situation is commonly encountered when you edit the templates
> - created by <code>forrest seed</code> with your favorite
> - (probably localized) editor without paying attention to the encoding,
> - or when you create a new file
> - and simply copy the headers from another file.
> - </p>
> - <p>Although UTF-8 is an encoding well-suited for most languages,
> - it is not usually the default in popular editors or systems.
> - In UNIX-like systems, most popular editors can handle different encodings to
> - write the file in disk. With some editors the encoding of the file is preserved, while with others the default
> - is used regardless of the original encoding. In most cases the encoding used to write files
> - can be controlled by setting the environment variable <code>LANG</code>
> - to an appropriate value, for instance:
> - </p>
> + <p>but the file content is actually using ISO-8859-1 then you will receive validation
> + errors, especially if you include some non-ASCII characters.</p>
> + <p> This situation is commonly encountered when you edit the templates created by
> + <code>forrest seed</code> with your favorite (probably localized) editor without paying
> + attention to the encoding, or when you create a new file and simply copy the headers from
> + another file. </p>
> + <p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
> + default in popular editors or systems. In UNIX-like systems, most popular editors can
> + handle different encodings to write the file in disk. With some editors the encoding of
> + the file is preserved, while with others the default is used regardless of the original
> + encoding. In most cases the encoding used to write files can be controlled by setting the
> + environment variable <code>LANG</code> to an appropriate value, for instance: </p>
> <source>[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 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>
> + <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
> + 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><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>]]></source>
> - <p>Another option is to use "character entities" such as
> - <code><![CDATA[ö]]></code> (ö) or the numeric form
> - <code><![CDATA[ö]]></code> (ö).
> - </p>
> - <p>Another related issue is that your webserver needs to send http
> - headers with the matching charset definitions to the html page.
> - </p>
> - <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>
> + <p>Another option is to use "character entities" such as <code><![CDATA[ö]]></code>
> + (ö) or the numeric form <code><![CDATA[ö]]></code> (ö). </p>
> + <p>Another related issue is that your webserver needs to send http headers with the matching
> + charset definitions to the html page. </p>
> + <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>
> + </answer>
> + </faq>
> + <faq id="cleanSite">
> + <question> How can I make Forrest properly clean up the build/site-directory? </question>
> + <answer>
> + <p>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.</p>
> + <p>To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest
> + will delete all build directories before creating new content. </p>
> </answer>
> </faq>
> </part>
> -
> <part id="technical">
> - <title>Technical</title>
> -
> -
> + <title>Technical</title>
> <faq id="proxy_config">
> - <question>I'm behind a proxy and it's preventing Plugins from
> - being downloaded, what should I do?</question>
> + <question>I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
> + do?</question>
> <answer>
> - <p>You can configure the proxy in the <code>forrest.properties</code>
> - file. Set the <code>proxy.host</code> and <code>proxy.port</code>
> - accordingly (the port will default to port 80).</p>
> + <p>You can configure the proxy in the <code>forrest.properties</code> file. Set the
> + <code>proxy.host</code> and <code>proxy.port</code> accordingly (the port will default
> + to port 80).</p>
> </answer>
> </faq>
> -
> <faq id="CVS_revison_tags">
> - <question>How can I generate html-pages to show the
> - revision tag of cvs?</question>
> + <question>How can I generate html-pages to show the revision tag of cvs?</question>
> <answer>
> - <p>If you have:<code><version>$Revision: 1.30
> - $</version></code>The '1.30' will be extracted and
> - displayed at the bottom of the page as "version 1.30". See for
> - example the bottom of the
> - <link href="site:your-project"> Using Forrest</link> document.</p>
> - <p>This technique could also be used for a modification date with
> - $Date: 2004/01/15 08:52:47 $</p>
> + <p>If you have:<code><version>$Revision: 1.30
> + $</version></code>The '1.30' will be extracted and
> + displayed at the bottom of the page as "version 1.30". See for example the
> + bottom of the <link href="site:your-project"> Using Forrest</link> document.</p>
> + <p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
> + $</p>
> </answer>
> </faq>
> -
> <faq id="cli-xconf">
> - <question>
> - How to control the processing of URIs by Cocoon, e.g. exclude
> - certain URIs, include other additional ones.
> - </question>
> + <question> How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
> + other additional ones. </question>
> <answer>
> - <p>
> - Forrest uses a configuration file to control the processing
> - done by the Apache Cocoon command-line called cli.xconf
> - </p>
> - <p>
> - Your project can supply its own <code>cli.xconf</code>
> - and define patterns for URIs to exclude. There are also
> - other powerful configuration features.
> - </p>
> - <p>
> - This means creating a directory <code>src/documentation/conf</code>
> - (or wherever <code>${forrest.conf-dir}</code> points) and copying
> - <code>$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</code> to it.
> - Declare the location of this file in the forrest.properties
> - configuration, e.g.
> - <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
> - </p>
> - <p>
> - Then edit
> - cli.xconf, and add any exclude sections that you require. The
> - default cli.xconf ignores directory links and links containing
> - 'apidocs' or starting with 'api/':
> + <p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
> + command-line called cli.xconf </p>
> + <p> Your project can supply its own <code>cli.xconf</code> and define patterns for URIs to
> + exclude. There are also other powerful configuration features. </p>
> + <p> This means creating a directory <code>src/documentation/conf</code> (or wherever
> + <code>${forrest.conf-dir}</code> points) and copying
> + <code>$FORREST_HOME/main/webapp/WEB-INF/cli.xconf</code> to it. Declare the location of
> + this file in the forrest.properties configuration, e.g.
> + <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
> </p>
> + <p> Then edit cli.xconf, and add any exclude sections that you require. The default
> + cli.xconf ignores directory links and links containing 'apidocs' or starting with 'api/': </p>
> <source><![CDATA[
> ....
> <!-- Includes and excludes can be used to limit which URLs are rendered -->
> @@ -430,56 +341,38 @@
> ]]></strong><![CDATA[
> <uri src="favicon.ico"/>
> </cocoon>]]></source>
> - <p>This is just an example, and you should modify it appropriately for
> - your site.</p>
> - <note>
> - Wildcards may be used. These are a powerful feature of Cocoon's
> - <link href="site:sitemap-ref">sitemap</link>.
> - For example, <strong>foo/*</strong> would match
> - <code>foo/bar</code>, but not <code>foo/bar/baz</code>
> - — use <strong>foo/**</strong> to match that.
> - </note>
> + <p>This is just an example, and you should modify it appropriately for your site.</p>
> + <note> Wildcards may be used. These are a powerful feature of Cocoon's <link
> + href="site:sitemap-ref">sitemap</link>. For example, <strong>foo/*</strong> would match
> + <code>foo/bar</code>, but not <code>foo/bar/baz</code> — use
> + <strong>foo/**</strong> to match that. </note>
> </answer>
> </faq>
> -
> <faq id="ignoring_javadocs">
> - <question>
> - How do I stop Forrest breaking on links to external files that may not
> - exist, like javadocs?
> - </question>
> + <question> How do I stop Forrest breaking on links to external files that may not exist, like
> + javadocs? </question>
> <answer>
> - <p>
> - This can be done by overriding the
> - <link href="#cli-xconf"><code>cli.xconf</code></link>
> - Cocoon config file, and defining patterns for URLs to exclude.
> - </p>
> + <p> This can be done by overriding the <link href="#cli-xconf">
> + <code>cli.xconf</code>
> + </link> Cocoon config file, and defining patterns for URLs to exclude. </p>
> </answer>
> </faq>
> -
> <faq id="claimed_patterns">
> - <question>Some of my files are not being processed because they use
> - common filenames.
> - </question>
> + <question>Some of my files are not being processed because they use common filenames. </question>
> <answer>
> - <p>
> - Certain patterns are claimed by the default sitemaps for
> - special processing. These include:
> - <code>site, changes, todo, faq, images, my-images, skinconf,
> - community, howto</code>
> - </p>
> - <p>
> - Sometimes there are workarounds, e.g. faq.html or faq-interview.html
> - would fail, but interview-faq.html would be fine.
> - In future versions of Forrest we will attempt to deal with this issue
> - (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
> + <p> Certain patterns are claimed by the default sitemaps for special processing. These
> + include: <code>site, changes, todo, faq, images, my-images, skinconf, community,
> + howto</code>
> + </p>
> + <p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
> + interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
> + with this issue (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
> </p>
> </answer>
> </faq>
> -
> <faq id="build_msg_a">
> - <question>What do the symbols and numbers mean when Forrest lists each
> - document that it has built?
> - </question>
> + <question>What do the symbols and numbers mean when Forrest lists each document that it has
> + built? </question>
> <answer>
> <source><![CDATA[
> * [56/0] 6.281s 23.0Kb index.html
> @@ -490,209 +383,156 @@
> * [50/0] 1.222s 20.2Kb dreams.html
> * [0/0] 0.535s 11.1Kb dreams.pdf
> ...]]></source>
> - <p>
> - Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
> - Column 2 is the number of links that were gathered from that page.
> - Column 3 is the time taken.
> - Column 4 is the page size.
> - </p>
> + <p> Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped). Column 2 is the
> + number of links that were gathered from that page. Column 3 is the time taken. Column 4 is
> + the page size. </p>
> </answer>
> </faq>
> -
> -
> -
> <faq id="headless_operation">
> - <question>
> - 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.
> - </question>
> + <question> 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. </question>
> <answer>
> - <p>
> - If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
> - operation by running Forrest with the <code>forrest.jvmarg</code>
> - parameter set to <code>-Djava.awt.headless=true</code>, like this:
> - </p>
> + <p> If you are using JDK 1.4.0 or newer, you can enable <em>headless</em> operation by
> + running Forrest with the <code>forrest.jvmarg</code> parameter set to
> + <code>-Djava.awt.headless=true</code>, like this: </p>
> <source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
> - <p>
> - See also
> - <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>.
> - </p>
> + <p> See also <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html"
> + >Cocoon FAQ</link>. </p>
> </answer>
> </faq>
> -
> <faq id="catalog">
> - <question>
> - How do i configure my favourite XML editor or parser to find the
> - local Forrest DTDs?
> - </question>
> + <question> How do i configure my favourite XML editor or parser to find the local Forrest
> + DTDs? </question>
> <answer>
> - <p>
> - Notes are provided for various tools at
> - <link href="site:catalog">Using Catalog Entity Resolver for
> - local DTDs</link>.
> - </p>
> + <p> Notes are provided for various tools at <link href="site:catalog">Using Catalog Entity
> + Resolver for local DTDs</link>. </p>
> </answer>
> </faq>
> <faq id="skin">
> - <question>
> - How to make the site look better and change its skin?
> - </question>
> + <question> How to make the site look better and change its skin? </question>
> <answer>
> - <p>
> - There are <link href="site:skins">default skins</link> provided,
> - which are configurable and so should meet the needs of most projects.
> - The aim is to provide many capabilities so that extra skins are not
> - needed.
> - </p>
> - <p>
> - See notes about
> - <link href="site:your-project/skins">configuration</link> of the skins.
> - Some projects may have special needs and can define their
> - <link href="site:your-project/new-skin">own skin</link>.
> - </p>
> + <p> There are <link href="site:skins">default skins</link> provided, which are configurable
> + and so should meet the needs of most projects. The aim is to provide many capabilities so
> + that extra skins are not needed. </p>
> + <p> See notes about <link href="site:your-project/skins">configuration</link> of the skins.
> + Some projects may have special needs and can define their <link
> + href="site:your-project/new-skin">own skin</link>. </p>
> </answer>
> </faq>
> -
> <faq id="xsp">
> <question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</question>
> <answer>
> - <p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.
> - </p>
> - <p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
> - XSP:</p>
> + <p>First consider whether your needs would be better met by Cocoon itself, rather than
> + Forrest. </p>
> + <p>That said, there are valid reasons for wanting programmatically generated content, so
> + here is how to enable XSP:</p>
> <ol>
> - <li>Download
> - <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java">jdtcore-2.1.0.jar</link>,
> - and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib directory
> - (or lib/core/ directory in the source
> - distribution).</li>
> - <li><p>
> - Add the following generator definition in the map:generators section
> - of your <link href="site:project-sitemap">project sitemap</link></p>
> + <li>Download <link
> + href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&content-type=application/java"
> + >jdtcore-2.1.0.jar</link>, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib
> + directory (or lib/core/ directory in the source distribution).</li>
> + <li>
> + <p> Add the following generator definition in the map:generators section of your <link
> + href="site:project-sitemap">project sitemap</link>
> + </p>
> <source><![CDATA[
> <map:generator name="serverpages"
> pool-grow="2" pool-max="32" pool-min="4"
> src="org.apache.cocoon.generation.ServerPagesGenerator"/>]]></source>
> </li>
> - <li><p>Decide how you want to use XSP. For single files, you could just define a *.xml matcher:</p>
> + <li>
> + <p>Decide how you want to use XSP. For single files, you could just define a *.xml
> + matcher:</p>
> <source><![CDATA[
> <map:match pattern="dynamic.xml">
> <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
> ...
> <map:serialize type="xml"/>
> </map:match>]]></source>
> - <p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
> + <p>You may instead wish to override forrest.xmap to define a general mapping for
> + XSPs.</p>
> </li>
> </ol>
> - <p>See also the
> - <link href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
> + <p>See also the <link href="http://wiki.apache.org/cocoon/AddingXSPToForrest"
> + >AddingXSPToForrest</link> Wiki page.</p>
> </answer>
> </faq>
> -
> <faq id="breadcrumbs">
> - <question>How do breadcrumbs work? Why don't they work locally?</question>
> + <question>How do breadcrumbs work? Why don't they work locally?</question>
> <answer>
> - <p>Breadcrumbs begin with up to three URLs specified in
> - <code>skinconf.xml</code>. Here is what the Forrest site uses:</p>
> - <source><![CDATA[
> + <p>Breadcrumbs begin with up to three URLs specified in <code>skinconf.xml</code>. Here is
> + what the Forrest site uses:</p>
> + <source><![CDATA[
> <trail>
> <link1 name="apache" href="http://www.apache.org/"/>
> <link2 name="xml.apache" href="http://xml.apache.org/"/>
> <link3 name="" href=""/>
> </trail>]]></source>
> - <p>If any links are blank, they are not used. After these first links,
> - JavaScript looks at the URL for the current page and
> - makes a link for each directory after the domain. If you are viewing
> - the site locally, there is no domain and so
> - there will be no extra breadcrumbs, only the ones that are specified
> - in <code>skinconf.xml</code>.
> - </p>
> + <p>If any links are blank, they are not used. After these first links, JavaScript looks at
> + the URL for the current page and makes a link for each directory after the domain. If you
> + are viewing the site locally, there is no domain and so there will be no extra
> + breadcrumbs, only the ones that are specified in <code>skinconf.xml</code>. </p>
> </answer>
> </faq>
> -
> <faq id="run_port">
> <question>How do I make <code>forrest run</code> listen on a different port?</question>
> <answer>
> - <p><code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code></p>
> - <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
> - directory and set the port number in that file. Then do <code>forrest run</code>
> - </p>
> + <p>
> + <code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
> + </p>
> + <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
> + directory and set the port number in that file. Then do <code>forrest run</code>
> + </p>
> </answer>
> </faq>
> </part>
> -
> <part id="old_faqs">
> <title>Older version: 0.6</title>
> <faq id="old_claimed_patterns">
> - <question>Some of my files are not being processed because they use
> - common filenames.
> - </question>
> + <question>Some of my files are not being processed because they use common filenames. </question>
> <answer>
> - <p>
> - Certain patterns are claimed by the default sitemaps for
> - special processing. These include:
> - <code>site, changes, todo, faq, images, my-images, skinconf,
> - community, howto</code>
> - </p>
> - <p>
> - Sometimes there are workarounds, e.g. faq.html or faq-interview.html
> - would fail, but interview-faq.html would be fine.
> - In future versions of Forrest we will attempt to deal with this issue
> - (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
> + <p> Certain patterns are claimed by the default sitemaps for special processing. These
> + include: <code>site, changes, todo, faq, images, my-images, skinconf, community,
> + howto</code>
> + </p>
> + <p> Sometimes there are workarounds, e.g. faq.html or faq-interview.html would fail, but
> + interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
> + with this issue (<link href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</link>).
> </p>
> </answer>
> </faq>
> </part>
> -
> <part id="general">
> <title>General</title>
> -
> <faq id="generating_menus">
> - <question>What is the relationship between &s; and
> - <code>book.xml</code>?
> - </question>
> + <question>What is the relationship between &s; and <code>book.xml</code>? </question>
> <answer>
> - <p>
> - One &s; file in your project root can replace all the book.xml files
> - (one per directory) in your site. Internally, Forrest uses &s; to
> - dynamically generate book.xml files. However, Forrest first checks
> - for the existence of a book.xml file, so backwards-compatibility is
> - preserved. If a directory has a book.xml file, the book.xml will be
> - used to generate the menu. This supplement is useful in situations
> - where &s;-generated menus aren't appropriate.
> - See <link href="site:linking">Menus and Linking</link>.
> - </p>
> + <p> One &s; file in your project root can replace all the book.xml files (one per
> + directory) in your site. Internally, Forrest uses &s; to dynamically generate book.xml
> + files. However, Forrest first checks for the existence of a book.xml file, so
> + backwards-compatibility is preserved. If a directory has a book.xml file, the book.xml
> + will be used to generate the menu. This supplement is useful in situations where
> + &s;-generated menus aren't appropriate. See <link href="site:linking">Menus and
> + Linking</link>. </p>
> </answer>
> </faq>
> -
> <faq id="docbook">
> - <question>
> - How do I use DocBook as the xml documentation format?
> - </question>
> + <question> How do I use DocBook as the xml documentation format? </question>
> <answer>
> - <p>
> - There are two ways. Forrest has a <code>simplified-docbook</code> 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 transformation is
> - deliberately very limited and does not attempt to deal with all
> - DocBook elements.
> - </p>
> - <p>
> - The other way is to use the full DocBook stylesheets directly. The DocBook
> - DTDs are shipped with Forrest and automatically handled. However, you
> - will need to have the DocBook stylesheets on your system (they are
> - too massive to ship with Forrest) and configure Forrest accordingly.
> - You will need to create a
> - <link href="site:project-sitemap">project sitemap</link>
> - as explained in
> - <link href="site:your-project">Using Forrest</link>
> - and add matches to handle your DocBook documents.
> - Here is an example. Note that you need to change it to suit your
> - situation. The match must be very specific so that only the
> - DocBook documents are matched. The rest of the documents will be
> - handled by Forrest core. Powerful regex capabilities are available.
> - </p>
> + <p> There are two ways. Forrest has a <code>simplified-docbook</code> 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
> + transformation is deliberately very limited and does not attempt to deal with all DocBook
> + elements. </p>
> + <p> The other way is to use the full DocBook stylesheets directly. The DocBook DTDs are
> + shipped with Forrest and automatically handled. However, you will need to have the DocBook
> + stylesheets on your system (they are too massive to ship with Forrest) and configure
> + Forrest accordingly. You will need to create a <link href="site:project-sitemap">project
> + sitemap</link> as explained in <link href="site:your-project">Using Forrest</link> and
> + add matches to handle your DocBook documents. Here is an example. Note that you need to
> + change it to suit your situation. The match must be very specific so that only the DocBook
> + documents are matched. The rest of the documents will be handled by Forrest core. Powerful
> + regex capabilities are available. </p>
> <source><![CDATA[<?xml version="1.0"?>
> <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
> <map:pipelines>
> @@ -705,100 +545,61 @@
> </map:match>
> </map:pipeline>
> </map:pipelines>
> -</map:sitemap>]]>
> - </source>
> - <p>
> - 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.
> - </p>
> - <p>
> - 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
> - <link href="site:your-project/new_dtd">Using Forrest</link>
> - for configuration guidance.
> - </p>
> +</map:sitemap>]]></source>
> + <p> 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. </p>
> + <p> 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 <link href="site:your-project/new_dtd">Using Forrest</link> for
> + configuration guidance. </p>
> </answer>
> </faq>
> -
> <faq id="version">
> - <question>
> - How to report which version of Forrest is being used and the
> - properties that are set?
> - </question>
> + <question> How to report which version of Forrest is being used and the properties that are
> + set? </question>
> <answer>
> - <p>
> - Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code>
> - to find the version number.
> - </p>
> - <p>
> - To list the properties, add "forrest.echo=true" to your
> - forrest.properties file and watch the build messages.
> - Doing <code>'forrest -v'</code> will provide verbose build messages.
> - </p>
> + <p> Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code> to find the version
> + number. </p>
> + <p> To list the properties, add "forrest.echo=true" to your forrest.properties file and
> + watch the build messages. Doing <code>'forrest -v'</code> will provide verbose build
> + messages. </p>
> </answer>
> </faq>
> -
> <faq id="logs">
> - <question>
> - Where are the log files to find more infomation about errors?
> - </question>
> + <question> Where are the log files to find more infomation about errors? </question>
> <answer>
> - <p>
> - The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
> - </p>
> - <p>
> - The log level can be raised with the <code>logkit.xconf</code>
> - configuration. If you are using Forrest in the interactive webapp
> - mode (which is generally easiest for debugging errors) then see the
> - <code>build/webapp/WEB-INF/logkit.xconf</code> file.
> - If you are generating a static site (with command-line 'forrest')
> - then copy <code>$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</code>
> - to your project at
> - <code>src/documentation/content/conf/logkit.xconf</code>
> - and modify it. See more information and efficiency tips with
> - <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>.
> - </p>
> - <p>
> - Doing <code>'forrest -v'</code> will provide verbose build messages
> - to the standard output.
> + <p> The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
> </p>
> + <p> The log level can be raised with the <code>logkit.xconf</code> configuration. If you are
> + using Forrest in the interactive webapp mode (which is generally easiest for debugging
> + errors) then see the <code>build/webapp/WEB-INF/logkit.xconf</code> file. If you are
> + generating a static site (with command-line 'forrest') then copy
> + <code>$FORREST_HOME/main/webapp/WEB-INF/logkit.xconf</code> to your project at
> + <code>src/documentation/content/conf/logkit.xconf</code> and modify it. See more
> + information and efficiency tips with <link
> + href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>. </p>
> + <p> Doing <code>'forrest -v'</code> will provide verbose build messages to the standard
> + output. </p>
> </answer>
> </faq>
> -
> <faq id="how_can_I_help">
> - <question>
> - How to help?
> - </question>
> + <question> How to help? </question>
> <answer>
> - <p>
> - Join one of the Forrest project
> - <link href="site:mail-lists">mailing lists</link>
> - and tell us what you would like to see improved. We regard all feedback
> - as valuable, particularly from newcomers—often, close proximity
> - blinds software developers to faults that are obvious to everyone
> - else. Don't be shy!
> - </p>
> + <p> Join one of the Forrest project <link href="site:mail-lists">mailing lists</link> and
> + tell us what you would like to see improved. We regard all feedback as valuable,
> + particularly from newcomers—often, close proximity blinds software developers to
> + faults that are obvious to everyone else. Don't be shy! </p>
> </answer>
> </faq>
> -
> <faq id="patch">
> - <question>
> - How to contribute a patch?
> - </question>
> - <answer>
> - <p>Please send all contributions via our
> - <link href="site:bugs">issue tracker</link>.
> - Here are notes about
> - <link href="site:contrib/patch">making patches</link>.
> - </p>
> - <p>More info about contributing can be found at the
> - <link href="site:contrib">Contributing to Forrest</link> page.
> - It is always a good idea to check the Forrest
> - <link href="site:bugs">issue tracker</link>
> - before diving in.
> - </p>
> + <question> How to contribute a patch? </question>
> + <answer>
> + <p>Please send all contributions via our <link href="site:bugs">issue tracker</link>. Here
> + are notes about <link href="site:contrib/patch">making patches</link>. </p>
> + <p>More info about contributing can be found at the <link href="site:contrib">Contributing
> + to Forrest</link> page. It is always a good idea to check the Forrest <link
> + href="site:bugs">issue tracker</link> before diving in. </p>
> </answer>
> </faq>
> </part>
>
Re: whitespace changes (Was: svn commit: r167890)
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
> David Crossley wrote:
>
> DC> It seemed to also do other reformatting. Be sure to do 'svn diff'
> DC> before committing.
>
> Should I revert it back to the original whitespaceing and insert my
> changes again?
No. I was just making sure that people knew the problems
that it causes.
--David
Re: whitespace changes (Was: svn commit: r167890)
Posted by Ferdinand Soethe <sa...@soethe.net>.
David Crossley wrote:
DC> It seemed to also do other reformatting. Be sure to do 'svn diff'
DC> before committing.
Should I revert it back to the original whitespaceing and insert my
changes again?
--
Ferdinand Soethe
Re: whitespace changes (Was: svn commit: r167890)
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> Ferdinand Soethe wrote:
> >David Crossley wrote:
> >
> >DC> If people want to do many whitespace changes, then please
> >DC> try to keep them as separate commits to real content changes.
> >DC> Committers have a duty to monitor the commits. When the
> >DC> changes are mixed with whitespace changes, it is very
> >DC> difficult to see what changed.
> >
> >Sorry about that.
> >
> >Actually I didn't really want to change other whitespace. I just had
> >Oxygen re-format the XML with 2 space indents (which I thought was the
> >rule).
It seemed to also do other reformatting. Be sure to do 'svn diff'
before committing.
> >Any suggestions how to set the Oxygen so that it is in sync what
> >everybody else uses.
>
> There are only guidelines, not rules. The best thing to do is to turn
> off all auto formating, ensure your editor uses spaces not tabs and edit
> files in the same style that they already exists.
Yes, that is the safest.
> I struggled with this myself for a while as I was used to working in
> teams with a clear set of rules. However, it seems Open Source never
> works this way because of the range of tools, preffered styles,
> operating systems etc.
There was a huge discussion about this topic at dev@cocoon
Re: whitespace cleanup and efficiency drive
http://marc.theaimsgroup.com/?t=106843997700002
Some of that was documented at:
http://cocoon.apache.org/community/committer.html
One particular outcome was that occasionally someone
who has a capable editor should make the whitespace
be consistent in all files. It would probably be best
to do a section of the repository while no other people
are working on that section. That has been gradually
happening at Cocoon.
--David
Re: whitespace changes (Was: svn commit: r167890)
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> David Crossley wrote:
>
> DC> If people want to do many whitespace changes, then please
> DC> try to keep them as separate commits to real content changes.
> DC> Committers have a duty to monitor the commits. When the
> DC> changes are mixed with whitespace changes, it is very
> DC> difficult to see what changed.
>
> Sorry about that.
>
> Actually I didn't really want to change other whitespace. I just had
> Oxygen re-format the XML with 2 space indents (which I thought was the
> rule).
>
> Any suggestions how to set the Oxygen so that it is in sync what
> everybody else uses.
There are only guidelines, not rules. The best thing to do is to turn
off all auto formating, ensure your editor uses spaces not tabs and edit
files in the same style that they already exists.
I struggled with this myself for a while as I was used to working in
teams with a clear set of rules. However, it seems Open Source never
works this way because of the range of tools, preffered styles,
operating systems etc.
Ross
Re: whitespace changes (Was: svn commit: r167890)
Posted by Ferdinand Soethe <sa...@soethe.net>.
David Crossley wrote:
DC> If people want to do many whitespace changes, then please
DC> try to keep them as separate commits to real content changes.
DC> Committers have a duty to monitor the commits. When the
DC> changes are mixed with whitespace changes, it is very
DC> difficult to see what changed.
Sorry about that.
Actually I didn't really want to change other whitespace. I just had
Oxygen re-format the XML with 2 space indents (which I thought was the
rule).
Any suggestions how to set the Oxygen so that it is in sync what
everybody else uses.
--
Ferdinand Soethe