You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2026/09/22 11:34:09 UTC
(maven-doap-plugin) 01/01: Rewrite site documentation in Simplified Technical English
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch ste100-site-markdown
in repository https://gitbox.apache.org/repos/asf/maven-doap-plugin.git
commit ff452beaca1efcbd59fbbef0042c0201536de40d
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Tue Sep 22 11:33:59 2026 +0000
Rewrite site documentation in Simplified Technical English
---
src/site/markdown/examples/doap-in-use.md | 18 ++++++++-----
src/site/markdown/examples/with-site-plugin.md.vm | 16 ++++++------
src/site/markdown/faq.md | 31 +++++++----------------
src/site/markdown/index.md | 26 ++++++++++++++-----
src/site/markdown/usage.md.vm | 4 +--
5 files changed, 49 insertions(+), 46 deletions(-)
diff --git a/src/site/markdown/examples/doap-in-use.md b/src/site/markdown/examples/doap-in-use.md
index aa1af94..06fcf20 100644
--- a/src/site/markdown/examples/doap-in-use.md
+++ b/src/site/markdown/examples/doap-in-use.md
@@ -26,23 +26,27 @@ under the License.
# Generated DOAP In Use
-DOAP is used to share informations (metadata) about a software project. Now that you have a generated DOAP from POM by the DOAP Plugin, you need to publish it and diffuse it.
+People use DOAP to share information (metadata) about a software project.
+
+After the DOAP Plugin generates a DOAP file from a POM, publish the file. Distribute the DOAP file to other people.
## How To Publish A DOAP File
-You need to publish it somewhere where the DOAP file will be accessible via an HTTP or HTTPS request like a web server or SVN.
+Publish the DOAP file on a web server or on SVN. Make sure that other people can get the file with an HTTP or HTTPS request.
+
+By default, the DOAP Plugin generates the file in the reporting output directory (that is ${project.reporting.outputDirectory}). The file is available when you deploy the Maven site with the [`site:deploy`](http://maven.apache.org/plugins/maven-site-plugin/usage.html) goal.
-By default, the DOAP Plugin generates the file in the reporting output directory (i.e. ${project.reporting.outputDirectory}). So, it will be available when you will deploy the Maven site via the [`site:deploy`](http://maven.apache.org/plugins/maven-site-plugin/usage.html) goal. See [Integrated DOAP Plugin With The Site Plugin](./with-site-plugin.html) part for more information.
+For more information, read the [Integrated DOAP Plugin With The Site Plugin](./with-site-plugin.html) page.
-## How To Diffuse A DOAP File
+## How To Distribute A DOAP File
-Several Semantic Web directories like [http://doapspace.org/](http://doapspace.org/) or [http://doapstore.org](http://doapstore.org) provide metadatas relating to open source projects into a public catalog. You need to enter the DOAP file URL to their catalogs.
+Several Semantic Web directories, like [http://doapspace.org/](http://doapspace.org/) and [http://doapstore.org](http://doapstore.org), list metadata about open source projects in a public catalog.
-You could also use the [Ping the Semantic Web](http://pingthesemanticweb.com/) which share RDF data with the World.
+Enter the URL of the DOAP file into their catalogs. Use [Ping the Semantic Web](http://pingthesemanticweb.com/) to share RDF data with the web.
# Examples for the Maven DOAP
-Our Maven DOAP file is share on SVN [here](http://svn.apache.org/repos/asf/maven/maven-3/trunk/doap_Maven.rdf). Here are the result from some Semantic Web directories:
+The Maven project shares its DOAP file in this [SVN repository](http://svn.apache.org/repos/asf/maven/maven-3/trunk/doap_Maven.rdf). Some Semantic Web directories show this file:
- [Doapstore](http://doapstore.org/view.php?uri=http%3A%2F%2FMaven.rdf.apache.org%2F)
- [Zigtgist RDF Viewer](http://dataviewer.zitgist.com/?uri=http%3A//svn.apache.org/repos/asf/maven/maven-3/trunk/doap_Maven.rdf)
diff --git a/src/site/markdown/examples/with-site-plugin.md.vm b/src/site/markdown/examples/with-site-plugin.md.vm
index 4598bee..ed39f37 100644
--- a/src/site/markdown/examples/with-site-plugin.md.vm
+++ b/src/site/markdown/examples/with-site-plugin.md.vm
@@ -26,14 +26,14 @@ under the License.
# Integrated DOAP Plugin With The Site Plugin
-As described in [DOAP In Use](./doap-in-use.html), you need to publish the generated DOAP file.
+You must publish the generated DOAP file, as described in [DOAP In Use](./doap-in-use.html).
-By default, the generated DOAP file will be deploy using the [`site:deploy`](http://maven.apache.org/plugins/maven-site-plugin/usage.html) goal in the site specified in the _distributionManagement_ section of the POM.
+By default, the [`site:deploy`](http://maven.apache.org/plugins/maven-site-plugin/usage.html) goal deploys the generated DOAP file to the site that the _distributionManagement_ section of the POM specifies.
-Including DOAP In The Site Phase
+Include DOAP In The Site Phase
--------------------------------
-You could always generate the DOAP file for your project by sticking the DOAP Plugin in the `site` phase, like the following:
+To generate the DOAP file for your project in the `site` phase, add the DOAP Plugin with this configuration:
```xml
<project>
@@ -60,10 +60,10 @@ You could always generate the DOAP file for your project by sticking the DOAP Pl
</project>
```
-Defining Meta Tag
+Define A Meta Tag
-----------------
-To make the DOAP file available for all HTML files deployed on the site, you could modify the `src/site/site.xml` to specify a <link/> tag, i.e.:
+To make the DOAP file available for all HTML files in the site, modify `src/site/site.xml` to specify a <link/> tag:
```xml
<project>
@@ -76,10 +76,10 @@ To make the DOAP file available for all HTML files deployed on the site, you cou
</project>
```
-Generating DOAP from Another Maven Project
+Generate DOAP From Another Maven Project
------------------------------------------
-Since 1.1, you could generate the DOAP file against another Maven Project. It could be useful, if you have a main project and a site project.
+Since 1.1, you can generate the DOAP file for another Maven project. This can help when you have a main project and a site project.
```xml
<project>
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index e3ac04b..eb0c019 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -27,49 +27,36 @@ under the License.
1. [What is DOAP?](#What_is_DOAP)
2. [What are the benefits of DOAP?](#What_are_the_benefits_of_DOAP)
-3. [Why would I use DOAP when I have a POM?](#Why_would_I_use_DOAP_when_I_have_a_POM)
+3. [Why do I use DOAP when I have a POM?](#Why_would_I_use_DOAP_when_I_have_a_POM)
4. [What to do with the generated DOAP file?](#What_to_do_with_the_generated_DOAP_file)
-5. [Why are not all developers/contributors listed in the DOAP file as maintainer?](#Why_are_not_all_developers.2Fcontributors_listed_in_the_DOAP_file_as_maintainer)
+5. [Why are not all developers and contributors listed as maintainers in the DOAP file?](#Why_are_not_all_developers.2Fcontributors_listed_in_the_DOAP_file_as_maintainer)
<a id="What_is_DOAP"></a>
### What is DOAP?
-DOAP stands for "Description of a Project" and you can find out everything there is to
-know about DOAP in its [spec repository](https://github.com/ewilderj/doap).
+DOAP stands for "Description of a Project". The [spec repository](https://github.com/ewilderj/doap) has all the information about DOAP.
<a id="What_are_the_benefits_of_DOAP"></a>
### What are the benefits of DOAP?
-The [Semantic Web](http://en.wikipedia.org/wiki/Semantic_web) provides
-mechanisms to process data provided in a form that is easily processed by machines. Thus,
-a DOAP is a machine readable document which facilitates projects research: it becomes much
-easier to seek information in the mass of data of the Web, since the data have a given
-foreseeable format.
+The [Semantic Web](http://en.wikipedia.org/wiki/Semantic_web) provides methods to process data in a machine-readable form. A DOAP file is a machine-readable document that helps project research. The data in a DOAP file has a predictable format. This format makes it easy to find project information in the large amount of data on the Web.
<a id="Why_would_I_use_DOAP_when_I_have_a_POM"></a>
-### Why would I use DOAP when I have a POM?
+### Why do I use DOAP when I have a POM?
-That's a very good question! The answer is that generating a DOAP file should take no
-effort if you are using Maven DOAP Plugin and it helps disseminate project information
-which can only be a good thing. Cataloging tools like [SWiK](http://swik.net/)
-or like [DoapStore](http://doapstore.org/) can benefit from you generating DOAP
-files and that can also only be a good thing. Even so, it is still important to spread as
-much information about projects around as possible so there is no downside to creating
-DOAP files.
+A DOAP file takes little effort to generate with the Maven DOAP Plugin. The DOAP file spreads project information to other systems. Cataloging tools like [SWiK](http://swik.net/) and [DoapStore](http://doapstore.org/) use DOAP files. A project must publish its information in many places.
<a id="What_to_do_with_the_generated_DOAP_file"></a>
### What to do with the generated DOAP file?
-Maven DOAP plugin has generated a DOAP file, what's next? See
-[DOAP in Use](./examples/doap-in-use.html) part.
+After the Maven DOAP Plugin generates a DOAP file, read the [DOAP in Use](./examples/doap-in-use.html) page.
<a id="Why_are_not_all_developers.2Fcontributors_listed_in_the_DOAP_file_as_maintainer"></a>
-### Why are not all developers/contributors listed in the DOAP file as maintainer?
+### Why are not all developers and contributors listed as maintainers in the DOAP file?
-Developers/contributors having a role containing "*emeritus*" are no longer active in the
-project and can't be maintainers therefore.
+Developers and contributors with a role that contains "*emeritus*" are no longer active in the project. They cannot be maintainers.
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 7bbf653..458e204 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -25,11 +25,11 @@ under the License.
-->
# Apache Maven DOAP Plugin
-The DOAP Plugin is used to generate a compliant [Description of a Project (DOAP)](https://github.com/ewilderj/doap) file from a POM. The main goal is to be able to provide DOAP files for Semantic Web systems that use them as primary input but that would also alleviate the burden of maintaining two sets of metadata.
+The DOAP Plugin generates a compliant [Description of a Project (DOAP)](https://github.com/ewilderj/doap) file from a POM. The main goal is to provide DOAP files for Semantic Web systems. These systems use DOAP files as their primary input. This also removes the need to maintain two sets of metadata.
-Version 1.0 of this plugin is specifically tailored for use by projects at [Apache](http://projects.apache.org/doap.html), but this will change in subsequent versions as more people become interested in DOAP.
+Version 1.0 of this plugin is designed for projects at [Apache](http://projects.apache.org/doap.html). This will change in later versions of the plugin, as more people become interested in DOAP.
-If you are not aware about RDF or Semantic Web concepts, refer you to the [Links part](./links.html) to getting started.
+If you do not know about RDF or Semantic Web concepts, read the [Links](./links.html) page.
## Goals Overview
@@ -38,15 +38,27 @@ The DOAP Plugin has one goal:
- [doap:generate](./generate-mojo.html) Generates a DOAP file from the POM.
## Usage
-General instructions on how to use the DOAP Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. Last but not least, users occasionally contribute additional examples, tips or errata to the [plugin's wiki page](http://docs.codehaus.org/display/MAVENUSER/DOAP+Plugin).
+The [usage page](./usage.html) has general instructions for the DOAP Plugin. The examples below describe specific ways to use the DOAP Plugin. Users sometimes contribute content to the [wiki page](http://docs.codehaus.org/display/MAVENUSER/DOAP+Plugin):
-In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
+- Examples
+- Tips
+- Errata
-If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are wel [...]
+If you have questions about the usage of this plugin, read the [FAQ](./faq.html). Contact the [user mailing list](./mailing-lists.html) for more help.
+
+The [mail archive](./mailing-lists.html) can contain answers to your questions in older threads of the mailing list.
+
+If the plugin misses a feature, enter a feature request in the [issue tracker](./issue-management.html). If the plugin has a defect, enter a bug report in the [issue tracker](./issue-management.html). When you create a new issue, give a full description of your concern. Attach this information to the issue:
+
+- Complete debug logs
+- POMs
+- Small demo projects
+
+The developers must be able to reproduce your problem. A small demo project is the most useful attachment. Patches are welcome. Contributors can get the project from the [source repository](./scm.html). The [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html) has more information for contributors.
## Examples
-To provide you with better understanding of some usages of the DOAP Plugin, you can take a look at the following examples:
+See these examples of the usage of the DOAP Plugin:
- [Generated DOAP in use](./examples/doap-in-use.html)
- [Integrate DOAP Plugin in the Site Plugin](./examples/with-site-plugin.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 3890dd4..9f1c85d 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -186,7 +186,7 @@ This is the minimal POM to be ASF compliant.
</project>
```
-**Note**: See the [DoapOptions Javadoc](./apidocs/org/apache/maven/plugin/doap/options/DoapOptions.html) and the [ASFExtOptions Javadoc](./apidocs/org/apache/maven/plugin/doap/options/ASFExtOptions.html) for advanced options.
+**Note**: See the [DoapOptions Javadoc](./apidocs/org/apache/maven/plugin/doap/options/DoapOptions.html) for advanced DOAP options. See the [ASFExtOptions Javadoc](./apidocs/org/apache/maven/plugin/doap/options/ASFExtOptions.html) for advanced ASFext options.
Advanced DOAP Configuration
---------------------------
@@ -260,7 +260,7 @@ Advanced DOAP Configuration
Generate DOAP File
------------------
-To generate the DOAP file you would use the following command:
+Use this command to generate the DOAP file:
```shell
mvn doap:generate