Forrest 1.0

# Forrest 1.0 - Working Draft

## Abstract

Forrest 1.0 is the first specification of Forrest (the product), intended to be the reference point for developers and users in the road to making a first stable Forrest release.

## Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This document is under development, and will not be considered final until Forrest 1.0 is released.

This is the First Public Working Draft of the Forrest 1.0 specification. This document has been produced by the Apache Forrest Project developer community as part of the Apache Forrest Project. The authors of this document are the Apache Forrest Project participants.

Publication as a Working Draft does not imply endorsement by the Apache Forrest Project Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Comments on this document are welcome. Please send issues to the public mailing list dev@forrest.apache.org (link to archive). It is appropriate to send discussion email to this address. Please note that comments that you make will be publicly archived and available, do not send information you would not want to see distributed, such as private data.

## 1 Introduction

### 1.1 Reading the Specification

The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.

This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].

### 1.2 How the Specification is Organized

Chapters are arranged by topic.

### 1.3 Documentation Conventions

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

> xhtml2: The XHTML 2.0 namespace
> my: Any user defined namespace

This is only a convention; any namespace prefix may be used in practice.

The following typographical conventions are used to present technical material in this document.

Examples are set off typographically:

Example: Example item

    Example Item

References to external documents appear as follows: [Sample Reference] with links to the references section of this document.

Sample Reference
  Reference - linked to from above.

The following typesetting convention is used for non-normative commentary:

Note:

A gentle explanation to readers.

Editorial note: Editorial Note Name |
Editorial commentary, not intended for final publication.

Issue (sample-implementation-issue):

Issue-Name

A specific issue for which input from implementors is requested, for example as part of the Candidate Recommendation phase.

Resolution:

None recorded.

## Forrest Core

Editorial note: TODOs |
raw files project directory layout config file formats internationalization

### Processing pipeline

This is the conceptual processing pipeline offered by Forrest.

All references to actual source dirs and internal or external formats is generic and are specified elsewhere in this spec.

#### Step 1: Resolution (content)

Forrest has a single conceptual source space, that can initially be thought of as a single directory, the current xdocs dir. Every file that is outside of this directory has to be resolved by a locationmap, so that Forrest sees it all as a single directory in any case.

This source space contains files that a filename and an extension. There should be only one file with a certain name in a certain directory, which will be the main source of our transformation.

For each URL that is requested, there shall be only one source file resolved, which will be our main source.

#### Step 2: Format Transformation (content)

In the second step, Forrest transforms the main source to the intermediate format, which is XHTML2 (also automatic transforms from XHTML1 and HTML will be supported). Transformations from HTML and XHTML will be done in the core, while all others will be done by plugins (input plugins).

Multiple formats can be asked for the same source: the filename asked will be in the following manner.

    name.type.format

Example:

    myfile.content.html
    myfile.javadocs.html
    myfile.html

#### Step 3: Filtering (content)

This is a new step, that adds navigation, metadata, extra content, functionality and transformations to the content stream.

The filtering stages should use different filtering files to not produce markup that is not needed by the view.

Navigation is the addition of the 'tab' and 'linkmap' information to the stream.

Metadata about a page can be added, like the date, page size, etc.

Nuggets of information can be added based on the URL and on the contents of the main source. For example, newsfeeds about the page being processed.

Fbits should be insert only as placeholder that the view can populate them with the actual functionality

Filtering on the main content can be done, like the automatic creation of links based on the site.xml linkmap or footnote processing.

These filtering steps are to be done by plugins (filtering plugins).

#### Step 4: Viewing (presentation)

Based on the view specified, the content is transformed in a format that contains presentation information. Example formats are html, fo (formatting objects) and svg.

Note that this part adds functionality implementation to the content. For example, a search item can be displayed, or widgets can be used. These are fbits, or functionality bits, and are different from nuggets, which are extra content.

Note that fbits are view dependant, so that a view can decide to implement them or not. The configuration of these bits are to be done with the new generic skinconf format and a new templating language.

Example of current fbits are the search pane, the page format selector, etc.

This new templating language will be forrest:templates, which contains forrest:view and forrest:template.

#### Step 5: Theming (presentation)

The view is creating the html-skelleton that is used for theming. Themes are view dependend but e.g. you can write one theme for x view derivatives. Theming adds colors and general appearance info. In html it's css files for example, or the skinconf color information.

#### Step 6: Serializing (presentation)

The presentation is transformed to the actual final format with output plugins. For example a fo presentation can be outputted as xhtml, pdf, rtf, doc, ps, etc.

### Forrest:templates

Forrest:templates or short f:t is a templating language to create views on forrest input-data.

Definition - Forrest-View: View = content (nuggets) + functionality (fbit) + design (style)

We will refer to incoming content as nuggets. Nuggets are pure content (without any information about fct., style,...).

fbits can (but do not have to) use nuggets to implemend (or populate) the actual functionality needed in the requested view.

  fbit containing nuggets (I mean it contains e.g. captions ->i18n nuggets) <forrest:fbit name="fontsize"/>

pure fbit (no content just functionality -> IMO very rare, the example tag would as well contain i18n: close-schliessen-cerrar) <forrest:fbit name="close-window"/>

pure fbit *using* nuggets (e.g. profiling data for the actual view.) <forrest:fbit name="searchbox" type="sport"/>

Normally the nuggets and fbits will be implemented in an overall design. The design is a container concept of storing fbits and nuggets in graphical container (template + hooks). Templates can be used to create the overall design in different media (xhtml, fo,...) of the document.

This design state should only use registered contracts for fbits and nuggets but still have absolute controll over the style.

## A Schemas for Forrest 1.0 config files

To be added.

## B References

### B.1 Normative References

[HTML]
  "HTML 4.01 Specification", D. Raggett, A. Le Hors, I. Jacobs, 24 December 1999.
  Latest version available at: http://www.w3.org/TR/html401
[RFC2119]
  "RFC2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997.
  Available at: http://www.ietf.org/rfc/rfc2119.txt
[RFC2396]
  "RFC2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998.
  This document updates RFC1738 and RFC1808.
  Available at: http://www.ietf.org/rfc/rfc2396.txt
[RFC2854]
  "RFC2854: The text/html Media Type", D. Conolly, L. Masinter, June 2000.
  Available at: http://www.ietf.org/rfc/rfc2854.txt
[RFC3023]
  "RFC3023: XML Media Types", M. Murata, S. St.Laurent, D. Kohn, January 2001.
  This document obsoletes [RFC2376].
  Available at: http://www.ietf.org/rfc/rfc3023.txt
[RFC3066]
  "Tags for the Identification of Languages", H. Alvestrand, January 2001.
  Available at: http://www.ietf.org/rfc/rfc3066.txt
[RFC3236]
  "The 'application/xhtml+xml' Media Type", M. Baker, P. Stark, January 2002.
  Available at: http://www.ietf.org/rfc/rfc3236.txt
[XML]
  "Extensible Markup Language (XML) 1.0 Specification (Second Edition)", T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, 6 October 2000.
  Latest version available at: http://www.w3.org/TR/REC-xml
[XMLNS]
  "Namespaces in XML", T. Bray, D. Hollander, A. Layman, 14 January 1999.
  XML namespaces provide a simple method for qualifying names used in XML documents by associating them with namespaces identified by URI.
  Latest version available at: http://www.w3.org/TR/REC-xml-names
[XMLC14N]
  "Canonical XML Version 1.0", J. Boyer, 15 March 2001.
  This document describes a method for generating a physical representation, the canonical form, of an XML document.
  Latest version available at: http://www.w3.org/TR/xml-c14n

### B.2 Informative References

XHTML Modularization
  Modularization of XHTML, M. Altheim, et. al., 2001. W3C Recommendation available at http://www.w3.org/TR/xhtml-modularization/.
XML Events
  XML Events - An events syntax for XML, Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/xml-events/.

## C Changes (Non-Normative)

To be added.

## D Acknowledgements (Non-Normative)

This document was produced with the participation of current Apache Forrest Project members and of all participants to the public discussion.

## E Development Notes (Non-Normative)

### Decisions and threads

#### [RT] RAW content

Raw content is to be gotten like this:

- for single files one can ask for myfile.source.extension

- for whole dirs, the thing has to be declared in some sitewide metadata

#### [RT] Directory structure and configuration

To be discussed