Demonstration of linking

+ Using site.xml to manage the links +

As you will have discovered, using pathnames with ../../ etc. will + get very nasty. Real problems occur when you use a smart text editor + that tries to manage the links for you. For example, it will have + trouble linking to the raw content files which are not yet in their + final location. +

+ Links and filenames are bound to change and re-arrange. It is + essential to only change those links in one central place, not in every + document. +

+ The "site.xml" configuration file to the rescue. It maps + symbolic names to actual resources. +

+ +

+ Basic link to internal generated pages +

This single entry ...

+ ]]> +

+ enables a simple link to a generated document, which corresponds to + content/xdocs/index.xml ... +

+ ]]>site:index]]> +

+ +

+ Group some items +

This compound entry ...

+ + + ... + +]]> +

+ enables a link to a generated document, which corresponds to + content/xdocs/samples/index.xml ... +

+ ]]>site:samples]]> +

+ and a link to a generated document, which corresponds to + content/xdocs/samples/faq.xml ... +

+ +]]>site:faq]]> +which can also be a complete reference +]]>site:samples/faq]]> + +

+ +

+ Fragment identifiers +

This compound entry ...

+ + + +

+ + ... + +]]> +

+ enables a link to a fragment identifier within the + samples/sample.html document ... +

+ ]]>site:samples/sample/section]]> +

+ +

+ Define items for raw content +

This entry ...

+ ]]> +

+ enables a link to a raw document, which corresponds to + content/hello.pdf ... +

+ ]]>site:hello_print]]> + +

+ +

+ External links +

This compound entry ...

+ + + + + + +]]> +

+ enables a link to an external URL ... +

+ ]]>ext:forrest]]> +

+ and a link to another external URL ... +

+ +]]>ext:linking]]> +which can also be a complete reference +]]>ext:forrest/linking]]> + +

+ and a link to another external URL with a fragment identifier ... +

+ +]]>ext:webapp]]> +which can also be a complete reference +]]>ext:forrest/webapp]]> + +

+ +

+ Images +

+ Images (and other resources) are handled by the main/webapp/resource.xmap sitemap. + It uses the main/webapp/locationmap.xml to look in various locations for images. + As usual, the first match wins. +

Here is the locationmap snippet ...

+ + + +]]> +

Which means look first in a project-defined images directory, then in the + default location (which is usually src/documentation/resources/images/), + then in the old default location (src/documentation/content/xdocs/images/), + then relative to the root of your xdocs.

+ The document author specifies the final image locations with these various + "src=" links. Behind-the-scenes Cocoon handles the requests + using the sitemap and locationmap. +

This sample has the following image locations:

+ +

Here is the effect of the various image links ...

+ + <img src="/images/icon-a.png" + ... The source file is found in src/documentation/resources/images/ directory. +
+ + <img src="/images/sub-dir/icon-c.png" + ... The source file is found in src/documentation/resources/images/sub-dir/ directory. +
+ + <img src="/images/icon-e.png" + ... The source file is not found in the normal src/documentation/resources/images/ + so Cocoon looks in the next location and finds the source in + src/documentation/content/xdocs/images/ directory. + This supports backward-compatibility for this old default location. +
+ + <img src="images/icon-a.png" + ... same as example 1 above. Except this time the generated image is relative to the document. +
+ + <img src="../images/icon-a.png" + ... Relative reference. Forrest "absolutizes" the URLs to be like the URLs + in examples 1 and 2 and 3. Then Cocoon looks in the normal locations as described above. + The source file is found in src/documentation/resources/images/ directory. +
+ + <img src="../../images/icon-b.png" + ... Broken relative reference (it points up beyond the document root). + Never mind, Forrest "absolutizes" the URLs to be like the URLs in examples 1 and 2 and 3. + The source file is found in src/documentation/resources/images/ directory. + However there is a problem here. When using Forrest in command-line mode, + the image will be generated outside the document directory. + It is better to use absolute /image/ URLs or be very careful about using + such relative links (Forrest will not repart an error). +
+
+ <img src="/images/ellipse-2.png" + ... Cocoon tried the various locations for a PNG image called + ellipse-2.png but did not find one anywhere. So the next sitemap match + looks for a corresponding + ellipse-2.svg and generates the PNG image on-the-fly. + The source file is found in src/documentation/resources/images/ directory. +

The image links shown above are handled by the resources.xmap using + special matches for the "images" directory in the URI. +

The main/webapp/resources.xmap has another section to deal specifically with PNG images. It looks first for an SVG source file which will be used to generate the PNG image. If that is not found then it looks for an ASCII art source file. Then looks for a pre-prepared PNG image.

+
+ <img src="ellipse.png" + ... Cocoon tried the various locations for a PNG image called + ellipse-2.png but did not find one anywhere. So the next sitemap match + looks for a corresponding + ellipse-2.svg and generates the PNG image on-the-fly. + The source file is found in the current directory src/documentation/content/xdocs/samples/ +
+
+ <img src="cocoon-pryamid.png" + ... ASCII Art. Cocoon did not find a PNG image, nor an SVG file. + So the next sitemap match looks for a corresponding + cocoon-pryamid.aart and generates the PNG image on-the-fly. + The source file is found in the current directory src/documentation/content/xdocs/samples/ +
+ + <img src="icon-d.png" + ... Relative to this document. + The source file is found in the current directory src/documentation/content/xdocs/samples/ +

+ + You might wonder why the above images all show correctly in dynamic + 'forrest run' mode, but some appear to be broken during static docs + generation 'forrest site' mode. The latter is for generating a set + of static docs for deployment to a server. If you used URLs beginning + with a slash, "/images/...", then that is their location. So the + generated docs on the + "forrest zone" demos appear to be broken. + +

+ + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/linking.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/sample.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/sample.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/sample.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/sample.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,407 @@ + + + + +

+ The Apache Forrest xdocs document-v2.0 DTD + The content of this document doesn't make any sense at all. + This is a demonstration document using all possible elements in + the current Apache Forrest xdocs document-v20.dtd + +

+ + + This is a demonstration document using all possible elements in the + current Apache Forrest xdocs document-v20.dtd + (See the DTD changes section at the bottom.) + +

+ Sample Content +

Hint: See the xml source to see how the various + elements are used and see the + + DTD reference documentation. +

+ Block and inline elements +

This is a simple paragraph. Most documents contain a fair amount of + paragraphs. Paragraphs are called .

With the  attribute, you can declare + that whitespace should be preserved, without implying it is in any other + way special.

+ This next paragraph has a class attribute of 'quote'. CSS can + be used to present this  in + a different style than the other paragraphs. The handling of + this quoted paragraph is defined in the <extra-css> + element in the skinconf.xml. +

+ Anyway, like I was sayin', shrimp is the fruit of the sea. You can + barbecue it, boil it, broil it, bake it, sautee it. Dey's uh, + shrimp-kabobs, shrimp creole, shrimp gumbo. Pan fried, deep fried, + stir-fried. There's pineapple shrimp, lemon shrimp, coconut shrimp, + pepper shrimp, shrimp soup, shrimp stew, shrimp salad, shrimp and + potatoes, shrimp burger, shrimp sandwich. That- that's about it. +

A number of in-line elements are available in the DTD, we will show them + inside an unordered list (<ul>):

Here is a simple list item (<li>).
Have you seen the use of the <code> element in the + previous item?
Also, we have  and  + elements to show content ^above or _below the text + baseline.
There is a facility to emphasize certain words using the +   + elements.
We can use + + <icon>s too.
Another possibility is the <img> element: + , + which offers the ability to refer to an image map.
We have elements for hyperlinking: +
+
<a href="faq.html">
+
Use this to + link + to another document. As per normal, this will open the new document + in the same browser window.
+ +
<a href="#section">
+
Use this to + link + to the named anchor in the current document. +
+ +
<a href="faq.html#forrest">
+
Use this to + link + to another document and go to the named anchor. This will open + the new document in the same browser window. +
+
Targetted window control with jump and fork.
+
See demonstration + using class attribute on links. +
+
Oh, by the way, a definition list <dl> was used inside + the previous list item. We could put another +
- unordered list
- inside the list item
+ + + + +
A sample nested table
Or even tables.. +
inside tables..
+
or inside lists, but I believe this liberty gets quickly quite + hairy as you see.
+

So far for the in-line elements, let's look at some paragraph-level + elements.

+ The <fixme> element is used for stuff + which still needs work. Mind the author attribute! + Use the <note> element to draw attention to something, e.g. ...The <code> element is used when the author can't + express himself clearly using normal sentences ;-) + Sleep deprivation can be the result of being involved in an open + source project. (a.k.a. the <warning> element). + + If you want your own labels for notes and + warnings, specify them using the label attribute. + +

Apart from unordered lists, we have ordered lists too, of course.

Item 1
Item 2
This should be 3 if my math is still OK.

+ +

+ Various presentation formats + +

This sample document, written in document-v20 XML can be presented + via Forrest in a number of different formats. The links in the + following list show this document in each of the currently available + formats.

+ +

Each of the formats can be made available as a link near the top of + the page. Actual placement of those links depends on the skin + currently in use. Those links are enabled in the skinconf.xml via the + <disable-XXX-link> elements in the skinconf.xml

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Presentation Format	Description	skinconf.xml Element
HTML	This document in HTML format.	Always generated by default. Cannot be turned off.
XML	This document in its raw XML format.	<disable-xml-link>. By default, set to true, meaning + that this link will not be shown.
PDF	This document as Adobe PDF	<disable-pdf-link>. By default, set to false, meaning + that this link will be shown.
Text	This document as straight text. + For additional information see the Forrest text-output + plugin.	<disable-txt-link>. By default, set to true, meaning + that this link will not be shown.
POD	This document as Perl POD (Plain Old Documentation). Text + with minimal formatting directives. If on a *nix system with perl + installed, see "man perlpod". + For additional information see the Forrest pod-output + plugin.	<disable-pod-link>. By default, set to true, meaning + that this link will not be shown.

+ Using sections +

You can use sections to put some structure in your document. For some + strange historical reason, the section title is an attribute of the + <section> element.

+ Sections, the sequel +

Just some second section.

+ Section 2.1 +

Which contains a subsection (2.1).

+ +

+ Showing preformatted source code +

Enough about these sections. Let's have a look at more interesting + elements, <source> for instance:

+ +// This example is from the book _Java in a Nutshell_ by David Flanagan. +// Written by David Flanagan. Copyright (c) 1996 O'Reilly & Associates. +// You may study, use, modify, and distribute this example for any purpose. +// This example is provided WITHOUT WARRANTY either expressed or implied. + +import java.applet.*; // Don't forget these import statements! +import java.awt.*; + +public class FirstApplet extends Applet { + // This method displays the applet. + // The Graphics class is how you do all drawing in Java. + public void paint(Graphics g) { + g.drawString("Hello World", 25, 50); + } +} +

CDATA sections are used within + <source> elements so that you can write pointy + brackets without needing to escape them with messy + < entities ... +

+ + easy + +]]> +

Please take care to still use a sensible line-length within your + source elements.

+ +

+ Using tables +

And now for a table:

+ + + + + + + + + + + + + + + + +

Table caption

heading cell 1

heading cell 2

heading cell 3

data cell

this data cell spans two columns

+ Tables can be nested: +

+ + + + + + + + + +

column 1	column 2
cell A	cell B

and can include most other elements
such as lists

+ + +

+ Using figures +

And a <figure> to end all of this. + Note that this can also be implemented with an + <img> element. +

+ Using class attribute on links + +

The document-v13 had elements <fork> and <jump>. In + document-v20, those elements no longer exist but the functionality can + be duplicated by using the @class attribute. + Even though the opening of separate windows should be under the + control of the user, these techniques can still be employed.

+ + + + + + + + + + + + + + + + + + + +

Document V1.3	Document V2.0
<fork href="faq.html">	<a class="fork" + href="faq.html">
<jump href="faq.html">	<a class="jump" + href="faq.html">

+ +

+ DTD changes +

See the generated + + DTD reference documentation. +

+ Changes between document-v13 and document-v20 +

Renamed <link> + to <a> +
Removed <fork> + and <jump> in favour of the + <a> element. See demonstration + using class attribute on links. +

+ Changes between document-v12 and document-v13 +

+ All v1.2 docs will work fine as v1.3 DTD. The main change is the + addition of a @class attribute to every element, which enables the + "extra-css" section in the skinconf to be put to good use. +

+ Changes between document-v11 and document-v12 +

+ doc-v12 enhances doc-v11 by relaxing various restrictions that were + found to be unnecessary. +

+ Links ((link|jump|fork) and inline elements (br|img|icon|acronym) are + allowed inside title. +
+ Paragraphs (p|source|note|warning|fixme), table and figure|anchor are + allowed inside li. +
+ Paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table, + figure|anchor are allowed inside definition lists (dd) and tables (td + and dh). +
+ Inline content + (strong|em|code|sub|sup|br|img|icon|acronym|link|jump|fork) is + allowed in strong and em. +

+ + + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/sample.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/static.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/static.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/static.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/static.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,62 @@ + + + + +

+ Static content - including raw un-processed files and documents +

+ +

+ Linking to static content +

+ You can place some types of raw content into the xdocs directory. For example, + you can place a PDF file in src/documentation/content/xdocs and link + to it normally, + <a href="../hello.pdf">hello.pdf</a> + However, note that if the file is one that Forrest is able to process, for example + an HTML file, these files will be processed accordingly.

+ +

+ It is also worth noting that files in the xdocs directory will only be copied + into your final site if there is a link to them somewhere in the site. See the next + section for details of how to include content that is not linked.

+ +

+ For more information see the + Linking demonstration.

+ +

+ Including Static Content that is Not Linked + +

+ You can include raw HTML, PDFs, plain-text, and other files. In your final site by + placing them in the src/documentation/content directory. Files in this + directory will be copied over automatically but will not be processed in any way by + Forrest, that is they will be linked to as raw files.

+ +

+ You can also have sub-directories such as + src/documentation/content/samples/subdir/ which + reflects your main + xdocs/ tree. The raw files will then end up + beside your documents. +

+ + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/static.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/book-sample.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/book-sample.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/book-sample.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/book-sample.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,47 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/book-sample.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/index.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/index.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/index.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/index.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,38 @@ + + + + +

+ Page generated from a sub-directory + + + + +

+ + +

+ A sub-directory +

This was generated from a sub-directory.

When creating new subdirectories, remember that these must + be declared in site.xml or each directory must have a book.xml file. +

+ + + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/subdir/index.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/svg.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/svg.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/svg.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/svg.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,42 @@ + + + + +

+ Using Scalable Vector Graphics (SVG) +

+ +

+ Forrest can deliver raw SVG files for capable browsers, e.g. Firefox. + See example. +

+ Forrest can convert SVG files into Portable Network Graphic (PNG). + See example. Note that Forrest will first + look for a pre-prepared PNG file, and if not found then it will + generate the PNG from the SVG. +

+ Be careful. We only provide a local copy of the SVG 1.0 DTD + so if you use SVG 1.1 then there will be network trips + for the DTDs. + Configure + your local catalog entity resolver for your local DTD copies. +

+ + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/svg.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/usemap.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/usemap.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/usemap.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/usemap.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,61 @@ + + + + +

+ Interactive client-side imagemaps - the usemap attribute +

+ +

+ Imagemap demo +

+ usemap demo +

+ + + + + +

+ Source code + + usemap demo

+ + + + + +

+]]> +

+ + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/usemap.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/xml-entities.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/xml-entities.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/xml-entities.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/xml-entities.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,82 @@ + + + + %symbols-project; +]> + +

+ Using XML entities for character replacements +

+ +

+ All of the normal xml character entities are available for use + in your source documents. + So you can use "™" + for the trademark symbol (™) + and use "ö" + for special accents (ö). +

+ Forrest also has some default sets of symbols. There is one set + for the core of Forrest. These are automatically available + for use in the "document-v*" series of document types. + (If you want to use them in another document type, then you + need to specify them in the document type declaration of your + xml instance documents or in your custom DTD. See below.) +

+ For example, + use "&for-s;" to represent the strong + text string "&for-s;". See the list of available symbols at + main/webapp/resources/schema/entity/symbols-core-v10.ent + which shows that that example entity was declared as + Apache Forrest]]>. +

+ You can supply lists of symbols for your own project too. + Create a fresh site with 'forrest seed' and see the set + src/documentation/resources/schema/symbols-project-v10.ent +

+ For example, + use "&myp-t;" to represent the project name + together with trademark symbol "&myp-t;". +

+ The set of project symbols is already configured. To use the symbols + in your documents, add to the document type declaration. For example, + see the source for this document + (src/documentation/content/xdocs/samples/xml-entites.xml) + which declares the project symbol set ... +

+ + + %symbols-project; +]> + + ... +]]> + + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/samples/xml-entities.xml ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/tabs.xml URL: http://svn.apache.org/viewvc/forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/tabs.xml?view=auto&rev=482028 ============================================================================== --- forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/tabs.xml (added) +++ forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/tabs.xml Sun Dec 3 19:23:29 2006 @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + Propchange: forrest/trunk/whiteboard/forrest2/core/src/examples/forrest1SeedSite/src/xdocs/tabs.xml ------------------------------------------------------------------------------ svn:eol-style = native