------
 Usage
 ------
 Jason van Zyl
 Vincent Siveton
 ------
 2011-01-11
 ------

~~ 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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Usage

 The DOAP Plugin generates DOAP and ASF DOAP compliant files. The following examples describe the basic usage of
 the Plugin.

* {Pure DOAP Configuration}

+-----+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-doap-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <doapOptions>
            <!-- Default values -->
            <bugDatabase>\${project.issueManagement.url}</bugDatabase>
            <category>library</category>
            <created>\${project.inceptionYear}-01-01</created>
            <description>\${project.description}</description>
            <downloadPage>\${project.distributionManagement.downloadUrl}</downloadPage>
            <homepage>\${project.url}</homepage>
            <license>\$\{project.licenses[0].url}</license>
            <mailingList>\${project.url}/mail-lists.html</mailingList>
            <name>\${project.name}</name>
            <programmingLanguage>Java</programmingLanguage>
            <scmAnonymousConnection>\${project.scm.connection}</scmAnonymousConnection>
            <scmDeveloperConnection>\${project.scm.developerConnection}</scmDeveloperConnection>
            <shortdesc>\${project.description}</shortdesc>
            <vendor>\${project.organization.name}</vendor>
            ...
          </doapOptions>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+-----+

  <<Note>>: See the {{{./apidocs/org/apache/maven/plugin/doap/options/DoapOptions.html}DoapOptions Javadoc}} for
  advanced DOAP options.

* {DOAP ASF Configuration}

  This is the minimal POM to be ASF compliant.

+-----+
<project>
  <!-- To retrieve the ASF organization and the ASF license -->
  <parent>
    <groupId>org.apache</groupId>
    <artifactId>apache</artifactId>
    <version>8</version>
  </parent>

  <groupId>org.apache.XXX</groupId>
  <artifactId>XXX</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>

  <name>Apache XXX Project</name>
  <description>Apache XXX is ...</description>
  <url>http://XXX.apache.org</url>
  <inceptionYear>2010</inceptionYear>

  <scm>
    <connection>scm:svn:http://svn.apache.org/repos/asf/XXX/trunk</connection>
    <developerConnection>scm:svn:https://svn.apache.org/repos/asf/XXX/trunk</developerConnection>
    <url>http://svn.apache.org/viewvc/XXX/trunk</url>
  </scm>
  <issueManagement>
    <system>jira</system>
    <url>http://issues.apache.org/jira/browse/XXX</url>
  </issueManagement>
  <distributionManagement>
    <downloadUrl>http://XXX.apache.org/download.html</downloadUrl>
  </distributionManagement>

  <developers>
    <!-- PMC Chair -->
    <developer>
      <id>XXX</id>
      <name>XXX</name>
      <email>XXX@apache.org</email>
      <organization>ASF</organization>
      <roles>
        <!-- For <asfext:chair/>, will be detected -->
        <role>PMC Chair</role>
      </roles>
    </developer>
    <!-- PMC -->
    <developer>
      <id>XXX</id>
      <name>XXX</name>
      <email>XXX@apache.org</email>
      <organization>ASF</organization>
      <roles>
        <role>PMC Member</role>
      </roles>
    </developer>
  </developers>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-doap-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <doapOptions>
            <!-- See http://projects.apache.org/languages.html -->
            <programmingLanguage>Java</programmingLanguage>
            <!-- http://projects.apache.org/categories.html -->
            <category>build-management</category>

            <!-- Default values -->
            <bugDatabase>\${project.issueManagement.url}</bugDatabase>
            <created>\${project.inceptionYear}-01-01</created>
            <description>\${project.description}</description>
            <downloadPage>\${project.distributionManagement.downloadUrl}</downloadPage>
            <homepage>\${project.url}</homepage>
            <license>\$\{project.licenses[0].url}</license>
            <mailingList>\${project.url}/mail-lists.html</mailingList>
            <name>\${project.name}</name>
            <scmAnonymousConnection>\${project.scm.connection}</scmAnonymousConnection>
            <scmDeveloperConnection>\${project.scm.developerConnection}</scmDeveloperConnection>
            <shortdesc>\${project.description}</shortdesc>
            <vendor>\${project.organization.name}</vendor>
            ...
          </doapOptions>

          <asfExtOptions>
            <charter>The mission of the Apache XXX project is to create and maintain software
            libraries that provide ...</charter>
            ...
            <!-- Default values -->
            <pmc>\${project.url}</pmc>
            <name>\${project.name}</name>

            <!-- If this Apache project implements a standard -->
            <standards>
              <standard>
                <title>Extensible Stylesheet Language - Formatting Objects (XSL-FO 1.1)</title>
                <body>W3C</body>
                <id>XSL 1.1</id>
                <url>http://www.w3.org/TR/xsl11/</url>
              </standard>
            </standards>
          </asfExtOptions>

        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
+-----+

  <<Note>>: See the {{{./apidocs/org/apache/maven/plugin/doap/options/DoapOptions.html}DoapOptions Javadoc}} and
  the {{{./apidocs/org/apache/maven/plugin/doap/options/ASFExtOptions.html}ASFExtOptions Javadoc}} for advanced options.

* Advanced DOAP Configuration

+-----+
<project>
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-doap-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <!-- generate DOAP file for a given artifact -->
          <artifact>
            <groupId>given-artifact-groupId</groupId>
            <artifactId>given-artifact-artifactId</artifactId>
            <version>given-artifact-version</version>
          </artifact>

          <!-- To not validate the generate DOAP file -->
          <validate>false</validate>

          <doapOptions>
            <!-- To add a custom DOAP xmlns prefix -->
            <xmlnsPrefix>doap</xmlnsPrefix>
            <!-- Default DOAP xmlns namespace URI -->
            <xmlnsNamespaceURI>http://usefulinc.com/ns/doap#</xmlnsNamespaceURI>

            <!-- Some extra DOAP vocabulary -->
            <extra>
              <!-- For example, i.e. actually unsupported by DOAP schema -->
              <ciManagement>http://ci.foo.org</ciManagement>
            </extra>
          </doapOptions>

          <asfExtOptions>
            <!-- Default ASFext xmlns prefix -->
            <xmlnsPrefix>asfext</xmlnsPrefix>
            <!-- Default ASFext xmlns namespace URI -->
            <xmlnsNamespaceURI>http://projects.apache.org/ns/asfext#</xmlnsNamespaceURI>

            <!-- Some extra ASFExt vocabulary -->
            <extra>
              <!-- Actually unsupported by ASFext -->
              <status>active</status>
            </extra>
          </asfExtOptions>

          <!-- More extensions -->
          <extOptions>
            <!-- ASF labs extension, http://labs.apache.org/doapizer.html -->
            <extOption>
              <xmlnsPrefix>labs</xmlnsPrefix>
              <xmlnsNamespaceURI>http://labs.apache.org/doap-ext/1.0#</xmlnsNamespaceURI>
              <extensions>
                <status>active</status>
              </extensions>
            </extOption>
          </extOptions>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
</project>
+-----+

* Generate DOAP File

 To generate the DOAP file you would use the following command:

+-----
mvn doap:generate
+-----

* Further Links

 * Parameters for the {{{./generate-mojo.html}doap:generate}} goal

 * {{{http://usefulinc.com/ns/doap#}http://usefulinc.com/ns/doap#}}

 * {{{http://projects.apache.org/docs/pmc.html}http://projects.apache.org/docs/pmc.html}}

 * {{{http://projects.apache.org/docs/standards.html}http://projects.apache.org/docs/standards.html}}

 * {{{http://www.w3.org/RDF/Validator/}W3C RDF Validation Service}}

 []