whiteboard/plugins/org.apache.forrest.plugin.input.doap/src/documentation/content/xdocs/index.xml - forrest - Git at Google

 <?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 document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
   <header>
     <title>Welcome to the org.apache.forrest.plugin.input.doap Plugin</title>
   </header>
   <body>
     <section id="overview">
       <title>Apache Forrest - org.apache.forrest.plugin.input.doap Plugin</title>
       <p>
         Renders DOAP files in a human readable form, provides various indexes of
         DOAP collections and allows the extraction of contact details from a set
         of DOAP files.
       </p>
     </section>
     <section>
       <title>Project Details</title>
       <p>
         Project details are generated from a project descriptor file. This file
         can be in any of the following formats:
       </p>
       <ul>
         <li>DOAP</li>
         <li>DOAP over ATOM</li>
       </ul>
       <note>
         We need your help in adding more formats.
       </note>
       <p>
         The location of this descriptor file is specified in the locationmap
         with the hint <code>doap.descriptor</code>. This defaults to a file
         called doap.xml in the root of your project's content directory. To place
         your descriptor in a different location simply add a matcher like that
         shown below in your project locationmap file.
       </p>
       <source>
 <![CDATA[
     <match pattern="doap.descriptor.projectDetails">
       <location src="[path/to/descriptor/file]" />
     </match>
       ]]>
       </source>
       <p>
         To retrieve the project DOAP file in its raw form request the file
         <code>/projectDetails/source.xml</code>.
       </p>
       <p>
         To retrieve the project details page request the file
         <code>/projectDetails.[FORMAT]</code>.
       </p>
       <section>
         <title>Multiple Projects</title>
         <p>
           You can use the doap plugin to pull together project
           information for multiple projects. For example, take a look at the
           project details for <a href="projectDetails/forrest.html">Apache
           Forrest</a>.
         </p>
         <p>
           Using the locationmap you can retrieve this content from anywhere you
           want, for example, the DOAP file for the Forrest project comes from
           directly from SVN, thus we are always assured of it being up to date.
         </p>
         <p>
           To retrieve the project details of another project make a request for
           <code>projectDetails/[PROJECT_NAME].html</code>. For
           this to work your project locationmap must have an entry like this:
         </p>
         <source>
 <![CDATA[
     <match pattern="doap.descriptor.forrest">
       <location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/doap.xml"/>
     </match>
         ]]>
         </source>
         <warning>
           FOR-910 "project DOAP file retrieved numerous times during docs
           generation" so use a local copy instead.
         </warning>
         <p>
           Of course, if you have a central location for all your project
           descriptor files you could use a match like this:
         </p>
         <source>
 <![CDATA[
     <match pattern="doap.descriptor.*">
       <location src="path_to_descriptors/{1}.xml"/>
     </match>
         ]]>
         </source>
         <warning>
           The indexing of projects (described below) does not currently work
           with wildcard matchers in the locationmap.
         </warning>
       </section>
       <section>
         <title>Project Indexes</title>
         <p>
           The system will automatically create an index of projects from your
           projects locationmap file. For example, the "Projects" section of the
           navigation on the left is automatically generated.
         </p>
         <note>
           There is considerable repetition in the indexes in this demo. The
           intention is to show the range of indexes that can be created. You
           should select the most suitable for your individual project.
         </note>
         <warning>
           The indexes to be included in your site navigation only work correctly
           when generating a static site. You should only use page based indexes
           for dynamic sites.
         </warning>
       </section>
       <section>
         <title>Contact Lists</title>
         <p>You can extract a comma separated list of contact details contained
         in the collection of DOAP files by requesting
         <a href="projectDetails/contacts.csv">projectDetails/contacts.csv</a>.</p>
       </section>
       <section>
         <title>Categories</title>
         <warning>This functionality is alpha quality and may change in the near future.
         In fact this was written by someone (me) who knows very little of RDF and currently
         has no network access or texts to inform this implementation. It is very likely there
         is a much better way to do this in the RDF world, I've tried, as much as possible,
         to make it possible to refactor this code when I'm more informed about how to do
         this. Use at your own risk, or better still, tell us how to improve it.</warning>

         <p>Projects can be assigned to one or more categories using the <code>doap:category</code>
         element. We recommend the use of an <code>rdf:resource</code> attribute to
         identify the category the project applies to. But what value should be given
         to the <code>rdf:resource</code> attribute?</p>

         <p>At present we are using the categories defined by the Apache Software
         Foundation. In the future we are likely to use the JISC standards catalogue
         as well.</p>

         <fixme author="rdg">Add links to previous para</fixme>

         <p>When rendering the category this plugin will attempt to resolve a proper name
         for the category. First, it will look in the <code>categoriesDefinitions.xml</code>
         file contained within this plugin. If no match is found in there it will look for
         a <code>dc:title</code> attribute in the doap file itself. If no such attribute is
         found it will use the value of <code>rdf:resource</code> attribute.</p>
       </section>
     </section>
     <section>
         <title>Dispatcher</title>
         <p>
           The DOAP plugin provides dispatcher templates for working with DOAP
           files. For usage instructions see the docs for the
           <a href="/ls.contracts.org.apache.forrest.plugin.input.doap.html">doap
           templates</a>.
         </p>
     </section>
     <section id="samples">
       <title>Samples</title>
       <p>
         This section includes links to a number of samples using this plugin.
         The plugin is intended to be self documenting through these samples. If
         you require further help please ask on the user mailing list.
       </p>

       <section>
         <title>Project Details</title>

         <ul>
           <li><a href="projectDetails/projectDetails.source.xml">Source XML file</a></li>
           <li><a href="projectDetails/projectDetails.rdf">Source RDF file (if the source file is an RDF/XML file this will be the same as the previous example - currently only RDF/XML is supported)</a></li>
           <li><a href="projectDetails/projectDetails.html">Descriptor page for this plugin</a></li>
           <li><a href="projectDetails/forrest.html">Descriptor page for Forrest</a></li>
           <li><a href="projectDetails/index/byLang.html">Index by language</a></li>
           <li><a href="projectDetails/index/byLang/Java.html">Index by specific language (Java)</a></li>
           <li><a href="projectDetails/index/byCategory.html">Index by category</a></li>
           <li><a href="projectDetails/allProjects.json">JSON file for all projects</a></li>
         </ul>
       </section>

       <section>
         <title>Maintainer Details</title>
         <ul>
           <li><a href="projectDetails/allMaintainers.rdf">All maintainers</a> for all projects in FOAF format</li>
           <li><a href="projectDetails/contacts.csv">Comma separated list of project contacts who have a recorded email address</a></li>
         </ul>
       </section>

       <section>
         <title>In Development Features</title>

           <ul>
             <li><a href="exhibitTest.html">Browse the catalogue using Exhibit from MIT</a></li>
             <li>Record relationships between projects. This is a simple relatedTo property
             and is not intended to replace detailed build information.
             <warning>This feature currently uses a "relatedTo" proeprty that has been
             placed in the asfext namespace. Hwoever, at the time of writing this addition
             to the asfext namespace has not been approved.</warning></li>
           </ul>
       </section>

       <note>
         The more samples included here the easier it is for users to understand
         this plugin. If you can provide additional samples please do so.
       </note>
     </section>
   </body>
 </document>
	<?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 document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
	<document>
	<header>
	<title>Welcome to the org.apache.forrest.plugin.input.doap Plugin</title>
	</header>
	<body>
	<section id="overview">
	<title>Apache Forrest - org.apache.forrest.plugin.input.doap Plugin</title>
	<p>
	Renders DOAP files in a human readable form, provides various indexes of
	DOAP collections and allows the extraction of contact details from a set
	of DOAP files.
	</p>
	</section>
	<section>
	<title>Project Details</title>
	<p>
	Project details are generated from a project descriptor file. This file
	can be in any of the following formats:
	</p>
	<ul>
	<li>DOAP</li>
	<li>DOAP over ATOM</li>
	</ul>
	<note>
	We need your help in adding more formats.
	</note>
	<p>
	The location of this descriptor file is specified in the locationmap
	with the hint <code>doap.descriptor</code>. This defaults to a file
	called doap.xml in the root of your project's content directory. To place
	your descriptor in a different location simply add a matcher like that
	shown below in your project locationmap file.
	</p>
	<source>
	<![CDATA[
	<match pattern="doap.descriptor.projectDetails">
	<location src="[path/to/descriptor/file]" />
	</match>
	]]>
	</source>
	<p>
	To retrieve the project DOAP file in its raw form request the file
	<code>/projectDetails/source.xml</code>.
	</p>
	<p>
	To retrieve the project details page request the file
	<code>/projectDetails.[FORMAT]</code>.
	</p>
	<section>
	<title>Multiple Projects</title>
	<p>
	You can use the doap plugin to pull together project
	information for multiple projects. For example, take a look at the
	project details for <a href="projectDetails/forrest.html">Apache
	Forrest</a>.
	</p>
	<p>
	Using the locationmap you can retrieve this content from anywhere you
	want, for example, the DOAP file for the Forrest project comes from
	directly from SVN, thus we are always assured of it being up to date.
	</p>
	<p>
	To retrieve the project details of another project make a request for
	<code>projectDetails/[PROJECT_NAME].html</code>. For
	this to work your project locationmap must have an entry like this:
	</p>
	<source>
	<![CDATA[
	<match pattern="doap.descriptor.forrest">
	<location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/doap.xml"/>
	</match>
	]]>
	</source>
	<warning>
	FOR-910 "project DOAP file retrieved numerous times during docs
	generation" so use a local copy instead.
	</warning>
	<p>
	Of course, if you have a central location for all your project
	descriptor files you could use a match like this:
	</p>
	<source>
	<![CDATA[
	<match pattern="doap.descriptor.*">
	<location src="path_to_descriptors/{1}.xml"/>
	</match>
	]]>
	</source>
	<warning>
	The indexing of projects (described below) does not currently work
	with wildcard matchers in the locationmap.
	</warning>
	</section>
	<section>
	<title>Project Indexes</title>
	<p>
	The system will automatically create an index of projects from your
	projects locationmap file. For example, the "Projects" section of the
	navigation on the left is automatically generated.
	</p>
	<note>
	There is considerable repetition in the indexes in this demo. The
	intention is to show the range of indexes that can be created. You
	should select the most suitable for your individual project.
	</note>
	<warning>
	The indexes to be included in your site navigation only work correctly
	when generating a static site. You should only use page based indexes
	for dynamic sites.
	</warning>
	</section>
	<section>
	<title>Contact Lists</title>
	<p>You can extract a comma separated list of contact details contained
	in the collection of DOAP files by requesting
	<a href="projectDetails/contacts.csv">projectDetails/contacts.csv</a>.</p>
	</section>
	<section>
	<title>Categories</title>
	<warning>This functionality is alpha quality and may change in the near future.
	In fact this was written by someone (me) who knows very little of RDF and currently
	has no network access or texts to inform this implementation. It is very likely there
	is a much better way to do this in the RDF world, I've tried, as much as possible,
	to make it possible to refactor this code when I'm more informed about how to do
	this. Use at your own risk, or better still, tell us how to improve it.</warning>

	<p>Projects can be assigned to one or more categories using the <code>doap:category</code>
	element. We recommend the use of an <code>rdf:resource</code> attribute to
	identify the category the project applies to. But what value should be given
	to the <code>rdf:resource</code> attribute?</p>

	<p>At present we are using the categories defined by the Apache Software
	Foundation. In the future we are likely to use the JISC standards catalogue
	as well.</p>

	<fixme author="rdg">Add links to previous para</fixme>

	<p>When rendering the category this plugin will attempt to resolve a proper name
	for the category. First, it will look in the <code>categoriesDefinitions.xml</code>
	file contained within this plugin. If no match is found in there it will look for
	a <code>dc:title</code> attribute in the doap file itself. If no such attribute is
	found it will use the value of <code>rdf:resource</code> attribute.</p>
	</section>
	</section>
	<section>
	<title>Dispatcher</title>
	<p>
	The DOAP plugin provides dispatcher templates for working with DOAP
	files. For usage instructions see the docs for the
	<a href="/ls.contracts.org.apache.forrest.plugin.input.doap.html">doap
	templates</a>.
	</p>
	</section>
	<section id="samples">
	<title>Samples</title>
	<p>
	This section includes links to a number of samples using this plugin.
	The plugin is intended to be self documenting through these samples. If
	you require further help please ask on the user mailing list.
	</p>

	<section>
	<title>Project Details</title>

	<ul>
	<li><a href="projectDetails/projectDetails.source.xml">Source XML file</a></li>
	<li><a href="projectDetails/projectDetails.rdf">Source RDF file (if the source file is an RDF/XML file this will be the same as the previous example - currently only RDF/XML is supported)</a></li>
	<li><a href="projectDetails/projectDetails.html">Descriptor page for this plugin</a></li>
	<li><a href="projectDetails/forrest.html">Descriptor page for Forrest</a></li>
	<li><a href="projectDetails/index/byLang.html">Index by language</a></li>
	<li><a href="projectDetails/index/byLang/Java.html">Index by specific language (Java)</a></li>
	<li><a href="projectDetails/index/byCategory.html">Index by category</a></li>
	<li><a href="projectDetails/allProjects.json">JSON file for all projects</a></li>
	</ul>
	</section>

	<section>
	<title>Maintainer Details</title>
	<ul>
	<li><a href="projectDetails/allMaintainers.rdf">All maintainers</a> for all projects in FOAF format</li>
	<li><a href="projectDetails/contacts.csv">Comma separated list of project contacts who have a recorded email address</a></li>
	</ul>
	</section>

	<section>
	<title>In Development Features</title>

	<ul>
	<li><a href="exhibitTest.html">Browse the catalogue using Exhibit from MIT</a></li>
	<li>Record relationships between projects. This is a simple relatedTo property
	and is not intended to replace detailed build information.
	<warning>This feature currently uses a "relatedTo" proeprty that has been
	placed in the asfext namespace. Hwoever, at the time of writing this addition
	to the asfext namespace has not been approved.</warning></li>
	</ul>
	</section>

	<note>
	The more samples included here the easier it is for users to understand
	this plugin. If you can provide additional samples please do so.
	</note>
	</section>
	</body>
	</document>