Return-Path: 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 D698E7D49 for ; Wed, 7 Dec 2011 07:52:11 +0000 (UTC) Received: (qmail 120 invoked by uid 500); 7 Dec 2011 07:52:11 -0000 Delivered-To: apmail-incubator-rat-commits-archive@incubator.apache.org Received: (qmail 99996 invoked by uid 500); 7 Dec 2011 07:52:11 -0000 Mailing-List: contact rat-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: rat-dev@incubator.apache.org Delivered-To: mailing list rat-commits@incubator.apache.org Received: (qmail 99989 invoked by uid 99); 7 Dec 2011 07:52:11 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 07 Dec 2011 07:52:11 +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; Wed, 07 Dec 2011 07:52:08 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 327E8238889B; Wed, 7 Dec 2011 07:51:47 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1211323 - in /incubator/rat/main/trunk/apache-rat-tasks/src/site/apt: examples/basic.apt examples/custom.apt report.apt types.apt Date: Wed, 07 Dec 2011 07:51:47 -0000 To: rat-commits@incubator.apache.org From: bodewig@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111207075147.327E8238889B@eris.apache.org> Author: bodewig Date: Wed Dec 7 07:51:46 2011 New Revision: 1211323 URL: http://svn.apache.org/viewvc?rev=1211323&view=rev Log: linefeeds Modified: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt (contents, props changed) incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt (contents, props changed) incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/report.apt (props changed) incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt (contents, props changed) Modified: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt URL: http://svn.apache.org/viewvc/incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt?rev=1211323&r1=1211322&r2=1211323&view=diff ============================================================================== --- incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt (original) +++ incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt Wed Dec 7 07:51:46 2011 @@ -1,131 +1,131 @@ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -~~ Licensed 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. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - ---- - Basic Usage Examples - ---- - -Examples - - These examples assume you have installed the RAT Antlib in a way - that provides the Report task in the XML namespace associated with - the prefix <<>>. - -* Run RAT in default configuration on all files in directory - <<>>. - ---- - - - ---- - - The report will be written to Ant's logging system. - - This corresponds to the command line - ---- -java -jar apache-rat-VERSION.jar src ---- - - except that Ant's default excludes will be applied when looking for - documents to check. - -* Run RAT on multiple directories - ---- - - - - ---- - -* Adding licence headers - - The equivalent of - -+------------------------------------------+ -java -jar apache-rat-VERSION.jar --addLicence - --copyright "Copyright 2008 Foo" - /path/to/project -+------------------------------------------+ - - is - ---- - - - ---- - -* Create a styled HTML report - ---- - - - - - - ---- - -* Run RAT on a tarball located on a webserver - ---- - - - - - - - ---- - -* Run RAT but make the Apache License Version 2.0 the only one - accepted - ---- - - - - ---- - -* Run RAT on all files in <<>> that have been modified today - ---- - - - - - - - ---- - -* Make RAT only detect your custom license and mark this license - approved. - ---- - - - - - - - ---- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~ Licensed 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. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ---- + Basic Usage Examples + ---- + +Examples + + These examples assume you have installed the RAT Antlib in a way + that provides the Report task in the XML namespace associated with + the prefix <<>>. + +* Run RAT in default configuration on all files in directory + <<>>. + +--- + + + +--- + + The report will be written to Ant's logging system. + + This corresponds to the command line + +--- +java -jar apache-rat-VERSION.jar src +--- + + except that Ant's default excludes will be applied when looking for + documents to check. + +* Run RAT on multiple directories + +--- + + + + +--- + +* Adding licence headers + + The equivalent of + ++------------------------------------------+ +java -jar apache-rat-VERSION.jar --addLicence + --copyright "Copyright 2008 Foo" + /path/to/project ++------------------------------------------+ + + is + +--- + + + +--- + +* Create a styled HTML report + +--- + + + + + + +--- + +* Run RAT on a tarball located on a webserver + +--- + + + + + + + +--- + +* Run RAT but make the Apache License Version 2.0 the only one + accepted + +--- + + + + +--- + +* Run RAT on all files in <<>> that have been modified today + +--- + + + + + + + +--- + +* Make RAT only detect your custom license and mark this license + approved. + +--- + + + + + + + +--- Propchange: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/basic.apt ------------------------------------------------------------------------------ svn:eol-style = native Modified: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt URL: http://svn.apache.org/viewvc/incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt?rev=1211323&r1=1211322&r2=1211323&view=diff ============================================================================== --- incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt (original) +++ incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt Wed Dec 7 07:51:46 2011 @@ -1,156 +1,156 @@ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -~~ Licensed 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. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - --- - Custom Types - --- - -Custom Types - - It is possible to provide license matchers or license families of - your own by implementing one of the RAT interfaces and providing the - implementation as an Ant type. This example will show how to use a - custom license matcher. - - To be suitable as an Ant type your class must provide a public no-arg - constructor (or no constructor at all). If you want to support - configuration of your instance via XML attributes or nested elements - your type must provide methods that follow Ant's method naming - conventions. For details see the - {{{http://ant.apache.org/manual/develop.html#writingowntask} Writing - Your Own Task}} section in Ant's manual. - - For this example let us assume you want to match a license that looks - like - ------------------------------------------------------------------- - /** - * Yet Another Software License, 1.0 - * - * Lots of text, specifying the users rights, and whatever ... - */ ------------------------------------------------------------------- - - and to make things a bit more interesting the version number shall be - configurable as an attribute on your type. - - An implementation of this matcher could look like - ------------------------------------------------------------------- -package org.example; - -import org.apache.rat.analysis.IHeaderMatcher; -import org.apache.rat.analysis.RatHeaderAnalysisException; -import org.apache.rat.api.Document; -import org.apache.rat.api.MetaData; -import org.apache.rat.api.MetaData.Datum; - -/** Just a POJO with no constructor at all */ -public class YASLMatcher implements IHeaderMatcher { - private final String MATCH = "Yet Another Software License, "; - private final String FAMILY = "YASL"; - private final String ONE = "1.0"; - private String matchWithVersion = MATCH + ONE; - private String familyWithVersion = FAMILY + ONE; - - /** becomes the version attribute */ - public void setVersion(String v) { - matchWithVersion = MATCH + v; - familyWithVersion = FAMILY + v; - } - - public void reset() { } - - /** trivial implementation that looks for a fixed string */ - public boolean match(Document subject, String line) - throws RatHeaderAnalysisException { - if (line.indexOf(matchWithVersion) >= 0) { - // this is what matchers are supposed to do when they find a - // match, even though it is not documented very well - subject.getMetaData().set(new Datum(MetaData.RAT_URL_LICENSE_FAMILY_CATEGORY, - familyWithVersion)); - return true; - } - return false; - } -} ------------------------------------------------------------------- - - Actually it would be easier to use RAT's - <<>> implementation or the built-in - {{{../types.html#substringMatcher}<<>>}}, but this - is just an example. - - In order to use your matcher it has to be defined as an Ant type. - You do so by either using - {{{http://ant.apache.org/manual/Tasks/typedef.html} <<>>}} or - {{{http://ant.apache.org/manual/Tasks/componentdef.html} - <<>>}}. If you are using Ant 1.8.x you should use - <<>>. - - In the most simple case this means - ------------------------------------------------------------------- - ------------------------------------------------------------------- - - Since you will be using classes from RAT's core in both the Report - task and your implementation you must ensure they get loaded via the - same classloader. If you are using the <<<-lib>>> command line - switchRAT's core will be part of Ant's core classloader and you don't - need to reference it in the <<>> for <<>> at all. - - If you define the RAT Antlib via a <<>> task with a nested - <<>> then you just use the same <<>> when - defining your custom matcher as well and set <<>> to the - same name. I.e. - -------- - - - - ... other dependencies ... - - - - - -------- - - With a definition like this you can use your matcher as in - ------- - - - - ------ - - to detect Version 1.0 or - ------- - - - - ------ - - for 2.0. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~ Licensed 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. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + --- + Custom Types + --- + +Custom Types + + It is possible to provide license matchers or license families of + your own by implementing one of the RAT interfaces and providing the + implementation as an Ant type. This example will show how to use a + custom license matcher. + + To be suitable as an Ant type your class must provide a public no-arg + constructor (or no constructor at all). If you want to support + configuration of your instance via XML attributes or nested elements + your type must provide methods that follow Ant's method naming + conventions. For details see the + {{{http://ant.apache.org/manual/develop.html#writingowntask} Writing + Your Own Task}} section in Ant's manual. + + For this example let us assume you want to match a license that looks + like + +------------------------------------------------------------------ + /** + * Yet Another Software License, 1.0 + * + * Lots of text, specifying the users rights, and whatever ... + */ +------------------------------------------------------------------ + + and to make things a bit more interesting the version number shall be + configurable as an attribute on your type. + + An implementation of this matcher could look like + +------------------------------------------------------------------ +package org.example; + +import org.apache.rat.analysis.IHeaderMatcher; +import org.apache.rat.analysis.RatHeaderAnalysisException; +import org.apache.rat.api.Document; +import org.apache.rat.api.MetaData; +import org.apache.rat.api.MetaData.Datum; + +/** Just a POJO with no constructor at all */ +public class YASLMatcher implements IHeaderMatcher { + private final String MATCH = "Yet Another Software License, "; + private final String FAMILY = "YASL"; + private final String ONE = "1.0"; + private String matchWithVersion = MATCH + ONE; + private String familyWithVersion = FAMILY + ONE; + + /** becomes the version attribute */ + public void setVersion(String v) { + matchWithVersion = MATCH + v; + familyWithVersion = FAMILY + v; + } + + public void reset() { } + + /** trivial implementation that looks for a fixed string */ + public boolean match(Document subject, String line) + throws RatHeaderAnalysisException { + if (line.indexOf(matchWithVersion) >= 0) { + // this is what matchers are supposed to do when they find a + // match, even though it is not documented very well + subject.getMetaData().set(new Datum(MetaData.RAT_URL_LICENSE_FAMILY_CATEGORY, + familyWithVersion)); + return true; + } + return false; + } +} +------------------------------------------------------------------ + + Actually it would be easier to use RAT's + <<>> implementation or the built-in + {{{../types.html#substringMatcher}<<>>}}, but this + is just an example. + + In order to use your matcher it has to be defined as an Ant type. + You do so by either using + {{{http://ant.apache.org/manual/Tasks/typedef.html} <<>>}} or + {{{http://ant.apache.org/manual/Tasks/componentdef.html} + <<>>}}. If you are using Ant 1.8.x you should use + <<>>. + + In the most simple case this means + +------------------------------------------------------------------ + +------------------------------------------------------------------ + + Since you will be using classes from RAT's core in both the Report + task and your implementation you must ensure they get loaded via the + same classloader. If you are using the <<<-lib>>> command line + switchRAT's core will be part of Ant's core classloader and you don't + need to reference it in the <<>> for <<>> at all. + + If you define the RAT Antlib via a <<>> task with a nested + <<>> then you just use the same <<>> when + defining your custom matcher as well and set <<>> to the + same name. I.e. + +------- + + + + ... other dependencies ... + + + + + +------- + + With a definition like this you can use your matcher as in + +------ + + + + +----- + + to detect Version 1.0 or + +------ + + + + +----- + + for 2.0. Propchange: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/examples/custom.apt ------------------------------------------------------------------------------ svn:eol-style = native Propchange: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/report.apt ------------------------------------------------------------------------------ svn:eol-style = native Modified: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt URL: http://svn.apache.org/viewvc/incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt?rev=1211323&r1=1211322&r2=1211323&view=diff ============================================================================== --- incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt (original) +++ incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt Wed Dec 7 07:51:46 2011 @@ -1,187 +1,187 @@ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -~~ Licensed 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. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - ----- - Built-In Types - ----- - -Built-In Types - - The RAT Antlib defines a few Ant types that can be used as nested - elements to the {{{./report.html} Report Task}} as license matchers or - license families. - - In order to stay compatible with Ant 1.7.1 these types are defined - via {{{http://ant.apache.org/manual/Tasks/typedef.html} - <<>>}} rather than - {{{http://ant.apache.org/manual/Tasks/componentdef.html} - <<>>}} which means they can be defined outside of the - Report task as well - but they will be completely useless there. - -{License Matchers} - - The following types correspond to the built-in license matchers of RAT: - -*-------*---------+-------------+ -| Typename | Detected License | Corresponding class | -*-------*---------+-------------+ -| asl20 | Apache License 2.0 | <<>> -*-------*---------+-------------+ -| dojo | {{{http://dojotoolkit.org/community/licensing.shtml}License of the Dojo Toolkit}} | <<>> -| | | -*-------*---------+-------------+ -| generated | Generated documents that don't need a license | <<>> -*-------*---------+-------------+ -| gpl1 | {{{http://www.gnu.org/licenses/old-licenses/gpl-1.0.html}GNU General Public License, version 1}} | <<>> -| | | -*-------*---------+-------------+ -| gpl2 | {{{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}GNU General Public License, version 2}} | <<>> -| | | -*-------*---------+-------------+ -| gpl3 | {{{http://www.gnu.org/licenses/gpl.html}GNU General Public License, version 3}} | <<>> -| | | -*-------*---------+-------------+ -| javadoc | Javadocs that don't need a license | <<>> -*-------*---------+-------------+ -| oasis | OASIS copyright claim plus derivative work clause | <<>> -| | | -*-------*---------+-------------+ -| w3c | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> -*-------*---------+-------------+ -| w3c-doc | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> -*-------*---------+-------------+ - - While these types may technically provide attributes or nested - elements you should use them as sole tags. - -* {<<>>} - - - - For the simple case where a license can be detected by searching for - a given string - in fact this is what all built-in implementations do - - you can use the <<>> type. - -** Attributes of the Type - -*-------------------------*-------------------------------+ -|Name |Description | -*-------------------------*-------------------------------+ -| licenseFamilyCategory | Short name of the detected license. Should be five characters long if you want to keep the layout of the plain text report. -| | This will be printed next to to the checked file inside the plain text report and creates <<>> elements inside the XML report. -| | <> -*-------------------------*-------------------------------+ -| licenseFamilyName | Long name of the detected license. The value is checked against the list of approved licenses. -| | This will not appear inside the plain text report and creates <<>> elements inside the XML report. -| | <> -*-------------------------*-------------------------------+ -| notes | Additional notes you want to provide. -| | This will not appear inside the plain text report and creates <<>> elements inside the XML report. -*-------------------------*-------------------------------+ - -** Nested Elements Supported by the Type - - The substring(s) to look for are specified as nested <<>> - elements with a substring attribute. You can specifiy multiple - <<>> elements and the <<>> will claim the - license matches if at least one substring can be found. - - At least one pattern is required. - -** Example - - Taking the example of {{{./examples/custom.html}the custom types page}} - in order to detect - ------------------------------------------------------------------- - /** - * Yet Another Software License, 1.0 - * - * Lots of text, specifying the users rights, and whatever ... - */ ------------------------------------------------------------------- - - you could use - ------------------------------------------------------------------- - - - - - - ------------------------------------------------------------------- - -{License Families} - - The following types correspond to the built-in license families of RAT: - -*-------*---------+-------------+ -| Typename | License Family | Corresponding class | -*-------*---------+-------------+ -*-------*---------+-------------+ -| academic-free-21 | Academic Free License 2.1 | <<>> -| | | -*-------*---------+-------------+ -| apache20-license | Apache License 2.0 | <<>> -*-------*---------+-------------+ -| gpl1-family | GNU General Public License, version 1 | <<>> -| | | -*-------*---------+-------------+ -| gpl2-family | GNU General Public License, version 2 | <<>> -| | | -*-------*---------+-------------+ -| gpl3-family | GNU General Public License, version 3 | <<>> -| | | -*-------*---------+-------------+ -| modified-bsd | Modified BSD License | <<>> -| | | -*-------*---------+-------------+ -| oasis-license | OASIS copyright claim plus derivative work clause | <<>> -| | | -*-------*---------+-------------+ -| w3c-doc-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> -*-------*---------+-------------+ -| w3c-soft-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> -*-------*---------+-------------+ - - While these types may technically provide attributes or nested - elements you should use them as sole tags. - -* {<<>>} - - - - This wrapper type makes it easy to specify a license name for new - approved licenses. The type has a single attribute <<>> - that must match the license family name returned by the license - matcher to make a license approved. - -** Example - - To make the YASL license of the {{substringMatcher}} Example approved - you'd use - ------------------------------------------------------------------- - - - - - - - ------------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~ Licensed 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. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + ----- + Built-In Types + ----- + +Built-In Types + + The RAT Antlib defines a few Ant types that can be used as nested + elements to the {{{./report.html} Report Task}} as license matchers or + license families. + + In order to stay compatible with Ant 1.7.1 these types are defined + via {{{http://ant.apache.org/manual/Tasks/typedef.html} + <<>>}} rather than + {{{http://ant.apache.org/manual/Tasks/componentdef.html} + <<>>}} which means they can be defined outside of the + Report task as well - but they will be completely useless there. + +{License Matchers} + + The following types correspond to the built-in license matchers of RAT: + +*-------*---------+-------------+ +| Typename | Detected License | Corresponding class | +*-------*---------+-------------+ +| asl20 | Apache License 2.0 | <<>> +*-------*---------+-------------+ +| dojo | {{{http://dojotoolkit.org/community/licensing.shtml}License of the Dojo Toolkit}} | <<>> +| | | +*-------*---------+-------------+ +| generated | Generated documents that don't need a license | <<>> +*-------*---------+-------------+ +| gpl1 | {{{http://www.gnu.org/licenses/old-licenses/gpl-1.0.html}GNU General Public License, version 1}} | <<>> +| | | +*-------*---------+-------------+ +| gpl2 | {{{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}GNU General Public License, version 2}} | <<>> +| | | +*-------*---------+-------------+ +| gpl3 | {{{http://www.gnu.org/licenses/gpl.html}GNU General Public License, version 3}} | <<>> +| | | +*-------*---------+-------------+ +| javadoc | Javadocs that don't need a license | <<>> +*-------*---------+-------------+ +| oasis | OASIS copyright claim plus derivative work clause | <<>> +| | | +*-------*---------+-------------+ +| w3c | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> +*-------*---------+-------------+ +| w3c-doc | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> +*-------*---------+-------------+ + + While these types may technically provide attributes or nested + elements you should use them as sole tags. + +* {<<>>} + + + + For the simple case where a license can be detected by searching for + a given string - in fact this is what all built-in implementations do + - you can use the <<>> type. + +** Attributes of the Type + +*-------------------------*-------------------------------+ +|Name |Description | +*-------------------------*-------------------------------+ +| licenseFamilyCategory | Short name of the detected license. Should be five characters long if you want to keep the layout of the plain text report. +| | This will be printed next to to the checked file inside the plain text report and creates <<>> elements inside the XML report. +| | <> +*-------------------------*-------------------------------+ +| licenseFamilyName | Long name of the detected license. The value is checked against the list of approved licenses. +| | This will not appear inside the plain text report and creates <<>> elements inside the XML report. +| | <> +*-------------------------*-------------------------------+ +| notes | Additional notes you want to provide. +| | This will not appear inside the plain text report and creates <<>> elements inside the XML report. +*-------------------------*-------------------------------+ + +** Nested Elements Supported by the Type + + The substring(s) to look for are specified as nested <<>> + elements with a substring attribute. You can specifiy multiple + <<>> elements and the <<>> will claim the + license matches if at least one substring can be found. + + At least one pattern is required. + +** Example + + Taking the example of {{{./examples/custom.html}the custom types page}} + in order to detect + +------------------------------------------------------------------ + /** + * Yet Another Software License, 1.0 + * + * Lots of text, specifying the users rights, and whatever ... + */ +------------------------------------------------------------------ + + you could use + +------------------------------------------------------------------ + + + + + + +------------------------------------------------------------------ + +{License Families} + + The following types correspond to the built-in license families of RAT: + +*-------*---------+-------------+ +| Typename | License Family | Corresponding class | +*-------*---------+-------------+ +*-------*---------+-------------+ +| academic-free-21 | Academic Free License 2.1 | <<>> +| | | +*-------*---------+-------------+ +| apache20-license | Apache License 2.0 | <<>> +*-------*---------+-------------+ +| gpl1-family | GNU General Public License, version 1 | <<>> +| | | +*-------*---------+-------------+ +| gpl2-family | GNU General Public License, version 2 | <<>> +| | | +*-------*---------+-------------+ +| gpl3-family | GNU General Public License, version 3 | <<>> +| | | +*-------*---------+-------------+ +| modified-bsd | Modified BSD License | <<>> +| | | +*-------*---------+-------------+ +| oasis-license | OASIS copyright claim plus derivative work clause | <<>> +| | | +*-------*---------+-------------+ +| w3c-doc-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> +*-------*---------+-------------+ +| w3c-soft-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> +*-------*---------+-------------+ + + While these types may technically provide attributes or nested + elements you should use them as sole tags. + +* {<<>>} + + + + This wrapper type makes it easy to specify a license name for new + approved licenses. The type has a single attribute <<>> + that must match the license family name returned by the license + matcher to make a license approved. + +** Example + + To make the YASL license of the {{substringMatcher}} Example approved + you'd use + +------------------------------------------------------------------ + + + + + + + +------------------------------------------------------------------ Propchange: incubator/rat/main/trunk/apache-rat-tasks/src/site/apt/types.apt ------------------------------------------------------------------------------ svn:eol-style = native