Return-Path: 
 <rat-commits-return-533-apmail-incubator-rat-commits-archive=incubator.apache.org@incubator.apache.org>
X-Original-To: apmail-incubator-rat-commits-archive@minotaur.apache.org
Delivered-To: apmail-incubator-rat-commits-archive@minotaur.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
	by minotaur.apache.org (Postfix) with SMTP id CC4599937
	for <apmail-incubator-rat-commits-archive@minotaur.apache.org>;
 Mon, 31 Oct 2011 20:58:24 +0000 (UTC)
Received: (qmail 10607 invoked by uid 500); 31 Oct 2011 20:58:24 -0000
Delivered-To: apmail-incubator-rat-commits-archive@incubator.apache.org
Received: (qmail 10580 invoked by uid 500); 31 Oct 2011 20:58:24 -0000
Mailing-List: contact rat-commits-help@incubator.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:rat-commits-help@incubator.apache.org>
List-Unsubscribe: <mailto:rat-commits-unsubscribe@incubator.apache.org>
List-Post: <mailto:rat-commits@incubator.apache.org>
List-Id: <rat-commits.incubator.apache.org>
Reply-To: rat-dev@incubator.apache.org
Delivered-To: mailing list rat-commits@incubator.apache.org
Received: (qmail 10573 invoked by uid 99); 31 Oct 2011 20:58:24 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 31 Oct 2011 20:58:24 +0000
X-ASF-Spam-Status: No, hits=-2000.0 required=5.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 31 Oct 2011 20:58:23 +0000
Received: from eris.apache.org (localhost [127.0.0.1])
	by eris.apache.org (Postfix) with ESMTP id EF92123889EB;
	Mon, 31 Oct 2011 20:58:02 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1195668 - in /incubator/rat/whisker/trunk/src/site:
 apt/meta-data.apt resources/examples/ resources/examples/template-license.xml
Date: Mon, 31 Oct 2011 20:58:02 -0000
To: rat-commits@incubator.apache.org
From: rdonkin@apache.org
X-Mailer: svnmailer-1.0.8-patched
Message-Id: <20111031205802.EF92123889EB@eris.apache.org>

Author: rdonkin
Date: Mon Oct 31 20:58:02 2011
New Revision: 1195668

URL: http://svn.apache.org/viewvc?rev=1195668&view=rev
Log:
Documented how template licenses work.

Added:
    incubator/rat/whisker/trunk/src/site/resources/examples/
    incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml   (with props)
Modified:
    incubator/rat/whisker/trunk/src/site/apt/meta-data.apt

Modified: incubator/rat/whisker/trunk/src/site/apt/meta-data.apt
URL: http://svn.apache.org/viewvc/incubator/rat/whisker/trunk/src/site/apt/meta-data.apt?rev=1195668&r1=1195667&r2=1195668&view=diff
==============================================================================
--- incubator/rat/whisker/trunk/src/site/apt/meta-data.apt (original)
+++ incubator/rat/whisker/trunk/src/site/apt/meta-data.apt Mon Oct 31 20:58:02 2011
@@ -122,6 +122,99 @@ Whisker Meta-Data Model
 ]>
 ----------------------------------------
 
+
+* Some More Advanced Features Explained
+
+** Templates For License Families
+
+ Some familiar open source licenses (for example, 
+ the {{{http://www.opensource.org/licenses/BSD-3-Clause}BSD 3-Clause License}}) are better understood
+ as families of licenses. Each family is based on a parameterised template. When the license is used, 
+ an appropriate value is substituted for each parameter.
+ 
+ Whisker supports template licenses with parameter substitution. Parameter names are defined by <<<parameter-name>>> elements
+ within a <<<template>>> block. 
+
++------------------------------------------------------------------------+
+        <license ...
+            <template>
+                <parameter-name>foo</parameter-name>
+                ...
+            </template>
+            ...
++------------------------------------------------------------------------+ 
+ 
+ Each <<<$\{parameter name\}>>> within the license <<<text>>> will be substituted by 
+ the <<<value>>> with matching <<<name>>> within a <<<parameter>>> in a <<<license-parameters>>> block. When referring
+ to a template license, this block is required. All parameter names defined must have exactly one value specified.
+
++------------------------------------------------------------------------+
+    <license-parameters>
+      <parameter>
+        <name>foo</name>
+        <value>bar</value>
+      </parameter>
+      ...
++------------------------------------------------------------------------+
+
+ 
+*** A Template Example 
+
+ This simple template example features a <<<Hello, World>>> license. 
+ Source is {{{./examples/template-license.xml}here}}.
+
++------------------------------------------------------------------------+
+<manifest>
+    <licenses>
+        <!-- A template license -->
+        <license id='TL1' name='A Template License'>
+            <!-- 
+                Parameter names in this section.
+                Values must be set for all parameters. 
+                                                -->
+            <template>
+                <!-- ${FOO} will be substituted wherever it occurs -->
+                <parameter-name>FOO</parameter-name>
+                <!-- ${BAR} will be substituted wherever it occurs -->
+                <parameter-name>BAR</parameter-name>
+            </template>
+            <!-- Wherever ${FOO} and ${BAR} are found will be substituted.-->
+            <text>
+                ${BAR}, ${FOO}.            
+            </text>
+        </license>
+    </licenses>
+    ...
+    <within dir='.'>
+        <with-license id='TL1'>
+            <!-- 
+                When a template license is referenced,
+                a license-parameter block must exist
+                and contain one value for each defined
+                parameter 
+                                                        -->
+            <license-parameters>
+                <parameter>
+                    <!-- Replace ${FOO} with 'world' -->
+                    <name>FOO</name>
+                    <value>world</value>
+                </parameter>
+                <parameter>
+                    <!-- Replace ${BAR} with 'Hello' -->
+                    <name>BAR</name>
+                    <value>hello</value>
+                </parameter>
+            </license-parameters>
+            <!--
+                After substituting values for parameters,
+                the license reads: Hello, world.
+                                                        -->                                        
+        </with-license>
+    </within>
+</manifest>
++------------------------------------------------------------------------+
+
+
 * A Sample 
 
   Describes components assembled into the {{{http://james.apache.org}Apache James}} 

Added: incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml
URL: http://svn.apache.org/viewvc/incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml?rev=1195668&view=auto
==============================================================================
--- incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml (added)
+++ incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml Mon Oct 31 20:58:02 2011
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.    
+-->
+<!DOCTYPE manifest [
+
+<!ELEMENT manifest (licenses, notices, organisations, 
+    primary-license, primary-notice?, primary-organisation?, within*)>
+<!-- Collects license descriptions -->    
+<!ELEMENT licenses (license*)>
+<!-- Describes a copyright license -->
+<!ELEMENT license (template?, text)>
+<!ATTLIST license name CDATA #REQUIRED>
+<!ATTLIST license url CDATA #IMPLIED>
+<!ATTLIST license id ID #REQUIRED>
+<!-- Some licenses require a link to source code -->
+<!ATTLIST license requires-source (yes|no) "no">
+<!-- The words expressing the license -->
+<!ELEMENT text (#PCDATA)>
+<!-- Template license families have parameterised license wording -->
+<!ELEMENT template (parameter-name+)>
+<!-- The name of a parameter to be substituted -->
+<!ELEMENT parameter-name (#PCDATA)>
+
+<!-- Collects notice descriptions -->
+<!ELEMENT notices (notice*)>
+<!-- Describes notice text to be preserved -->
+<!ELEMENT notice (#PCDATA)>
+<!ATTLIST notice id ID #REQUIRED>
+
+<!-- Collections organisation descriptions -->
+<!ELEMENT organisations (organisation*)>
+<!-- Descibres an upstream organisation -->
+<!ELEMENT organisation EMPTY>
+<!ATTLIST organisation id ID #REQUIRED>
+<!ATTLIST organisation name CDATA #REQUIRED>
+<!ATTLIST organisation url CDATA #IMPLIED>
+
+<!-- The primary license for the application -->
+<!ELEMENT primary-license EMPTY>
+<!-- References the license by id attribute -->
+<!ATTLIST primary-license id IDREF #REQUIRED>
+
+<!-- The text of the application's primary notice -->
+<!ELEMENT primary-notice (#PCDATA)>
+
+<!-- The organisation responsible for the application -->
+<!ELEMENT primary-organisation EMPTY>
+<!-- References the organisation by id attribute -->
+<!ATTLIST primary-organisation id IDREF #REQUIRED>
+
+<!-- Collects the resources within a directory-->
+<!ELEMENT within (public-domain?, with-license*)>
+<!ATTLIST within dir CDATA #REQUIRED>
+
+<!-- Collects resources sharing licensing qualities -->
+<!ELEMENT with-license (copyright-notice?, license-parameters?, by-organisation*)>
+<!-- Refers to a license defined above by ID -->
+<!ATTLIST with-license id IDREF #REQUIRED>
+<!-- A copyright claim -->
+<!ELEMENT copyright-notice (#PCDATA)>
+<!-- Values substituted into the text of template licenses -->
+<!ELEMENT license-parameters (parameter*)>
+<!ELEMENT parameter (name, value)>
+<!ELEMENT name (#PCDATA)>
+<!ELEMENT value (#PCDATA)>
+
+<!-- Collects resources in the public domain -->
+<!ELEMENT public-domain (by-organisation*)>
+
+<!-- Collects resources issued by an upstream organisation -->
+<!ELEMENT by-organisation (resource*)>
+<!ATTLIST by-organisation id IDREF #REQUIRED>
+
+<!-- Contained in the application release -->
+<!ELEMENT resource EMPTY>
+<!ATTLIST resource name CDATA #REQUIRED>
+<!ATTLIST resource sha1 CDATA #IMPLIED>
+<!ATTLIST resource notice IDREF #IMPLIED>
+<!ATTLIST resource source CDATA #IMPLIED>
+]>
+<manifest>
+    <licenses>
+        <!-- A template license -->
+        <license id='TL1' name='A Template License'>
+            <!-- 
+                Parameter names in this section.
+                Values must be set for all parameters. 
+                                                -->
+            <template>
+                <!-- ${FOO} will be substituted wherever it occurs -->
+                <parameter-name>FOO</parameter-name>
+                <!-- ${BAR} will be substituted wherever it occurs -->
+                <parameter-name>BAR</parameter-name>
+            </template>
+            <!-- Wherever ${FOO} and ${BAR} are found will be substituted.-->
+            <text>
+                ${BAR}, ${FOO}.            
+            </text>
+        </license>
+    </licenses>
+    <notices/>
+    <organisations>
+        <organisation id='example.org' name='An Example Organisation'/>
+    </organisations>
+    <primary-license id='TL1'/>
+    <within dir='.'>
+        <with-license id='TL1'>
+            <!-- 
+                When a template license is referenced,
+                a license-parameter block must exist
+                and contain one value for each defined
+                parameter 
+                                                        -->
+            <license-parameters>
+                <parameter>
+                    <!-- Replace ${FOO} with 'world' -->
+                    <name>FOO</name>
+                    <value>world</value>
+                </parameter>
+                <parameter>
+                    <!-- Replace ${BAR} with 'Hello' -->
+                    <name>BAR</name>
+                    <value>hello</value>
+                </parameter>
+            </license-parameters>
+            <!--
+                After substituting values for parameters,
+                the license reads: Hello, world.
+                                                        --> 
+        </with-license>
+    </within>
+</manifest>
\ No newline at end of file

Propchange: incubator/rat/whisker/trunk/src/site/resources/examples/template-license.xml
------------------------------------------------------------------------------
    svn:eol-style = native