Author: tchemit Date: 2010-04-16 12:47:43 +0200 (Fri, 16 Apr 2010) New Revision: 1754 Log: use apt doc (avoid cyclic when wants to release jrst and maven-license-plugin) Added: trunk/src/site/apt/ trunk/src/site/apt/descriptor.apt trunk/src/site/apt/header.apt trunk/src/site/apt/index.apt trunk/src/site/apt/usage.apt Added: trunk/src/site/apt/descriptor.apt =================================================================== --- trunk/src/site/apt/descriptor.apt (rev 0) +++ trunk/src/site/apt/descriptor.apt 2010-04-16 10:47:43 UTC (rev 1754) @@ -0,0 +1,74 @@ +~~~ +~~ #%L +~~ Maven License Plugin +~~ +~~ $Id$ +~~ $HeadURL$ +~~ %% +~~ Copyright (C) 2008 - 2010 CodeLutin +~~ %% +~~ This program is free software: you can redistribute it and/or modify +~~ it under the terms of the GNU Lesser General Public License as +~~ published by the Free Software Foundation, either version 3 of the +~~ License, or (at your option) any later version. +~~ +~~ This program is distributed in the hope that it will be useful, +~~ but WITHOUT ANY WARRANTY; without even the implied warranty of +~~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +~~ GNU General Lesser Public License for more details. +~~ +~~ You should have received a copy of the GNU General Lesser Public +~~ License along with this program. If not, see +~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. +~~ #L% +~~~ +---- +License project descriptor +---- + +Abstract + + + This document describes the license project descriptor file introduced in + version 2.1. + + The license file descriptor file aims to enumerate all files to include in + license process per type and license. + + This new format is used in goal + {{{./update-file-header-mojo.html}update-file-header}} and + {{{./update-project-license-mojo.html}update-project-license}}. + + TODO-TC-20100409 Do this documentation + +xsd + + This file is ruled by a {{{./licenseProjectDescriptor-1.0.0.xsd}xsd file}}_. + +Example + + The next example applies a gpl v3 license on all java files in **src/main/java**. + +------------------------------------------------------------------------------- + + <?xml version='1.0' encoding='UTF-8'?> + <project xmlns="http://maven-site.nuiton.org/maven-license-plugin/1.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven-site.nuiton.org/maven-license-plugin/1.0.0 http://maven-site.nuiton.org/maven-license-plugin/licenseProjectDescriptor-1.0.0.xsd"> + <mainLicense>gpl_v3</mainLicense> + <headers> + <header> + <licenseName>lgpl_v3</licenseName> + <commentStyle>java</commentStyle> + <fileSets> + <fileSet> + <basedir>all/src</basedir> + <includes> + <include>**/*.java</include> + </includes> + </fileSet> + </fileSets> + </header> + </headers> + </project> +------------------------------------------------------------------------------- \ No newline at end of file Property changes on: trunk/src/site/apt/descriptor.apt ___________________________________________________________________ Added: svn:keywords + "Author Date Id Revision HeadURL Added: trunk/src/site/apt/header.apt =================================================================== --- trunk/src/site/apt/header.apt (rev 0) +++ trunk/src/site/apt/header.apt 2010-04-16 10:47:43 UTC (rev 1754) @@ -0,0 +1,146 @@ +~~~ +~~ #%L +~~ Maven License Plugin +~~ +~~ $Id$ +~~ $HeadURL$ +~~ %% +~~ Copyright (C) 2008 - 2010 CodeLutin +~~ %% +~~ This program is free software: you can redistribute it and/or modify +~~ it under the terms of the GNU Lesser General Public License as +~~ published by the Free Software Foundation, either version 3 of the +~~ License, or (at your option) any later version. +~~ +~~ This program is distributed in the hope that it will be useful, +~~ but WITHOUT ANY WARRANTY; without even the implied warranty of +~~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +~~ GNU General Lesser Public License for more details. +~~ +~~ You should have received a copy of the GNU General Lesser Public +~~ License along with this program. If not, see +~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. +~~ #L% +~~~ +---- +File Header +---- + +Abstract + + This document describes the file header model introduced in version 2.1. + + You will learn how to customize it and use it with the goal + {{{./update-file-header-mojo.html}update-file-header}}. + +Header model + +* Example + + Here is an example of a file header (with NO comment box) : + +-------------------------------------------------------------------------------- + + (1) # % L + (2) Project description + (3) %% + (4) Copyright (C) 2010 your organization + (5) %% + (6) License content + (7) # L % +-------------------------------------------------------------------------------- + + * (1) the start process tag used to detect begin of header (NEVER suppress it). + * (2) Project description section + * (3) Header section delimiter + * (4) Copyright section of the file (see next section for detail) + * (5) Header section delimiter + * (6) License section + * (7) the end process tag used to detect end of header (NEVER suppress it). + +* Configuration + + You can configure those things : + + * start process tag + * header section delimiter + * end process tag + +* Copyright model + + Copyright section must exactly be of this form : + +-------------------------------------------------------------------------------- + + Copyright (C) firstYear[ - lastYear] holder +-------------------------------------------------------------------------------- + + If *firstYear* and *lastYear* are the same then lastYear is omitted. + +* Comment box + + In a file, we must box the file header in a comment. In the descriptor file + you can customize it by choosing a headerType. + +Available comment styles + + Here is the available comment styles. + + Using the goal{{{./comment-style-list-mojo.html}comment-style-list}} + you can find all of them. + +* java style + +-------------------------------------------------------------------------------- + + /* + * HEADER + */ +-------------------------------------------------------------------------------- + +* xml style + +-------------------------------------------------------------------------------- + + <!-- + HEADER + --> +-------------------------------------------------------------------------------- + +* properties style + +-------------------------------------------------------------------------------- + + ###### + # HEADER + ###### +-------------------------------------------------------------------------------- + +* apt style + +-------------------------------------------------------------------------------- + + ~~~~~~ + ~~ HEADER + ~~~~~~ +-------------------------------------------------------------------------------- + +* rst style + +-------------------------------------------------------------------------------- + .. - + .. * HEADER + .. - +-------------------------------------------------------------------------------- + +Ignore a header + + If you don't want `update-file-header` goal to treate a specific file, you can + use a specific tag in your class : + +-------------------------------------------------------------------------------- + + %%License-Ignore +-------------------------------------------------------------------------------- + + You can change it with **ignoreTag** property. \ No newline at end of file Property changes on: trunk/src/site/apt/header.apt ___________________________________________________________________ Added: svn:keywords + "Author Date Id Revision HeadURL Added: trunk/src/site/apt/index.apt =================================================================== --- trunk/src/site/apt/index.apt (rev 0) +++ trunk/src/site/apt/index.apt 2010-04-16 10:47:43 UTC (rev 1754) @@ -0,0 +1,104 @@ +~~~ +~~ #%L +~~ Maven License Plugin +~~ +~~ $Id$ +~~ $HeadURL$ +~~ %% +~~ Copyright (C) 2008 - 2010 CodeLutin +~~ %% +~~ This program is free software: you can redistribute it and/or modify +~~ it under the terms of the GNU Lesser General Public License as +~~ published by the Free Software Foundation, either version 3 of the +~~ License, or (at your option) any later version. +~~ +~~ This program is distributed in the hope that it will be useful, +~~ but WITHOUT ANY WARRANTY; without even the implied warranty of +~~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +~~ GNU General Lesser Public License for more details. +~~ +~~ You should have received a copy of the GNU General Lesser Public +~~ License along with this program. If not, see +~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. +~~ #L% +~~~ +---- +Introduction +---- + +Maven license Plugin + + The Maven License Plugin is used to deal with license stuff on a maven project. + +* NOTE + The process tags are separated by space otherwise plugin can NOT update header of this file! + + +License header + + The license header is a comment added on the top of sources files. + + To detect the header on files we use processor technology, with tags + +------------------------------------------------------------------------------- + + # % L Content # L % +------------------------------------------------------------------------------- + + The header is composed of two parts : + + * the first part gives some common informations for all files of a maven + module (such as project name, organisation, ...). + * the second part resumes the license used. + + Here a example : + +------------------------------------------------------------------------------- + + /* + * # % L + * Plugin maven de changement de license + * %% + * Copyright (C) 2008 - 2009 CodeLutin + * %% + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Lesser Public License for more details. + * + * You should have received a copy of the GNU General Lesser Public + * License along with this program. If not, see + * <http://www.gnu.org/licenses/lgpl-3.0.html>. + * # L % + */ +------------------------------------------------------------------------------- + +* Goals Overview + + The plugin has the following goals: + + * {{{./update-project-license-mojo.html}update-project-license}} adds or updates license project file (since 2.1). + + * {{{./update-file-header-mojo.html}update-file-header}} adds or updates license header on some files (since 2.1). + + * {{{./add-third-party-mojo.html}add-third-party}} creates the THIRD-PARTY.txt in the build. + + * {{{./comment-style-list-mojo.html}comment-style-list}} display list of available comment style header (since 2.1). + + * {{{./license-list-mojo.html}license-list}} display list of available licenses. + + * {{{./help-mojo.html}help}} display help about the plugin (goals, usage). + +* Usage + + Instructions on how to use the Plugin can be found on {{{./usage.html}usage}} page + +* Examples + + to be done. + Property changes on: trunk/src/site/apt/index.apt ___________________________________________________________________ Added: svn:keywords + "Author Date Id Revision HeadURL Added: trunk/src/site/apt/usage.apt =================================================================== --- trunk/src/site/apt/usage.apt (rev 0) +++ trunk/src/site/apt/usage.apt 2010-04-16 10:47:43 UTC (rev 1754) @@ -0,0 +1,144 @@ +~~~ +~~ #%L +~~ Maven License Plugin +~~ +~~ $Id$ +~~ $HeadURL$ +~~ %% +~~ Copyright (C) 2008 - 2010 CodeLutin +~~ %% +~~ This program is free software: you can redistribute it and/or modify +~~ it under the terms of the GNU Lesser General Public License as +~~ published by the Free Software Foundation, either version 3 of the +~~ License, or (at your option) any later version. +~~ +~~ This program is distributed in the hope that it will be useful, +~~ but WITHOUT ANY WARRANTY; without even the implied warranty of +~~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +~~ GNU General Lesser Public License for more details. +~~ +~~ You should have received a copy of the GNU General Lesser Public +~~ License along with this program. If not, see +~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. +~~ #L% +~~~ +---- +Usage +---- + +Actions + +* update-project-license goal + + This goal creates or updates the LICENSE.txt file and add it in build. + + It can also generate a bundle License file to avoid name collision in a final + application. + + for full detail see {{{./update-project-license-mojo.html}detail page}}. + +* update-file-header goal + + This goal adds or updates the license header on some files using a xml + descriptor file to describe all files to include in license process for a + whole module. + + for full detail see {{{./update-file-header-mojo.html}detail page}}. + +* add-third-party goal + + This goal build the THIRD-PARTY.txt file and add it in build. + + for full detail see {{{./add-third-party-mojo.html}detail page}}. + +Get informations + +* license-list goal + + This goal display of available licenses. + + Use it directly (and only) from commandline : + +------------------------------------------------------------------------------- + + mvn license:license-list +------------------------------------------------------------------------------- + + To display the license header, use the <<detail>> parameter : + +------------------------------------------------------------------------------- + mvn license:license-list -Ddetail +------------------------------------------------------------------------------- + + for full detail see {{{./license-list-mojo.html}detail page}}. + +** Example of execution + +------------------------------------------------------------------------------- + [INFO] [license:license-list {execution: default-cli}] + [INFO] Available licenses : + + * agpl_v3 : GNU Affero General Public License (AGPL) version 3.0 + * apache_v2 : Apache License version 2.0 + * cddl_v1 : COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0 + * fdl_v1_3 : GNU Free Documentation License (FDL) version 1.3 + * gpl_v1 : GNU General Public License (GPL) version 1.0 + * gpl_v2 : GNU General Public License (GPL) version 2.0 + * gpl_v3 : GNU General Public License (GPL) version 3.0 + * lgpl_v2_1 : GNU General Lesser Public License (LGPL) version 2.1 + * lgpl_v3 : GNU General Lesser Public License (LGPL) version 3.0 + * mit : MIT-License +------------------------------------------------------------------------------- + +* comment-style-list goal + + This goal display of available comment style to box file header. + + Use it directly (and only) from commandline : + +------------------------------------------------------------------------------- + + mvn license:comment-style-list +------------------------------------------------------------------------------- + + To display the example, use the <<detail>> parameter : + +------------------------------------------------------------------------------- + + mvn license:comment-style-list -Ddetail +------------------------------------------------------------------------------- + + for full detail see {{{./comment-style-list-mojo.html}detail page}}. + +** Example of execution + +------------------------------------------------------------------------------- + [INFO] [license:comment-style-list {execution: default-cli}] + [INFO] List of available comment styles: + + - apt : header transformer with apt comment style + - java : header transformer with java comment style + - properties : header transformer with properties file comment style + - rst : header transformer with rst comment style + - xml : header transformer with xml comment style +------------------------------------------------------------------------------- + +* help goal + + This goal display the help of the plugin (available goals). + + Use it directly (and only) from commandline : + +------------------------------------------------------------------------------- + + mvn license:help +------------------------------------------------------------------------------- + + To display verbose help : + +------------------------------------------------------------------------------- + + mvn license:help -Ddetail +------------------------------------------------------------------------------- + + for full detail see {{{./help-mojo.html}detail page}}. Property changes on: trunk/src/site/apt/usage.apt ___________________________________________________________________ Added: svn:keywords + "Author Date Id Revision HeadURL