You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2004/10/18 05:51:59 UTC
svn commit: rev 54987 - forrest/site
Author: crossley
Date: Sun Oct 17 20:51:58 2004
New Revision: 54987
Modified:
forrest/site/faq.html
forrest/site/faq.pdf
forrest/site/faq.xml
Log:
Add FAQ about tools for editing content.
Modified: forrest/site/faq.html
==============================================================================
--- forrest/site/faq.html (original)
+++ forrest/site/faq.html Sun Oct 17 20:51:58 2004
@@ -226,72 +226,75 @@
<a href="#technical">2. Technical</a>
<ul class="minitoc">
<li>
-<a href="#PDF-output">2.1. How can I generate one pdf-file out of
+<a href="#edit-content">2.1. What tools can be used to edit the content?</a>
+</li>
+<li>
+<a href="#PDF-output">2.2. How can I generate one pdf-file out of
the whole site or selected pages of the site?</a>
</li>
<li>
-<a href="#clickable-email-adress">2.2. How can I generate html-pages to show a
+<a href="#clickable-email-adress">2.3. How can I generate html-pages to show a
'clickable' email-address (of the author-element)?</a>
</li>
<li>
-<a href="#CVS_revison_tags">2.3. How can I generate html-pages to show the
+<a href="#CVS_revison_tags">2.4. How can I generate html-pages to show the
revision tag of cvs?</a>
</li>
<li>
-<a href="#ignoring_javadocs">2.4.
+<a href="#ignoring_javadocs">2.5.
How do I stop Forrest breaking on links to external files that may not
exist, like javadocs?
</a>
</li>
<li>
-<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf?
+<a href="#link_raw">2.6. How do I link to raw files such as config.txt and brochure.pdf?
</a>
</li>
<li>
-<a href="#claimed_patterns">2.6. Some of my files are not being processed because they use
+<a href="#claimed_patterns">2.7. Some of my files are not being processed because they use
common filenames.
</a>
</li>
<li>
-<a href="#build_msg_a">2.7. What do the symbols and numbers mean when Forrest lists each
+<a href="#build_msg_a">2.8. What do the symbols and numbers mean when Forrest lists each
document that it has built?
</a>
</li>
<li>
-<a href="#pdf_images">2.8. Images don't display in PDFs. How do I fix this?</a>
+<a href="#pdf_images">2.9. Images don't display in PDFs. How do I fix this?</a>
</li>
<li>
-<a href="#index.html">2.9.
+<a href="#index.html">2.10.
The tab link in my site incorrectly assumes that 'index.html' is present in
the linked-to directory. How do I fix this?
</a>
</li>
<li>
-<a href="#headless_operation">2.10.
+<a href="#headless_operation">2.11.
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.
</a>
</li>
<li>
-<a href="#catalog">2.11.
+<a href="#catalog">2.12.
How do i configure my favourite XML editor or parser to find the
local Forrest DTDs?
</a>
</li>
<li>
-<a href="#label-entity">2.12.
+<a href="#label-entity">2.13.
How to use special characters in the labels of the site.xml file?
</a>
</li>
<li>
-<a href="#skin">2.13.
+<a href="#skin">2.14.
How to make the site look better and change its skin?
</a>
</li>
<li>
-<a href="#xsp">2.14. How do I enable XSP processing?</a>
+<a href="#xsp">2.15. How do I enable XSP processing?</a>
</li>
<li>
-<a href="#breadcrumbs">2.15. How do breadcrumbs work? Why don't they work locally?</a>
+<a href="#breadcrumbs">2.16. How do breadcrumbs work? Why don't they work locally?</a>
</li>
</ul>
</li>
@@ -483,8 +486,32 @@
</div>
<a name="N1007E"></a><a name="technical"></a>
<h3 class="underlined_5">2. Technical</h3>
-<a name="N10082"></a><a name="PDF-output"></a>
-<h4 class="faq">2.1. How can I generate one pdf-file out of
+<a name="N10082"></a><a name="edit-content"></a>
+<h4 class="faq">2.1. What tools can be used to edit the content?</h4>
+<div align="right">
+<a href="#edit-content-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>If you are using the Apache Forrest xml
+ <a href="docs/dtd-docs.html">document format</a> 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
+ <a href="docs/catalog.html">configuration notes</a>
+ for various editors.
+ </p>
+<p>There are content management systems like
+ <a class="external" href="http://cocoon.apache.org/lenya/">Apache Lenya</a>.
+ </p>
+<p>Remember that Forrest can also use other source formats, such as
+ Open Office 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>
+</div>
+<a name="N1009C"></a><a name="PDF-output"></a>
+<h4 class="faq">2.2. How can I generate one pdf-file out of
the whole site or selected pages of the site?</h4>
<div align="right">
<a href="#PDF-output-menu">^</a>
@@ -509,8 +536,8 @@
structure and navigation, rather than the old book.xml method.
</p>
</div>
-<a name="N1009C"></a><a name="clickable-email-adress"></a>
-<h4 class="faq">2.2. How can I generate html-pages to show a
+<a name="N100B6"></a><a name="clickable-email-adress"></a>
+<h4 class="faq">2.3. How can I generate html-pages to show a
'clickable' email-address (of the author-element)?</h4>
<div align="right">
<a href="#clickable-email-adress-menu">^</a>
@@ -521,8 +548,8 @@
and edit the "headers/authors" template.
</p>
</div>
-<a name="N100A7"></a><a name="CVS_revison_tags"></a>
-<h4 class="faq">2.3. How can I generate html-pages to show the
+<a name="N100C1"></a><a name="CVS_revison_tags"></a>
+<h4 class="faq">2.4. How can I generate html-pages to show the
revision tag of cvs?</h4>
<div align="right">
<a href="#CVS_revison_tags-menu">^</a>
@@ -536,8 +563,8 @@
<p>This technique could also be used for a modification date with
$Date: 2004/01/15 08:52:47 $</p>
</div>
-<a name="N100B9"></a><a name="ignoring_javadocs"></a>
-<h4 class="faq">2.4.
+<a name="N100D3"></a><a name="ignoring_javadocs"></a>
+<h4 class="faq">2.5.
How do I stop Forrest breaking on links to external files that may not
exist, like javadocs?
</h4>
@@ -580,8 +607,8 @@
</div>
</div>
</div>
-<a name="N100ED"></a><a name="link_raw"></a>
-<h4 class="faq">2.5. How do I link to raw files such as config.txt and brochure.pdf?
+<a name="N10107"></a><a name="link_raw"></a>
+<h4 class="faq">2.6. How do I link to raw files such as config.txt and brochure.pdf?
</h4>
<div align="right">
<a href="#link_raw-menu">^</a>
@@ -606,8 +633,8 @@
'forrest seed' site.
</p>
</div>
-<a name="N1010A"></a><a name="claimed_patterns"></a>
-<h4 class="faq">2.6. Some of my files are not being processed because they use
+<a name="N10124"></a><a name="claimed_patterns"></a>
+<h4 class="faq">2.7. Some of my files are not being processed because they use
common filenames.
</h4>
<div align="right">
@@ -628,8 +655,8 @@
(<a class="external" href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
</p>
</div>
-<a name="N1011C"></a><a name="build_msg_a"></a>
-<h4 class="faq">2.7. What do the symbols and numbers mean when Forrest lists each
+<a name="N10136"></a><a name="build_msg_a"></a>
+<h4 class="faq">2.8. What do the symbols and numbers mean when Forrest lists each
document that it has built?
</h4>
<div align="right">
@@ -652,8 +679,8 @@
Column 4 is the page size.
</p>
</div>
-<a name="N10128"></a><a name="pdf_images"></a>
-<h4 class="faq">2.8. Images don't display in PDFs. How do I fix this?</h4>
+<a name="N10142"></a><a name="pdf_images"></a>
+<h4 class="faq">2.9. Images don't display in PDFs. How do I fix this?</h4>
<div align="right">
<a href="#pdf_images-menu">^</a>
</div>
@@ -692,8 +719,8 @@
Forrest.</div>
</div>
</div>
-<a name="N10154"></a><a name="index.html"></a>
-<h4 class="faq">2.9.
+<a name="N1016E"></a><a name="index.html"></a>
+<h4 class="faq">2.10.
The tab link in my site incorrectly assumes that 'index.html' is present in
the linked-to directory. How do I fix this?
</h4>
@@ -718,8 +745,8 @@
<map:redirect-to uri="manual/Introduction.html"/>
</map:match></pre>
</div>
-<a name="N10170"></a><a name="headless_operation"></a>
-<h4 class="faq">2.10.
+<a name="N1018A"></a><a name="headless_operation"></a>
+<h4 class="faq">2.11.
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.
</h4>
<div align="right">
@@ -737,8 +764,8 @@
<a class="external" href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>.
</p>
</div>
-<a name="N1018C"></a><a name="catalog"></a>
-<h4 class="faq">2.11.
+<a name="N101A6"></a><a name="catalog"></a>
+<h4 class="faq">2.12.
How do i configure my favourite XML editor or parser to find the
local Forrest DTDs?
</h4>
@@ -752,8 +779,8 @@
local DTDs</a>.
</p>
</div>
-<a name="N10198"></a><a name="label-entity"></a>
-<h4 class="faq">2.12.
+<a name="N101B2"></a><a name="label-entity"></a>
+<h4 class="faq">2.13.
How to use special characters in the labels of the site.xml file?
</h4>
<div align="right">
@@ -774,8 +801,8 @@
<a class="external" href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</a>.
</p>
</div>
-<a name="N101B1"></a><a name="skin"></a>
-<h4 class="faq">2.13.
+<a name="N101CB"></a><a name="skin"></a>
+<h4 class="faq">2.14.
How to make the site look better and change its skin?
</h4>
<div align="right">
@@ -795,8 +822,8 @@
<a href="docs/your-project.html#new_skin">own skin</a>.
</p>
</div>
-<a name="N101C8"></a><a name="xsp"></a>
-<h4 class="faq">2.14. How do I enable XSP processing?</h4>
+<a name="N101E2"></a><a name="xsp"></a>
+<h4 class="faq">2.15. How do I enable XSP processing?</h4>
<div align="right">
<a href="#xsp-menu">^</a>
</div>
@@ -842,8 +869,8 @@
<p>See also the
<a class="external" href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
</div>
-<a name="N101FD"></a><a name="breadcrumbs"></a>
-<h4 class="faq">2.15. How do breadcrumbs work? Why don't they work locally?</h4>
+<a name="N10217"></a><a name="breadcrumbs"></a>
+<h4 class="faq">2.16. How do breadcrumbs work? Why don't they work locally?</h4>
<div align="right">
<a href="#breadcrumbs-menu">^</a>
</div>
@@ -864,9 +891,9 @@
in <span class="codefrag">skinconf.xml</span>.
</p>
</div>
-<a name="N10212"></a><a name="old_faqs"></a>
+<a name="N1022C"></a><a name="old_faqs"></a>
<h3 class="underlined_5">3. Older versions</h3>
-<a name="N10216"></a><a name="unresolved_project.home"></a>
+<a name="N10230"></a><a name="unresolved_project.home"></a>
<h4 class="faq">3.1. When invoking Forrest 0.4 from the
forrest.antproxy.xml, the build fails because
${project.home} isn't resolved.
@@ -888,7 +915,7 @@
<classpath refid="forrest-classpath"/>
<jvmarg value="-Dforrest.home=${forrest.home}"/></pre>
</div>
-<a name="N1022B"></a><a name="odd_html"></a>
+<a name="N10245"></a><a name="odd_html"></a>
<h4 class="faq">3.2.
After upgrading to 0.4 my HTML looks significantly different, and table
widths are wrong. What happened?
@@ -911,7 +938,7 @@
<pre class="code">
<doctype-system>http://www.w3.org/TR/html4/loose.dtd</doctype-system></pre>
</div>
-<a name="N10241"></a><a name="validation_error-doctype_root_null"></a>
+<a name="N1025B"></a><a name="validation_error-doctype_root_null"></a>
<h4 class="faq">3.3.
When building my project, I get an validation error: Document root
element "site", must match DOCTYPE root "null"..
@@ -934,7 +961,7 @@
listed to prevent an attempt at DTD-based validation.
</p>
</div>
-<a name="N1025E"></a><a name="building_error-custom_sitemap"></a>
+<a name="N10278"></a><a name="building_error-custom_sitemap"></a>
<h4 class="faq">3.4.
When building my project, I get any of these errors:
menu.xmap (The system cannot find the file specified)
@@ -950,9 +977,9 @@
<a href="docs/upgrading_05.html">Upgrading to Forrest 0.5</a>).
</p>
</div>
-<a name="N10273"></a><a name="general"></a>
+<a name="N1028D"></a><a name="general"></a>
<h3 class="underlined_5">4. General</h3>
-<a name="N10277"></a><a name="generating_menus"></a>
+<a name="N10291"></a><a name="generating_menus"></a>
<h4 class="faq">4.1. What is the relationship between site.xml and
book.xml?
</h4>
@@ -971,7 +998,7 @@
See <a href="docs/linking.html">Menus and Linking</a>.
</p>
</div>
-<a name="N10292"></a><a name="docbook"></a>
+<a name="N102AC"></a><a name="docbook"></a>
<h4 class="faq">4.2.
How do I use DocBook as the xml documentation format?
</h4>
@@ -1029,7 +1056,7 @@
for configuration guidance.
</p>
</div>
-<a name="N102B3"></a><a name="version"></a>
+<a name="N102CD"></a><a name="version"></a>
<h4 class="faq">4.3.
How to report which version of Forrest is being used and the
properties that are set?
@@ -1048,7 +1075,7 @@
Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages.
</p>
</div>
-<a name="N102C7"></a><a name="logs"></a>
+<a name="N102E1"></a><a name="logs"></a>
<h4 class="faq">4.4.
Where are the log files to find more infomation about errors?
</h4>
@@ -1077,7 +1104,7 @@
to the standard output.
</p>
</div>
-<a name="N102EB"></a><a name="how_can_I_help"></a>
+<a name="N10305"></a><a name="how_can_I_help"></a>
<h4 class="faq">4.5.
How to help?
</h4>
@@ -1094,7 +1121,7 @@
else. Don't be shy!
</p>
</div>
-<a name="N102F7"></a><a name="patch"></a>
+<a name="N10311"></a><a name="patch"></a>
<h4 class="faq">4.6.
How to contribute a patch?
</h4>
Modified: forrest/site/faq.pdf
==============================================================================
Binary files. No diff available.
Modified: forrest/site/faq.xml
==============================================================================
--- forrest/site/faq.xml (original)
+++ forrest/site/faq.xml Sun Oct 17 20:51:58 2004
@@ -79,7 +79,25 @@
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>
- </section></section><section id="technical"><title>2. Technical</title><section id="PDF-output"><title>2.1. How can I generate one pdf-file out of
+ </section></section><section id="technical"><title>2. Technical</title><section id="edit-content"><title>2.1. What tools can be used to edit the content?</title>
+ <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="site:references/lenya">Apache Lenya</link>.
+ </p>
+ <p>Remember that Forrest can also use other source formats, such as
+ Open Office 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>
+ </section><section id="PDF-output"><title>2.2. How can I generate one pdf-file out of
the whole site or selected pages of the site?</title>
<p>Add the following entries to your site.xml file:</p>
<source xml:space="preserve">
@@ -99,13 +117,13 @@
<link href="site:linking">site.xml</link> method for your site
structure and navigation, rather than the old book.xml method.
</p>
- </section><section id="clickable-email-adress"><title>2.2. How can I generate html-pages to show a
+ </section><section id="clickable-email-adress"><title>2.3. How can I generate html-pages to show a
'clickable' email-address (of the author-element)?</title>
<p>You would override <code>
src/core/context/skins/common/xslt/html/document2html.xsl</code>
and edit the "headers/authors" template.
</p>
- </section><section id="CVS_revison_tags"><title>2.3. How can I generate html-pages to show the
+ </section><section id="CVS_revison_tags"><title>2.4. How can I generate html-pages to show the
revision tag of cvs?</title>
<p>If you have:<code><version>$Revision: 1.30
$</version></code>The '1.30' will be extracted and
@@ -114,7 +132,7 @@
<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>
- </section><section id="ignoring_javadocs"><title>2.4.
+ </section><section id="ignoring_javadocs"><title>2.5.
How do I stop Forrest breaking on links to external files that may not
exist, like javadocs?
</title>
@@ -149,7 +167,7 @@
<code>foo/bar</code>, but not <code>foo/bar/baz</code>
— use <strong>foo/**</strong> to match that.
</note>
- </section><section id="link_raw"><title>2.5. How do I link to raw files such as config.txt and brochure.pdf?
+ </section><section id="link_raw"><title>2.6. How do I link to raw files such as config.txt and brochure.pdf?
</title>
<p>
Place them in the <code>src/documentation/content</code> directory
@@ -169,7 +187,7 @@
See the explanation and demonstration of "linking" in your local
'forrest seed' site.
</p>
- </section><section id="claimed_patterns"><title>2.6. Some of my files are not being processed because they use
+ </section><section id="claimed_patterns"><title>2.7. Some of my files are not being processed because they use
common filenames.
</title>
<p>
@@ -184,7 +202,7 @@
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>
- </section><section id="build_msg_a"><title>2.7. What do the symbols and numbers mean when Forrest lists each
+ </section><section id="build_msg_a"><title>2.8. What do the symbols and numbers mean when Forrest lists each
document that it has built?
</title>
<source xml:space="preserve">
@@ -202,7 +220,7 @@
Column 3 is the time taken.
Column 4 is the page size.
</p>
- </section><section id="pdf_images"><title>2.8. Images don't display in PDFs. How do I fix this?</title>
+ </section><section id="pdf_images"><title>2.9. Images don't display in PDFs. How do I fix this?</title>
<p>
	 Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
for rendering PDFs. FOP cannot handle all image types natively, and
@@ -227,7 +245,7 @@
</p>
<note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
Forrest.</note>
- </section><section id="index.html"><title>2.9.
+ </section><section id="index.html"><title>2.10.
The tab link in my site incorrectly assumes that 'index.html' is present in
the linked-to directory. How do I fix this?
</title>
@@ -247,7 +265,7 @@
<map:match pattern="manual">
<map:redirect-to uri="manual/Introduction.html"/>
</map:match></source>
- </section><section id="headless_operation"><title>2.10.
+ </section><section id="headless_operation"><title>2.11.
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.
</title>
<p>
@@ -260,7 +278,7 @@
See also
<link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>.
</p>
- </section><section id="catalog"><title>2.11.
+ </section><section id="catalog"><title>2.12.
How do i configure my favourite XML editor or parser to find the
local Forrest DTDs?
</title>
@@ -269,7 +287,7 @@
<link href="site:catalog">Using Catalog Entity Resolver for
local DTDs</link>.
</p>
- </section><section id="label-entity"><title>2.12.
+ </section><section id="label-entity"><title>2.13.
How to use special characters in the labels of the site.xml file?
</title>
<p>
@@ -284,7 +302,7 @@
and see more discussion at
<link href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>.
</p>
- </section><section id="skin"><title>2.13.
+ </section><section id="skin"><title>2.14.
How to make the site look better and change its skin?
</title>
<p>
@@ -299,7 +317,7 @@
Some projects may have special needs and can define their
<link href="site:your-project/new-skin">own skin</link>.
</p>
- </section><section id="xsp"><title>2.14. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
+ </section><section id="xsp"><title>2.15. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
<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
@@ -329,7 +347,7 @@
</ol>
<p>See also the
<link href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
- </section><section id="breadcrumbs"><title>2.15. How do breadcrumbs work? Why don't they work locally?</title>
+ </section><section id="breadcrumbs"><title>2.16. How do breadcrumbs work? Why don't they work locally?</title>
<p>Breadcrumbs begin with up to three URLs specified in
<code>skinconf.xml</code>. Here is what the Forrest site uses:</p>
<source xml:space="preserve">