forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r178944 - in /forrest/site/0.7/docs: faq.html faq.pdf faq.xml linking.html linking.pdf
Date Sun, 29 May 2005 11:45:40 GMT
Author: crossley
Date: Sun May 29 04:45:40 2005
New Revision: 178944

URL: http://svn.apache.org/viewcvs?rev=178944&view=rev
Log:
Added some more FAQs.

Modified:
    forrest/site/0.7/docs/faq.html
    forrest/site/0.7/docs/faq.pdf
    forrest/site/0.7/docs/faq.xml
    forrest/site/0.7/docs/linking.html
    forrest/site/0.7/docs/linking.pdf

Modified: forrest/site/0.7/docs/faq.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.html?rev=178944&r1=178943&r2=178944&view=diff
==============================================================================
--- forrest/site/0.7/docs/faq.html (original)
+++ forrest/site/0.7/docs/faq.html Sun May 29 04:45:40 2005
@@ -327,40 +327,45 @@
 <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>
+<a href="#site-xml">2.2. 
+        How to use the site.xml configuration file for menus and linking.
+      </a>
 </li>
 <li>
-<a href="#pageBreaks">2.3. How do I insert page breaks into documents?</a>
+<a href="#PDF-output">2.3. 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-address">2.4. How can I generate html-pages to show a 'clickable' email-address (of the
+<a href="#pageBreaks">2.4. How do I insert page breaks into documents?</a>
+</li>
+<li>
+<a href="#clickable-email-address">2.5. How can I generate html-pages to show a 'clickable' email-address (of the
         author-element)?</a>
 </li>
 <li>
-<a href="#link_raw">2.5. How do I link to raw files such as config.txt and brochure.pdf? </a>
+<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="#pdf_images">2.6. Images don't display in PDFs. How do I fix this?</a>
+<a href="#pdf_images">2.7. Images don't display in PDFs. How do I fix this?</a>
 </li>
 <li>
-<a href="#index.html">2.7.  The tab link in my site incorrectly assumes that 'index.html' is present in the
+<a href="#index.html">2.8.  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="#defaultFileName">2.8.  How can I change the default file name that Forrest will look for when I request a
+<a href="#defaultFileName">2.9.  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/ ? </a>
 </li>
 <li>
-<a href="#defaultStartPage">2.9.  How can I use a start-up-page other than index.html? </a>
+<a href="#defaultStartPage">2.10.  How can I use a start-up-page other than index.html? </a>
 </li>
 <li>
-<a href="#label-entity">2.10.  How to use special characters in the labels of the site.xml file? </a>
+<a href="#label-entity">2.11.  How to use special characters in the labels of the site.xml file? </a>
 </li>
 <li>
-<a href="#encoding">2.11. Does Forrest handle accents for non-English languages?</a>
+<a href="#encoding">2.12. Does Forrest handle accents for non-English languages?</a>
 </li>
 <li>
-<a href="#cleanSite">2.12.  How can I make Forrest properly clean up the build/site-directory? </a>
+<a href="#cleanSite">2.13.  How can I make Forrest properly clean up the build/site-directory? </a>
 </li>
 </ul>
 </li>
@@ -394,20 +399,25 @@
         server using ':0.0' as the value of the DISPLAY variable. </a>
 </li>
 <li>
-<a href="#catalog">3.8.  How do i configure my favourite XML editor or parser to find the local Forrest
+<a href="#project-logo-svg">3.8.  
+        The project logo that is generated from SVG is truncating my project name.
+      </a>
+</li>
+<li>
+<a href="#catalog">3.9.  How do i configure my favourite XML editor or parser to find the local Forrest
         DTDs? </a>
 </li>
 <li>
-<a href="#skin">3.9.  How to make the site look better and change its skin? </a>
+<a href="#skin">3.10.  How to make the site look better and change its skin? </a>
 </li>
 <li>
-<a href="#xsp">3.10. How do I enable XSP processing?</a>
+<a href="#xsp">3.11. How do I enable XSP processing?</a>
 </li>
 <li>
-<a href="#breadcrumbs">3.11. How do breadcrumbs work? Why don't they work locally?</a>
+<a href="#breadcrumbs">3.12. How do breadcrumbs work? Why don't they work locally?</a>
 </li>
 <li>
-<a href="#run_port">3.12. How do I make forrest run listen on a different port?</a>
+<a href="#run_port">3.13. How do I make forrest run listen on a different port?</a>
 </li>
 </ul>
 </li>
@@ -545,8 +555,50 @@
           you can use text editors or "html editors" such as the one provided with the Mozilla web
           browser. </p>
 </div>
-<a name="N1009B"></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>
+<a name="N1009B"></a><a name="site-xml"></a>
+<h4 class="faq">2.2. 
+        How to use the site.xml configuration file for menus and linking.
+      </h4>
+<div align="right">
+<a href="#site-xml-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+          The <span class="codefrag">site.xml</span> configuration file is used for two different purposes:
+          defining the left-hand navigation menus, and as a method for defining references
+          to be used when linking between documents.
+          This file is fully explained in
+          <a href="../docs/linking.html">Menus and Linking</a>. Here is a precis:
+        </p>
+<p>
+          Use unique element names. The labels can be whatever text you want.
+        </p>
+<pre class="code">&lt;faq label="FAQs" href="faq.html"&gt;
+  &lt;tech label="Technical" href="faq-tech.html"&gt;
+    &lt;docbook href="#docbook"/&gt;
+    &lt;ignoring_javadocs href="#ignoring_javadocs"/&gt;
+  &lt;/tech&gt;
+  &lt;user label="User" href="faq-user.html"&gt;
+&lt;/faq&gt;</pre>
+<p>
+          That will create a menu like this with three links:
+        </p>
+<pre class="code">FAQs
+   Technical
+   User</pre>
+<p>
+          These documents can be linked to from other documents, like this:
+        </p>
+<pre class="code">&lt;a href="site:faq/tech"&gt; link to the top of the Tech FAQs
+&lt;a href="site:faq/tech/docbook"&gt; link to the DocBook FAQ in the Tech FAQs</pre>
+<p>
+          If that "docbook" entry was a unique name in your site.xml then you
+          can shorten that latter link:
+        </p>
+<pre class="code">&lt;a href="site:docbook"&gt; link to the DocBook FAQ in the Tech FAQs</pre>
+</div>
+<a name="N100C9"></a><a name="PDF-output"></a>
+<h4 class="faq">2.3. 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>
 </div>
@@ -565,8 +617,8 @@
 <p> This assumes that you use the <a href="../docs/linking.html">site.xml</a> method for your
           site structure and navigation, rather than the old book.xml method. </p>
 </div>
-<a name="N100B5"></a><a name="pageBreaks"></a>
-<h4 class="faq">2.3. How do I insert page breaks into documents?</h4>
+<a name="N100E3"></a><a name="pageBreaks"></a>
+<h4 class="faq">2.4. How do I insert page breaks into documents?</h4>
 <div align="right">
 <a href="#pageBreaks-menu">^</a>
 </div>
@@ -586,8 +638,8 @@
 <pre class="code"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
           margin-bottom: 0; page-break-after: always; } </pre>
 </div>
-<a name="N100D3"></a><a name="clickable-email-address"></a>
-<h4 class="faq">2.4. How can I generate html-pages to show a 'clickable' email-address (of the
+<a name="N10101"></a><a name="clickable-email-address"></a>
+<h4 class="faq">2.5. How can I generate html-pages to show a 'clickable' email-address (of the
         author-element)?</h4>
 <div align="right">
 <a href="#clickable-email-address-menu">^</a>
@@ -597,8 +649,8 @@
             $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</span> and edit the
           "headers/authors" template. </p>
 </div>
-<a name="N100DE"></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? </h4>
+<a name="N1010C"></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>
 </div>
@@ -607,8 +659,8 @@
           <a href="../docs/upgrading_07.html#raw">Upgrading to Apache Forrest 0.7</a> for
           all the details.</p>
 </div>
-<a name="N100EA"></a><a name="pdf_images"></a>
-<h4 class="faq">2.6. Images don't display in PDFs. How do I fix this?</h4>
+<a name="N10118"></a><a name="pdf_images"></a>
+<h4 class="faq">2.7. Images don't display in PDFs. How do I fix this?</h4>
 <div align="right">
 <a href="#pdf_images-menu">^</a>
 </div>
@@ -639,8 +691,8 @@
 <div class="content">Due to Sun's licensing, we cannot redistribute Jimi or JAI with Forrest.</div>
 </div>
 </div>
-<a name="N10117"></a><a name="index.html"></a>
-<h4 class="faq">2.7.  The tab link in my site incorrectly assumes that 'index.html' is present in the
+<a name="N10145"></a><a name="index.html"></a>
+<h4 class="faq">2.8.  The tab link in my site incorrectly assumes that 'index.html' is present in the
         linked-to directory. How do I fix this? </h4>
 <div align="right">
 <a href="#index.html-menu">^</a>
@@ -658,8 +710,8 @@
     &lt;map:redirect-to uri="manual/Introduction.html"/&gt;
   &lt;/map:match&gt;</pre>
 </div>
-<a name="N10133"></a><a name="defaultFileName"></a>
-<h4 class="faq">2.8.  How can I change the default file name that Forrest will look for when I request a
+<a name="N10161"></a><a name="defaultFileName"></a>
+<h4 class="faq">2.9.  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/ ? </h4>
 <div align="right">
 <a href="#defaultFileName-menu">^</a>
@@ -688,8 +740,8 @@
         
 </ol>
 </div>
-<a name="N1015B"></a><a name="defaultStartPage"></a>
-<h4 class="faq">2.9.  How can I use a start-up-page other than index.html? </h4>
+<a name="N10189"></a><a name="defaultStartPage"></a>
+<h4 class="faq">2.10.  How can I use a start-up-page other than index.html? </h4>
 <div align="right">
 <a href="#defaultStartPage-menu">^</a>
 </div>
@@ -719,8 +771,8 @@
         
 </ol>
 </div>
-<a name="N1017F"></a><a name="label-entity"></a>
-<h4 class="faq">2.10.  How to use special characters in the labels of the site.xml file? </h4>
+<a name="N101AD"></a><a name="label-entity"></a>
+<h4 class="faq">2.11.  How to use special characters in the labels of the site.xml file? </h4>
 <div align="right">
 <a href="#label-entity-menu">^</a>
 </div>
@@ -731,8 +783,8 @@
 </p>
 <p> See the <a href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</a> and see more discussion at <a href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</a>. </p>
 </div>
-<a name="N10198"></a><a name="encoding"></a>
-<h4 class="faq">2.11. Does Forrest handle accents for non-English languages?</h4>
+<a name="N101C6"></a><a name="encoding"></a>
+<h4 class="faq">2.12. Does Forrest handle accents for non-English languages?</h4>
 <div align="right">
 <a href="#encoding-menu">^</a>
 </div>
@@ -778,8 +830,8 @@
             Schlabach</a> and <a href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
             resources</a>. </p>
 </div>
-<a name="N101EA"></a><a name="cleanSite"></a>
-<h4 class="faq">2.12.  How can I make Forrest properly clean up the build/site-directory? </h4>
+<a name="N10218"></a><a name="cleanSite"></a>
+<h4 class="faq">2.13.  How can I make Forrest properly clean up the build/site-directory? </h4>
 <div align="right">
 <a href="#cleanSite-menu">^</a>
 </div>
@@ -790,9 +842,9 @@
 <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>
 </div>
-<a name="N101F5"></a><a name="technical"></a>
+<a name="N10223"></a><a name="technical"></a>
 <h3 class="underlined_5">3. Technical</h3>
-<a name="N101F9"></a><a name="proxy_config"></a>
+<a name="N10227"></a><a name="proxy_config"></a>
 <h4 class="faq">3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
         do?</h4>
 <div align="right">
@@ -803,7 +855,7 @@
             <span class="codefrag">proxy.host</span> and <span class="codefrag">proxy.port</span> accordingly (the port will default
           to port 80).</p>
 </div>
-<a name="N1020A"></a><a name="CVS_revison_tags"></a>
+<a name="N10238"></a><a name="CVS_revison_tags"></a>
 <h4 class="faq">3.2. How can I generate html-pages to show the revision tag of cvs?</h4>
 <div align="right">
 <a href="#CVS_revison_tags-menu">^</a>
@@ -816,7 +868,7 @@
 <p>This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47
           $</p>
 </div>
-<a name="N1021C"></a><a name="cli-xconf"></a>
+<a name="N1024A"></a><a name="cli-xconf"></a>
 <h4 class="faq">3.3.  How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
         other additional ones. </h4>
 <div align="right">
@@ -854,7 +906,7 @@
           <strong>foo/**</strong> to match that. </div>
 </div>
 </div>
-<a name="N10259"></a><a name="ignoring_javadocs"></a>
+<a name="N10287"></a><a name="ignoring_javadocs"></a>
 <h4 class="faq">3.4.  How do I stop Forrest breaking on links to external files that may not exist, like
         javadocs? </h4>
 <div align="right">
@@ -865,7 +917,7 @@
             <span class="codefrag">cli.xconf</span>
           </a> Cocoon config file, and defining patterns for URLs to exclude. </p>
 </div>
-<a name="N10268"></a><a name="claimed_patterns"></a>
+<a name="N10296"></a><a name="claimed_patterns"></a>
 <h4 class="faq">3.5. Some of my files are not being processed because they use common filenames. </h4>
 <div align="right">
 <a href="#claimed_patterns-menu">^</a>
@@ -881,7 +933,7 @@
           with this issue (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
         </p>
 </div>
-<a name="N1027A"></a><a name="build_msg_a"></a>
+<a name="N102A8"></a><a name="build_msg_a"></a>
 <h4 class="faq">3.6. What do the symbols and numbers mean when Forrest lists each document that it has
         built? </h4>
 <div align="right">
@@ -901,7 +953,7 @@
           number of links that were gathered from that page. Column 3 is the time taken. Column 4 is
           the page size. </p>
 </div>
-<a name="N10286"></a><a name="headless_operation"></a>
+<a name="N102B4"></a><a name="headless_operation"></a>
 <h4 class="faq">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. </h4>
 <div align="right">
@@ -914,8 +966,28 @@
 <pre class="code">forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</pre>
 <p> See also <a href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</a>. </p>
 </div>
-<a name="N102A2"></a><a name="catalog"></a>
-<h4 class="faq">3.8.  How do i configure my favourite XML editor or parser to find the local Forrest
+<a name="N102D0"></a><a name="project-logo-svg"></a>
+<h4 class="faq">3.8.  
+        The project logo that is generated from SVG is truncating my project name.
+      </h4>
+<div align="right">
+<a href="#project-logo-svg-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+          In a 'forrest seed site' the project and the group logo are generated from a
+          Scalable Vector Graphics (SVG) file, using the text from the
+          <span class="codefrag">&lt;project-name&gt;</span> and
+          <span class="codefrag">&lt;group-name&gt;</span> elements of the <span class="codefrag">skinconf.xml</span> file.
+          If you have a long project-name then you may need to adjust the width of the image.
+          Perhaps you want to change the colours too. Edit the file at
+          <span class="codefrag">src/documentation/content/xdocs/images/project.svg</span> and adjust the "width"
+          attribute of the &lt;svg&gt; element. For further details see
+          <a href="http://www.w3.org/Graphics/SVG/">SVG</a> resources.
+        </p>
+</div>
+<a name="N102E8"></a><a name="catalog"></a>
+<h4 class="faq">3.9.  How do i configure my favourite XML editor or parser to find the local Forrest
         DTDs? </h4>
 <div align="right">
 <a href="#catalog-menu">^</a>
@@ -924,8 +996,8 @@
 <p> Notes are provided for various tools at <a href="../docs/catalog.html">Using Catalog Entity
             Resolver for local DTDs</a>. </p>
 </div>
-<a name="N102AE"></a><a name="skin"></a>
-<h4 class="faq">3.9.  How to make the site look better and change its skin? </h4>
+<a name="N102F4"></a><a name="skin"></a>
+<h4 class="faq">3.10.  How to make the site look better and change its skin? </h4>
 <div align="right">
 <a href="#skin-menu">^</a>
 </div>
@@ -936,8 +1008,8 @@
 <p> See notes about <a href="../docs/your-project.html#skins">configuration</a> of the skins.
           Some projects may have special needs and can define their <a href="../docs/your-project.html#new_skin">own skin</a>. </p>
 </div>
-<a name="N102C5"></a><a name="xsp"></a>
-<h4 class="faq">3.10. How do I enable XSP processing?</h4>
+<a name="N1030B"></a><a name="xsp"></a>
+<h4 class="faq">3.11. How do I enable XSP processing?</h4>
 <div align="right">
 <a href="#xsp-menu">^</a>
 </div>
@@ -984,8 +1056,8 @@
 </ol>
 <p>See also the <a href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</a> Wiki page.</p>
 </div>
-<a name="N10300"></a><a name="breadcrumbs"></a>
-<h4 class="faq">3.11. How do breadcrumbs work? Why don't they work locally?</h4>
+<a name="N10346"></a><a name="breadcrumbs"></a>
+<h4 class="faq">3.12. How do breadcrumbs work? Why don't they work locally?</h4>
 <div align="right">
 <a href="#breadcrumbs-menu">^</a>
 </div>
@@ -1003,8 +1075,8 @@
           are viewing the site locally, there is no domain and so there will be no extra
           breadcrumbs, only the ones that are specified in <span class="codefrag">skinconf.xml</span>. </p>
 </div>
-<a name="N10315"></a><a name="run_port"></a>
-<h4 class="faq">3.12. How do I make forrest run listen on a different port?</h4>
+<a name="N1035B"></a><a name="run_port"></a>
+<h4 class="faq">3.13. How do I make forrest run listen on a different port?</h4>
 <div align="right">
 <a href="#run_port-menu">^</a>
 </div>
@@ -1019,9 +1091,9 @@
         
 </p>
 </div>
-<a name="N10329"></a><a name="old_faqs"></a>
+<a name="N1036F"></a><a name="old_faqs"></a>
 <h3 class="underlined_5">4. Older version: 0.6</h3>
-<a name="N1032D"></a><a name="old_claimed_patterns"></a>
+<a name="N10373"></a><a name="old_claimed_patterns"></a>
 <h4 class="faq">4.1. Some of my files are not being processed because they use common filenames. </h4>
 <div align="right">
 <a href="#old_claimed_patterns-menu">^</a>
@@ -1037,9 +1109,9 @@
           with this issue (<a href="http://issues.cocoondev.org/browse/FOR-217">FOR-217</a>).
         </p>
 </div>
-<a name="N1033F"></a><a name="general"></a>
+<a name="N10385"></a><a name="general"></a>
 <h3 class="underlined_5">5. General</h3>
-<a name="N10343"></a><a name="generating_menus"></a>
+<a name="N10389"></a><a name="generating_menus"></a>
 <h4 class="faq">5.1. What is the relationship between site.xml and book.xml? </h4>
 <div align="right">
 <a href="#generating_menus-menu">^</a>
@@ -1053,7 +1125,7 @@
           <span class="codefrag">site.xml</span>-generated menus aren't appropriate. See <a href="../docs/linking.html">Menus and
             Linking</a>. </p>
 </div>
-<a name="N1035E"></a><a name="docbook"></a>
+<a name="N103A4"></a><a name="docbook"></a>
 <h4 class="faq">5.2.  How do I use DocBook as the xml documentation format? </h4>
 <div align="right">
 <a href="#docbook-menu">^</a>
@@ -1094,7 +1166,7 @@
           different DTDs, then see <a href="../docs/your-project.html#new_dtd">Using Forrest</a> for
           configuration guidance. </p>
 </div>
-<a name="N10382"></a><a name="version"></a>
+<a name="N103C8"></a><a name="version"></a>
 <h4 class="faq">5.3.  How to report which version of Forrest is being used and the properties that are
         set? </h4>
 <div align="right">
@@ -1107,7 +1179,7 @@
           watch the build messages. Doing <span class="codefrag">'forrest -v'</span> will provide verbose build
           messages. </p>
 </div>
-<a name="N10396"></a><a name="logs"></a>
+<a name="N103DC"></a><a name="logs"></a>
 <h4 class="faq">5.4.  Where are the log files to find more infomation about errors? </h4>
 <div align="right">
 <a href="#logs-menu">^</a>
@@ -1126,7 +1198,7 @@
 <p> Doing <span class="codefrag">'forrest -v'</span> will provide verbose build messages to the standard
           output. </p>
 </div>
-<a name="N103BA"></a><a name="how_can_I_help"></a>
+<a name="N10400"></a><a name="how_can_I_help"></a>
 <h4 class="faq">5.5.  How to help? </h4>
 <div align="right">
 <a href="#how_can_I_help-menu">^</a>
@@ -1137,7 +1209,7 @@
           particularly from newcomers&mdash;often, close proximity blinds software developers to
           faults that are obvious to everyone else. Don't be shy! </p>
 </div>
-<a name="N103C6"></a><a name="patch"></a>
+<a name="N1040C"></a><a name="patch"></a>
 <h4 class="faq">5.6.  How to contribute a patch? </h4>
 <div align="right">
 <a href="#patch-menu">^</a>

Modified: forrest/site/0.7/docs/faq.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.pdf?rev=178944&r1=178943&r2=178944&view=diff
==============================================================================
Binary files - no diff available.

Modified: forrest/site/0.7/docs/faq.xml
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/faq.xml?rev=178944&r1=178943&r2=178944&view=diff
==============================================================================
--- forrest/site/0.7/docs/faq.xml (original)
+++ forrest/site/0.7/docs/faq.xml Sun May 29 04:45:40 2005
@@ -55,7 +55,45 @@
           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>
+      </section><section id="site-xml"><title>2.2. 
+        How to use the <code>site.xml</code> configuration file for menus and linking.
+      </title>
+        <p>
+          The <code>site.xml</code> configuration file is used for two different purposes:
+          defining the left-hand navigation menus, and as a method for defining references
+          to be used when linking between documents.
+          This file is fully explained in
+          <link href="site:linking">Menus and Linking</link>. Here is a precis:
+        </p>
+        <p>
+          Use unique element names. The labels can be whatever text you want.
+        </p>
+        <source xml:space="preserve">&lt;faq label="FAQs" href="faq.html"&gt;
+  &lt;tech label="Technical" href="faq-tech.html"&gt;
+    &lt;docbook href="#docbook"/&gt;
+    &lt;ignoring_javadocs href="#ignoring_javadocs"/&gt;
+  &lt;/tech&gt;
+  &lt;user label="User" href="faq-user.html"&gt;
+&lt;/faq&gt;</source>
+        <p>
+          That will create a menu like this with three links:
+        </p>
+        <source xml:space="preserve">FAQs
+   Technical
+   User</source>
+
+        <p>
+          These documents can be linked to from other documents, like this:
+        </p>
+        <source xml:space="preserve">&lt;a href="site:faq/tech"&gt; link to the top of the Tech FAQs
+&lt;a href="site:faq/tech/docbook"&gt; link to the DocBook FAQ in the Tech FAQs</source>
+
+        <p>
+          If that "docbook" entry was a unique name in your site.xml then you
+          can shorten that latter link:
+        </p>
+        <source xml:space="preserve">&lt;a href="site:docbook"&gt; link to the DocBook FAQ in the Tech FAQs</source>
+      </section><section id="PDF-output"><title>2.3. 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">
   &lt;about tab="home" label="About" href=""&gt;
@@ -69,7 +107,7 @@
           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>
-      </section><section id="pageBreaks"><title>2.3. How do I insert page breaks into documents?</title>
+      </section><section id="pageBreaks"><title>2.4. How do I insert page breaks into documents?</title>
         <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>
@@ -83,16 +121,16 @@
         </p>
         <source xml:space="preserve"> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
           margin-bottom: 0; page-break-after: always; } </source>
-      </section><section id="clickable-email-address"><title>2.4. How can I generate html-pages to show a 'clickable' email-address (of the
+      </section><section id="clickable-email-address"><title>2.5. How can I generate html-pages to show a 'clickable' email-address (of the
         author-element)?</title>
         <p>You would override <code>
             $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
           "headers/authors" template. </p>
-      </section><section id="link_raw"><title>2.5. How do I link to raw files such as config.txt and brochure.pdf? </title>
+      </section><section id="link_raw"><title>2.6. How do I link to raw files such as config.txt and brochure.pdf? </title>
         <p>Handling of raw files was significantly changed in Forrest 0.7. See 
           <link href="site:upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for
           all the details.</p>
-      </section><section id="pdf_images"><title>2.6. Images don't display in PDFs. How do I fix this?</title>
+      </section><section id="pdf_images"><title>2.7. 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 requires third-party jars to be
           added. FOP natively handles BMP, GIF, JPG, TIFF and EPS (with a few limitations). FOP can
@@ -109,7 +147,7 @@
           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>
-      </section><section id="index.html"><title>2.7.  The tab link in my site incorrectly assumes that 'index.html' is present in the
+      </section><section id="index.html"><title>2.8.  The tab link in my site incorrectly assumes that 'index.html' is present in the
         linked-to directory. How do I fix this? </title>
         <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
@@ -122,7 +160,7 @@
   &lt;map:match pattern="manual"&gt;
     &lt;map:redirect-to uri="manual/Introduction.html"/&gt;
   &lt;/map:match&gt;</source>
-      </section><section id="defaultFileName"><title>2.8.  How can I change the default file name that Forrest will look for when I request a
+      </section><section id="defaultFileName"><title>2.9.  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> ? </title>
         <p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
           make the following changes:</p>
@@ -140,7 +178,7 @@
   &lt;/map:pipeline&gt;
           </source></li>
         </ol>
-      </section><section id="defaultStartPage"><title>2.9.  How can I use a start-up-page other than index.html? </title>
+      </section><section id="defaultStartPage"><title>2.10.  How can I use a start-up-page other than index.html? </title>
         <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>
@@ -159,12 +197,12 @@
           <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>
-      </section><section id="label-entity"><title>2.10.  How to use special characters in the labels of the site.xml file? </title>
+      </section><section id="label-entity"><title>2.11.  How to use special characters in the labels of the site.xml file? </title>
         <p> Use the numeric values for character entities. For example, rather than using
             <code>&amp;ouml;</code> use <code>&amp;#246;</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>
-      </section><section id="encoding"><title>2.11. Does Forrest handle accents for non-English languages?</title>
+      </section><section id="encoding"><title>2.12. Does Forrest handle accents for non-English languages?</title>
         <p>Yes, Forrest can process text in any language, so you can include:</p>
         <ul>
           <li>accents: á é í ó ú</li>
@@ -201,7 +239,7 @@
         <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.12.  How can I make Forrest properly clean up the build/site-directory? </title>
+      </section><section id="cleanSite"><title>2.13.  How can I make Forrest properly clean up the build/site-directory? </title>
         <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>
@@ -282,17 +320,31 @@
             <code>-Djava.awt.headless=true</code>, like this: </p>
         <source xml:space="preserve">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>
-      </section><section id="catalog"><title>3.8.  How do i configure my favourite XML editor or parser to find the local Forrest
+      </section><section id="project-logo-svg"><title>3.8.  
+        The project logo that is generated from SVG is truncating my project name.
+      </title>
+        <p>
+          In a 'forrest seed site' the project and the group logo are generated from a
+          Scalable Vector Graphics (SVG) file, using the text from the
+          <code>&lt;project-name&gt;</code> and
+          <code>&lt;group-name&gt;</code> elements of the <code>skinconf.xml</code> file.
+          If you have a long project-name then you may need to adjust the width of the image.
+          Perhaps you want to change the colours too. Edit the file at
+          <code>src/documentation/content/xdocs/images/project.svg</code> and adjust the "width"
+          attribute of the &lt;svg&gt; element. For further details see
+          <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
+        </p>
+      </section><section id="catalog"><title>3.9.  How do i configure my favourite XML editor or parser to find the local Forrest
         DTDs? </title>
         <p> Notes are provided for various tools at <link href="site:catalog">Using Catalog Entity
             Resolver for local DTDs</link>. </p>
-      </section><section id="skin"><title>3.9.  How to make the site look better and change its skin? </title>
+      </section><section id="skin"><title>3.10.  How to make the site look better and change its skin? </title>
         <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>
-      </section><section id="xsp"><title>3.10. How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</title>
+      </section><section id="xsp"><title>3.11. 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
@@ -322,7 +374,7 @@
           </li>
         </ol>
         <p>See also the <link href="http://wiki.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
-      </section><section id="breadcrumbs"><title>3.11. How do breadcrumbs work? Why don't they work locally?</title>
+      </section><section id="breadcrumbs"><title>3.12. 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">
@@ -335,7 +387,7 @@
           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>
-      </section><section id="run_port"><title>3.12. How do I make <code>forrest run</code> listen on a different port?</title>
+      </section><section id="run_port"><title>3.13. How do I make <code>forrest run</code> listen on a different port?</title>
         <p>
           <code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
         </p>

Modified: forrest/site/0.7/docs/linking.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/linking.html?rev=178944&r1=178943&r2=178944&view=diff
==============================================================================
--- forrest/site/0.7/docs/linking.html (original)
+++ forrest/site/0.7/docs/linking.html Sun May 29 04:45:40 2005
@@ -505,10 +505,13 @@
           "<span class="codefrag">http://xml.apache.org/commons/resolver/</span>"</li>
       
 </ul>
+<p>
+        See another <a href="../docs/faq.html#site-xml">explained example</a>.
+      </p>
 </div>
 
     
-<a name="N100A2"></a><a name="menu_generation"></a>
+<a name="N100A9"></a><a name="menu_generation"></a>
 <h2 class="underlined_10">Generating Menus</h2>
 <div class="section">
 <p>
@@ -539,7 +542,7 @@
       defaults to "<span class="codefrag">index.html</span>" if no value is supplied. Therefore the
       link for the howto tab is <span class="codefrag">community/howto/index.html</span>
 </p>
-<a name="N100E9"></a><a name="tabs-external"></a>
+<a name="N100F0"></a><a name="tabs-external"></a>
 <h3 class="underlined_5">Tabs for External Resources</h3>
 <p>A tab can refer to an external resource by using the 
         "<span class="codefrag">href</span>" attribute instead of the "<span class="codefrag">dir</span>" attribute.
@@ -552,7 +555,7 @@
         is left unmodified by Forrest unless it is root-relative and obviously 
         specifies a directory (ends in '/'). In which case /index.html will be 
         added.</p>
-<a name="N10109"></a><a name="selecting-entries"></a>
+<a name="N10110"></a><a name="selecting-entries"></a>
 <h3 class="underlined_5">Selecting menu entries</h3>
 <p>Forrest decides which menu entries to display, by examining the
           "<span class="codefrag">tab</span>" attributes in the <span class="codefrag">site.xml</span> file. The children of 
@@ -605,14 +608,14 @@
           value of "<span class="codefrag">home</span>".  Forrest will select <em>all nodes with
             tab="home"</em> and put them in the menu.
         </p>
-<a name="N10163"></a><a name="other-menu-selection"></a>
+<a name="N1016A"></a><a name="other-menu-selection"></a>
 <h3 class="underlined_5">Alternative menu selection mechanisms.</h3>
 <p>
           The "<span class="codefrag">tab</span>" attribute-based scheme for selecting a menu's
           entries is not the only one, although it is the most flexible.  Here
           we describe a few alternatives.
         </p>
-<a name="N1016F"></a><a name="dir-menu-selection"></a>
+<a name="N10176"></a><a name="dir-menu-selection"></a>
 <h4>Directory-based selection</h4>
 <p>In this scheme, each tab corresponds to a directory within the
             site.  All content below that directory is included in the menu.</p>
@@ -635,7 +638,7 @@
               entries.</li>
           
 </ul>
-<a name="N1019F"></a><a name="book-menu-selection"></a>
+<a name="N101A6"></a><a name="book-menu-selection"></a>
 <h4>Specifying menus with book.xml</h4>
 <p>
             Historically, menus in Forrest have been generated from a
@@ -646,7 +649,7 @@
             that led to obsolescence of book.xml files.  In general, however, we
             recommend that users avoid <span class="codefrag">book.xml</span> files.
           </p>
-<a name="N101BC"></a><a name="tab-selection"></a>
+<a name="N101C3"></a><a name="tab-selection"></a>
 <h3 class="underlined_5">Selecting the current tab</h3>
 <p>
           The tab selection algorithm is quite simple: the tab with the
@@ -658,7 +661,7 @@
 </div>
 
     
-<a name="N101D3"></a><a name="toc-generation"></a>
+<a name="N101DA"></a><a name="toc-generation"></a>
 <h2 class="underlined_10">Table of Contents Generation</h2>
 <div class="section">
 <p>Each page can have an automatically generated table of contents. This
@@ -704,10 +707,10 @@
 </div>
     
     
-<a name="N10208"></a><a name="linking"></a>
+<a name="N1020F"></a><a name="linking"></a>
 <h2 class="underlined_10">Linking systems</h2>
 <div class="section">
-<a name="N1020E"></a><a name="direct-linking"></a>
+<a name="N10215"></a><a name="direct-linking"></a>
 <h3 class="underlined_5">Direct linking</h3>
 <p>
           In earlier versions of Forrest (and in similar systems), there has
@@ -726,7 +729,7 @@
           typically renders to multiple output formats (HTML and PDF), links in
           one of them (here, the PDF) are likely to break.
         </p>
-<a name="N10233"></a><a name="indirect-linking"></a>
+<a name="N1023A"></a><a name="indirect-linking"></a>
 <h3 class="underlined_5">Indirect linking</h3>
 <p>
           Forrest's solution is simple: instead of &lt;a href="todo.html"&gt;,
@@ -754,7 +757,7 @@
           "idea" of "the todo file".  It doesn't matter where it physically lives;
           that will be sorted out by Forrest.
         </p>
-<a name="N1025A"></a><a name="resolve-site-uris"></a>
+<a name="N10261"></a><a name="resolve-site-uris"></a>
 <h4>Resolving site: URIs</h4>
 <p>
             So how does "<span class="codefrag">site:todo</span>" get resolved?  A full answer
@@ -789,7 +792,7 @@
             "new_content_type" its own XML file, or a node in another file, in
             another category.
           </p>
-<a name="N10298"></a><a name="resolve-ext-uris"></a>
+<a name="N1029F"></a><a name="resolve-ext-uris"></a>
 <h4>ext: URIs: linking to external URLs</h4>
 <p>
             The "<span class="codefrag">ext:</span>" scheme was created partly to demonstrate the
@@ -824,7 +827,7 @@
             Specifically, the "@href" aggregation makes defining large numbers of
             related URLs easy.
           </p>
-<a name="N102CB"></a><a name="source-uris"></a>
+<a name="N102D2"></a><a name="source-uris"></a>
 <h4>Theory: source URIs</h4>
 <p>
             The "<span class="codefrag">site:</span>" URIs like "<span class="codefrag">site:todo</span>" are examples of
@@ -840,7 +843,7 @@
             in the destination URI space, just like exotic XML source formats are
             translated into plain old HTML in the output.
           </p>
-<a name="N102EA"></a><a name="future-schemes"></a>
+<a name="N102F1"></a><a name="future-schemes"></a>
 <h4>Future schemes</h4>
 <p>
             So far, the "<span class="codefrag">site:</span>" and "<span class="codefrag">ext:</span>" schemes are defined.
@@ -910,7 +913,7 @@
           </p>
 </div>
     
-<a name="N1038D"></a><a name="concept"></a>
+<a name="N10394"></a><a name="concept"></a>
 <h2 class="underlined_10">Concept</h2>
 <div class="section">
 <p>
@@ -925,7 +928,7 @@
       </p>
 </div>
     
-<a name="N103A4"></a><a name="implementation"></a>
+<a name="N103AB"></a><a name="implementation"></a>
 <h2 class="underlined_10">Implementation</h2>
 <div class="section">
 <p>Full details on the implementation of

Modified: forrest/site/0.7/docs/linking.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/linking.pdf?rev=178944&r1=178943&r2=178944&view=diff
==============================================================================
Binary files - no diff available.



Mime
View raw message