You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2010/05/12 16:46:36 UTC
svn commit: r943523 [1/2] - in /uima/site/trunk/uima-website: docs/
docs/board-reports/ xdocs/
Author: schor
Date: Wed May 12 14:46:36 2010
New Revision: 943523
URL: http://svn.apache.org/viewvc?rev=943523&view=rev
Log:
[UIMA-1756] updates to the website include 2 new pages not yet linked from the top: maven-design.html which describes how we use Maven for building, and dev-docbook - which is a start at describing how to write docbook style documentation so it can be built with our build tooling. Also, the svn page has been updated to say to use m2eclipse, and mentions the new top-level "build" directory in svn. Some of the instructions (e.g. building from the command line) are updated to new aggregate project names (so they apply to the branch until it's reintegrated...)
Added:
uima/site/trunk/uima-website/docs/board-reports/2010-05.txt
uima/site/trunk/uima-website/docs/dev-docbook.html
uima/site/trunk/uima-website/xdocs/dev-docbook.xml
Modified:
uima/site/trunk/uima-website/docs/distribution.html
uima/site/trunk/uima-website/docs/maven-design.html
uima/site/trunk/uima-website/docs/svn.html
uima/site/trunk/uima-website/xdocs/distribution.xml
uima/site/trunk/uima-website/xdocs/maven-design.xml
uima/site/trunk/uima-website/xdocs/svn.xml
Added: uima/site/trunk/uima-website/docs/board-reports/2010-05.txt
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/board-reports/2010-05.txt?rev=943523&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/board-reports/2010-05.txt (added)
+++ uima/site/trunk/uima-website/docs/board-reports/2010-05.txt Wed May 12 14:46:36 2010
@@ -0,0 +1,46 @@
+--------------------------------------------------------
+Attachment AK: Status report for the Apache UIMA Project
+
+Apache UIMA's mission: the creation and maintenance of open-source
+software related to the analysis of unstructured data, guided by the
+UIMA Oasis Standard.
+
+Moving to TLP
+-------------
+In the last month, we completed our move to a TLP, and are almost finished
+with the updates needed for making use of a major redesign of how we use Maven
+to do our builds and releases that uses the standard Apache Maven Parent POM
+and the Apache Nexus repository installation.
+
+The website was updated to remove "incubator" things, including some graphics.
+
+Releases
+--------
+none yet (as a TLP), we hope to do one in the next month or 2.
+
+2010-1-26 2.3.0 (Incubator - last release) release of Java SDK, Annotator
+ add-on package, UIMA-AS (Async scaleout), and UIMA-CPP
+ (C++ enablement)
+
+Development
+-----------
+Lots of work in devising a new way to use Maven that is much more aligned
+with the conventional way of doing things.
+
+We still have a significant number of issues remain in Jira, postponed from the
+last release. More progress should get made on these after our Maven re-alignment
+work is finished.
+
+Some issues regarding large scale use of UIMA-AS were reported and fixed.
+
+PR
+--
+Sally Khudairi included a bit about Apache UIMA in her PR blog, etc. this past month (Thanks!).
+
+Community
+---------
+No changes
+
+Issues
+------
+No Board level issues at this time
Added: uima/site/trunk/uima-website/docs/dev-docbook.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/dev-docbook.html?rev=943523&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/dev-docbook.html (added)
+++ uima/site/trunk/uima-website/docs/dev-docbook.html Wed May 12 14:46:36 2010
@@ -0,0 +1,319 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+ <style type="text/css">@import "stylesheets/base.css";</style>
+ <meta name="author" value="
+ UIMA Documentation Team">
+ <meta name="email" value="dev@uima.apache.org">
+
+
+
+ <title>Apache UIMA - Using Docbook for documentation</title>
+ </head>
+
+ <body>
+ <div class="topLogos">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <a href="index.html">
+ <img style="border: 1px solid black;" src="./images/UIMA_banner2tlp.png" alt="UIMA project logo" border="0"/>
+ </a>
+ </td>
+ <td align='CENTER'>
+ <div class="pageBanner">Using Docbook for documentation</div>
+ </td>
+ <td align='RIGHT'>
+ <a href="http://www.apache.org">
+ <img src="./images/asf-logo-on-white-small.png" alt="Apache UIMA" border="0"/>
+ </a>
+ </td>
+ </tr>
+ </table>
+ <hr noshade="" size="1"/>
+ </div>
+ <table border="0" width="100%" cellspacing="4">
+ <tr>
+ <td align='RIGHT' colspan="2">
+ <form method="get" action="http://www.google.com/search">
+ Search the site
+ <input type="text" name="q" size="25" maxlength="255" value="" />
+ <input type="hidden" name="sitesearch" value="http://uima.apache.org/" />
+ <input name="Search" value="Search Site" type="submit"/>
+ </form>
+ </td>
+ </tr>
+ <tr> <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top">
+
+
+
+
+
+
+ <!-- regular menu -->
+ <div class="navBar">
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">General</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./index.html">Home</a>
+ </div>
+ <div class="navBarItem"> <a href="./downloads.cgi">Downloads</a>
+ </div>
+ <div class="navBarItem"> <a href="./documentation.html">Documentation</a>
+ </div>
+ <div class="navBarItem"> <a href="./news.html">News</a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="./mail-lists.html">Mailing Lists</a>
+ </div>
+ <div class="navBarItem"> <a href="./mail-lists.html#Apache_UIMA_Forums">Forums</a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.general" target="_blank"><em> Users</em> <img src="images/offsitelink.png" /></a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.devel" target="_blank"><em>Dev</em> <img src="images/offsitelink.png" /></a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="http://issues.apache.org/jira/browse/uima" target="_blank">Issue tracker <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://cwiki.apache.org/UIMA/" target="_blank">Wiki <img src="images/offsitelink.png"</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Components & Tools</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./annotators.html">Annotators</a>
+ </div>
+ <div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a>
+ </div>
+ <div class="navBarItem"> <a href="./sandbox.html">Sandbox</a>
+ </div>
+ <div class="navBarItem"> <a href="./external-resources.html">External Resources</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Community</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./get-involved.html">Get Involved</a>
+ </div>
+ <div class="navBarItem"> <a href="./contribution-policy.html">Contribution Policies</a>
+ </div>
+ <div class="navBarItem"> <a href="./faq.html">FAQ</a>
+ </div>
+ <div class="navBarItem"> <a href="./project-guidelines.html">Project Guidelines</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Development</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./svn.html">Source Code</a>
+ </div>
+ <div class="navBarItem"> <a href="./distribution.html">Creating a Distribution</a>
+ </div>
+ <div class="navBarItem"> <a href="./release.html">Doing a UIMA release</a>
+ </div>
+ <div class="navBarItem"> <a href="./codeConventions.html">Code Conventions</a>
+ </div>
+ <div class="navBarItem"> <a href="./uima-specification.html">UIMA Specification (OASIS)</a>
+ </div>
+ <div class="navBarItem"> <a href="./team-list.html">Project Team</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./iks09.html">IKS 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./gscl09.html">GSCL 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lsm09.html">LSM 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lrec08.html">LREC 2008</a>
+ </div>
+ <div class="navBarItem"> <a href="./gldv07.html">GLDV 2007</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">ASF</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./license.html">License</a>
+ </div>
+ <div class="navBarItem"> <a href="http://apache.org/foundataion/thanks.html" target="_blank">ASF Sponsors <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/foundation/sponsorship.html" target="_blank">ASF Sponsorship <img src="images/offsitelink.png"</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="UIMA Docbook Bookshelf"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> UIMA Docbook Bookshelf</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>To facilitate cross referencing among UIMA docbooks, we ask users
+ when downloading these books to place the downloaded files in a common
+ directory, which we refer to as the UIMA bookshelf.</p>
+ <p>When this is done, the user will be able to follow cross reference
+ linkages within the downloaded books, without needing an internet
+ connection.</p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Docbook Conventions used"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Docbook Conventions used</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>The build tooling expects the following conventions to
+ be followed:</p>
+ <ul>
+ <li>Docbook source(s) should be put in the directory src/docbook/. The
+ existance of this directory is what causes the normal parent pom chain
+ to notice that docbook processing is needed during the build.</li>
+ <li>Currently, the docbooks are written to the 4.4 version of Docbook;
+ begin your files with the standard boilerplate (best to copy from another
+ docbook in the "set".</li>
+ <li>There is one designated file specified in project's POM as the property
+ "<bookNameRoot>" which must have as its value the name of the docbook
+ source file to process, minus the ".xml". This supports breaking large
+ docbooks into multiple parts, perhaps one per "chapter"; you have one
+ top-level docbook which xincludes the other parts. See the file
+ uima-docbook-overview-and-setup/src/docbook/overview-and-setup.xml for
+ an example of using this technique.
+ <p>The bookNameRoot name serves also as the book "name"
+ and must be unique among all the docbooks in the UIMA bookshelf.</p>
+ </li>
+ <li>The first part of the top docbook source must include the line:
+ <pre><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="../../target/docbook-shared/common_book_info.xml"/></pre>
+ This allows it to pick up the standard license, disclaimers, and copyright notices.
+ Please set the POM element <inceptionYear>; this is used in the copyright notice.
+ </li>
+ <li>Xinclude support is automatically provided by the docbkx toolchain; you do not have to set
+ XML entities for this at the top of your file.</li>
+ <li>Images to be included are by convention expected be located in a folder named
+ "images/[bookNameRoot]", which is located in the same parent directory as
+ the top docbook source file. The [bookNameRoot] is the name of the top docbook source
+ file, less the ".xml". The "extra" directory under "images" is used to separate
+ images from the different docbooks in the uima bookshelf.</li>
+ <li>Standard entities may be included, using the form:
+ <pre><!ENTITY imgroot
+ "images/insert-booknameroot-here/optional-sub-dir/">
+<!ENTITY % uimaents SYSTEM
+ "../../target/docbook-shared/entities.ent">
+%uimaents;</pre>
+ <p>The docbook-shared/entities... are common shared entities you can use; please
+ see the source for the list, located here:
+ <a href="http://svn.apache.org/repos/asf/uima/build/trunk/uima-docbook-resource-bundle/src/main/resources/docbook-shared/entities.ent" target="_blank">here</a>.</p></li>
+ </ul>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Cross Referencing among UIMA Docbooks"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Cross Referencing among UIMA Docbooks</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>Docbooks support an enhanced cross-referencing among
+ docbook collections, using a link style called "olink".
+ Olinks allow cross-referencing and
+ hyperlinking among documents, using extra saved information about the
+ target document (being linked to, as contrasted with plain href style
+ links, which only have the link url). For instance, in PDFs, there's
+ extra info enabling the referring doc to say "page 123 in document abc".
+ For PDF and HTML, olinks allow the referring text to include a hyperlink
+ which includes target document's element title, and maybe a number (if it
+ has numbered items - such as our chapter / section numbers in the main
+ UIMA documentation). So you can get a link that looks like this:
+ <ul><li>see Section 1.5.1, ?Annotator Methods?</li></ul>
+ where the 1.5.1 was generated by docbook processing, and the "Annotator
+ Methods" was the title of that section.</p>
+ <p>
+ To make olinks work, each time a docbook is processed, an extra database
+ of info for that docbook is created, containing just the things needed for
+ this. This database, together with some other data about how the
+ multiple interlinking docbooks are arranged, is then
+ used when processing a docbook.
+ </p>
+ <p>
+ Olink data for all UIMA docbooks is stored in one additional project,
+ uima-docbook-olink, that has an attached artifact: a zip file of all
+ olink data.
+ </p>
+ <p>
+ This project is at the level 1-SNAPSHOT, and will stay there.
+ Because it's a snapshot, it is updated whenever it is "deployed".
+ Each docbook processing run updates that docbook's olink data.
+ Committers should deploy the snapshot to share updates of olink
+ data with others.
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Creating a new Docbook"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Creating a new Docbook</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ <ul>
+ <li>Add a src/docbook directory, and put an images directory there
+ for new images (if you have images), and one or more XML files containing docbook source.</li>
+ <li>Put the name of the top docbook xml file in the project's docbookNameRoot property</li>
+ <li>Add this docbook to the UIMA bookshelf - modifying the uima-docbook-olink project's
+ src/main/docbook-olink/{html, htmlsingle, and pdf}/site.xml files.
+ <ul><li>Add a stanza to the site-map, and</li>
+ <li>add an entity for the docbookNameRoot at the top of the site file.</li>
+ </ul>
+ </li>
+ </ul>
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ </td>
+ </tr>
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <table class="pageFooter">
+ <tr>
+ <td><a href="index.html">Home</a></td>
+ <td><a href="privacy-policy.html">Privacy Policy</a></td>
+ <td>
+ Copyright © 2006-2009, The Apache Software Foundation
+ </td>
+ <td><a href="mailto:dev@uima.apache.org">Contact us</a></td>
+ </tr>
+ </table>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+
Modified: uima/site/trunk/uima-website/docs/distribution.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/distribution.html?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/distribution.html (original)
+++ uima/site/trunk/uima-website/docs/distribution.html Wed May 12 14:46:36 2010
@@ -168,7 +168,7 @@
<p>This is because specifying source and target of, say, Java 1.5, and then accidentally using a
Java 6 library method, surprisingly doesn't cause a mvn driven compile failure (if Maven is running under Java 6).</p>
<p>
- <ul>
+ <ul>
<li><a href="#Building the Apache UIMA base distribution">Building the Apache UIMA base distribution</a></li>
<li><a href="#Building the Apache UIMA-AS distribution">Building the Apache UIMA-AS distribution</a></li>
<li><a href="#Building Apache UIMA Sandbox distributions">Building Apache UIMA Sandbox distributions</a></li>
Modified: uima/site/trunk/uima-website/docs/maven-design.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/maven-design.html?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/maven-design.html (original)
+++ uima/site/trunk/uima-website/docs/maven-design.html Wed May 12 14:46:36 2010
@@ -182,13 +182,11 @@
things and arranges POMs in a parent-child hierarchy, by having the child
identify the parent POM. The other kind is aggregation - POMs which specify sub-modules
for purposes of building multi-module things, and releasing them all at once. For clarity,
-we keep these two uses in separate POMs: parent POMs do not do aggregation,
+we mostly keep these two uses in separate POMs: parent POMs do not do aggregation,
and aggregation POMs do not do common factoring.</p>
<p>Our parent poms are kept in a folder, under a top level SCM node called "build", which holds things
needed for building, but which are not part of normal aggregate distributions.
Aggregation POMs are kept with the SCM node focused on those modules being aggregated.</p>
- <p class="note">A recent change in Maven 3 now requires that POMs whose parent poms are not in the
- parent directory, have an empty <relativePath/> element.</p>
</blockquote>
</p>
</td></tr>
@@ -205,22 +203,27 @@ and aggregation POMs do not do common fa
<ul>
<li>POMs contain a <url> element. If they don't, they will inherit from their parent
following an assumption that the url is the parent url value followed by "/" and
- this POMs artifactId. This may or may not be how our website is set up, so
- it is best to just code the url that is correct for the new project.</li>
+ this POMs artifactId. If this does not correspond to how the website is set up,
+ please specify the url that is correct for the new project.
+ In the Maven spirit of convention over configuration,
+ web pages for specific projects (such as the
+ individual annotators) will be set up this way, so the <url> element can be
+ omitted.</li>
<li>The SCM connection is needed for releasing - and needs to be accurate for this
component.</li>
<li>The POM's "version" is stated literally, not via a "property", etc. Maven 3
will complain if you use properties here, and the release mechanism for maven
manipulates these values (removing SNAPSHOT, incrementing things, etc.)</li>
- <li>The POM's groupId is usually omitted - in which case, it inherits from the
- parent. Doing this is a recommended best practice.</li>
+ <li>The POM's groupId is omitted if it is the same as the parent pom's; it inherits from the
+ parent.</li>
+ <li>The packaging is omitted if it is "jar".</li>
</ul>
</p>
<p>Maven 3 has more requirements on POMs
<p>A transition to Maven 3 is occuring in 2010. The Eclipse plugin, m2eclipse, "embeds"
Maven 3 already.</p>
<ul>
- <li>Property names have to include their path from project, etc. For instance, you cannot use
+ <li>Build variable names have to include their path from project, etc. For instance, you cannot use
${version}, you have to use ${project.version}.</li>
</ul></p>
</blockquote>
@@ -241,16 +244,18 @@ and aggregation POMs do not do common fa
<li>Docbook</li>
<li>UIMA Website (Anakia)</li>
</ul>
- <p>For each Java source artifact, the Apache standard parent POM builds and attaches
- a <ul><li>source zip, and a</li><li>Javadocs zip</li></ul>
- to the main Jar artifact. It doesn't do any standard actions for other documentation (e.g., docbook style).</p>
<p>We use Docbook style for much of our other documentation,
the main exception being our website, which uses Anakia.
See <a href="dev-docbook.html">the development docbook page</a> for details.</p>
- <p>Normally, all website content is kept in SVN in the uima/site/trunk/uima-website/docs directory; this directory is
+ <p>For each Java source artifact, when the apache-release profile is specified (usually during the
+ release process), the Apache standard parent POM builds and attaches
+ a <ul><li>source zip, and a</li><li>Javadocs zip</li></ul>
+ to the main Jar artifact. It doesn't do any standard actions for other documentation (e.g., docbook style).
+ Docbooks are built during the normal lifecycle.</p>
+ <p>Normally, all website-ready content is kept in SVN in the uima/site/trunk/uima-website/docs directory; this directory is
checked out into the right spot on people.apache.org. For large generated documents,
- we have the option to generate them from sources in svn, and deploy them directly to the right spot on people.apache.org. This avoids
- using SVN for large generated files. This satisfies the
+ we have the option to generate them from sources in svn, and deploy them directly to the right spot on people.apache.org.
+ This avoids using SVN for large generated files. This satisfies the
<a href="http://apache.org/dev/project-site.html" target="_blank">requirements</a>
for Apache websites.</p>
</blockquote>
@@ -260,6 +265,98 @@ and aggregation POMs do not do common fa
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
+ <a name="Packaging Individual Projects"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Packaging Individual Projects</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ The UIMA Project, in addition to the main frameworks, has Annotators and other components and tools
+ (such as the SimpleServer) that it releases. These in the past have been released as a big
+ assembly we called the Sandbox, but now are are being supported as individual items.
+ </p>
+ <p>
+ There are two kinds of packaging for these supported, by using one of the following parent-poms:
+ <ul><li>parent-pom-annotator - this packages things as a PEAR</li>
+ <li>parent-pom-single-project - this packages things as a tar / zip file having a lib/ directory
+ with the generated Jar and dependencies, plus other files (see below).</li></ul>
+ </p>
+ <p>
+ The individual Annotators are mostly packaged as a
+ <a href="http://uima.apache.org/downloads/releaseDocs/2.3.0-incubating/docs/html/references/references.html#ugr.ref.pear">
+ PEAR</a> file, which is the UIMA standard for annotator component packaging and distribution.
+ The Pear is generated using the PearPackagingMavenPlugin, which generates automatically a
+ conventional Pear Installation Descriptor, from the information in the project.
+ The PEAR artifact is generated in addition to Jar of the code, and includes
+ other items such as the generated documentation, data, and a lib/ directory with other Jars
+ needed for the PEAR to operate. This PEAR is the packaged equivalent of a binary distribution
+ artifact produced for the main framework, and comes with a license and notice that
+ covers any included libraries. Generated PEARs are included in the artifacts that are managed by
+ Maven, and are available in the Maven repository system.
+ </p>
+ <p class="note">
+ The PEAR internal folder "src" is not used by components here; the source is instead available
+ via the standard Maven source packaging.
+ </p>
+ <p>
+ Projects indicate they want PEAR packaging by making the parent pom be parent-pom-annotator.
+ </p>
+ <p>
+ PEARs must have a "main" descriptor, which is the one normally used to configure and run
+ the annotator. When using the parent-pom-annotator to indicate PEAR packaging, you must include a property called
+ <pearMainDescriptor> in the Annotator's POM, whose value is the path from the project base directory
+ identifying the main descriptor. For example, if the folder "desc" was at the root of your project, the
+ value might be something like "desc/my-main-descriptor.xml".
+ </p>
+ <p>If an annotator isn't suitable for PEAR packaging, perhaps because it is inappropriate to have
+ one pre-done main descriptor, then the annotator can be packaged as a single-project, instead, by
+ making the POM's parent parent-pom-single-project.</p>
+ <h2>Conventions for structuring individually releaseable projects</h2>
+ <p>Use these conventions to get your annotator properly packaged when you use the parent-pom-annotator or
+ the parent-pom-single-project as your parent pom:
+ <ul>
+ <li>Use <package>jar</package> (which is the default, so it should be omitted), if there
+ is a Jar that should be built (as is usually the case). This will cause the main
+ annotator Jar to be built, including any resources (plus the top-level desc folder, if it exists), as normal.</li>
+ <li>Create the required License, Notice, and optional Readme, and Release Notes files
+ in the project directory at the top level; these will be included in the
+ PEAR or simple project binary assembly at the top level.
+ The License and Notice files should be for the entire project, including
+ all third-party Jars etc. being distributed.
+ <p style="margin-left: 2em">The generated Jar, which only has Apache-developed code, includes
+ the normal Apache License and Notice files.</p></li>
+ <li>Dependencies: those marked with scope "compile" (the default) or "runtime"
+ are copied to the PEAR or single-project's lib/ directory. To keep a dependency needed for compiling
+ from being included in the lib/, give it a scope of "provided".</li>
+ <li>Using the following folders at the top level of your project (which is the "conventional" PEAR layout,
+ will cause the contents of these folders to be added to the corresponding files in the PEAR or binary zip/tar:
+ <ul>
+ <li>desc - for descriptiors, including the main descriptor</li>
+ <li>bin - (optional) for extra executables</li>
+ <li>lib - (optional) for libraries (not being included via the Maven dependencies mechanism)</li>
+ <li>doc - (optional) not normally used, but can have additional user-ready documentation</li>
+ <li>data - (optional) for arbitrary data</li>
+ <li>resources - (optional) not normally used, but can have additional data which should be on the classpath</li>
+ <li>conf - (optional) for extra configuration files</li>
+ <li>src - not-used</li>
+ </ul>
+ <p>The following Maven conventional information will be added to the above:
+ <ul>
+ <li>lib - dependencies with scope "compile" or "runtime" are resolved from maven repositories and added to the lib/</li>
+ <li>doc - docbook sources under src/docbook are processed and the html and pdf forms are added</li>
+ <li>Maven resources - (not the top level resources directory described above)
+ are by convention included in the Jar, and are not included in this folder</li>
+ </ul>
+ </p>
+ </li>
+ </ul>
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
<a name="Building Assemblies for Distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Assemblies for Distribution</h1></a>
</td></tr>
<tr><td>
@@ -268,11 +365,19 @@ and aggregation POMs do not do common fa
when built produces maven artifacts in repositories (your local repository, or perhaps uploaded
to a snapshot or staging repository).</p>
<p>When releases are done, additional artifacts are constructed using the distribution assemblies.
- </p>
+ We have these for
+ <ul>
+ <li>UIMA - the base Java framework</li>
+ <li>UIMA-AS - the asynchronous scaleout add-on</li>
+ <li>UIMA Add-ons - not decided yet, but it's likely we'll just release these as individual projects.
+ So there is no add-ons-distr project (yet).</li>
+ <!--li>UIMA Add-ons - annotators and other add-on components such as the SimpleServer</li-->
+ <li>UIMACPP - the C++ framework</li>
+ </ul>
+ </p>
<h2>Distribution Pom - Clean phase</h2>
- <p>The clean phase
- of the distribution POMs includes running the dependency:purge-local-repository plugin
- to purge the local repository of dependencies.
+ <p>The clean phase of the distribution POMs includes running the dependency:purge-local-repository plugin
+ to purge the local repository of dependencies, when activated by the apache-release profiles.
</p>
</blockquote>
</p>
@@ -281,24 +386,54 @@ and aggregation POMs do not do common fa
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
+ <a name="Build resources"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Build resources</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>During the build process, several resources are used, and are built into Maven Artifact Jars with
+ Maven coordinates:
+ <ul>
+ <li>uima-jar-resource-bundle - this is the standard License Notice and Dependencies from the
+ Apache common parent pom, except it allows adding post-Notice text. We use this when
+ we need to include the IBM Copyright notice, moved here from donated code from IBM.</li>
+ <li>uima-docbook-olink - this is the shared olink data. This project's source contains the
+ information about the UIMA Bookshelf - the set of books that can cross-reference each other,
+ and how they're laid out (current layout - they all are subitems of one common directory).
+ </li>
+ <li>uima-docbook-resource-bundle - holds common information needed by docbook builds, including
+ the specification for the titlepage.</li>
+ <li>uima-assembly-single-project - holds the binary assembly descriptor for single-projects.</li>
+ </ul></p>
+ <p>There is also one custom Maven plugin (uima-build-helper-maven-plugin) - to get the build month and build year into properties.
+ This is used, for instance, in the common docbook frontmatter - to indicate when the book was
+ built.</p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
<a name="Parent Pom Hierarchy"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Parent Pom Hierarchy</h1></a>
</td></tr>
<tr><td>
<blockquote class="sectionBody">
<p>Parent pom names start with parent-pom-:</p>
<pre>
- top
+ parent-pom-top
- docbook
+ parent-pom-docbook
+
+ parent-pom-ibm-notice
- uimaj
-
- uimaj-eclipse-plugins
+ parent-pom-eclipse-plugins
- uimaj-eclipse-plugins-ibm-notice
-
- uimaj-ibm-notice
- </pre>
+ parent-pom-eclipse-plugins-ibm-notice
+
+ parent-pom-annotator
+
+ parent-pom-single-project
+</pre>
</blockquote>
</p>
</td></tr>
Modified: uima/site/trunk/uima-website/docs/svn.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/svn.html?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/svn.html (original)
+++ uima/site/trunk/uima-website/docs/svn.html Wed May 12 14:46:36 2010
@@ -212,12 +212,10 @@
<tr><td>
<blockquote class="sectionBody">
<p>Apache UIMA uses
-<a class="external" rel="nofollow" href="http://subversion.tigris.org">
+<a class="external" rel="nofollow" target="_blank" href="http://subversion.tigris.org">
Subversion</a> to manage its source code.
If you're new to Subversion, you can check out the
-<a href="http://svnbook.red-bean.com/">online book</a> about Subversion.
-Note that we are currently using Subversion 1.1.x (there are separate
-versions of the book covering 1.0 and 1.1).
+<a href="http://svnbook.red-bean.com/" target="_blank">online book</a> about Subversion.
</p>
<p>
The code for UIMA is stored in several sections:</p>
@@ -226,6 +224,7 @@ versions of the book covering 1.0 and 1.
<li>http://svn.apache.org/repos/asf/uima/uima-as - the Asynchronous Scaleout add-on for base UIMA</li>
<li>http://svn.apache.org/repos/asf/uima/sandbox - a collection of add-ons for UIMA including annotators</li>
<li>http://svn.apache.org/repos/asf/uima/uimacpp - the C++ framework supporting Annotators written in C++</li>
+ <li>http://svn.apache.org/repos/asf/uima/build - Build information and configurations used in building from sources</li>
</ol>
<p>
Each of these have subdirectories: trunk - for the latest, tags - for preserved copies of releases,
@@ -383,24 +382,42 @@ via HTTPS, in order to be able to check
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
- <p>To access the SVN repository from Eclipse, you will need to install the Subclipse plugin from the update site
-<a class="external" rel="nofollow" href="http://subclipse.tigris.org/update_1.0.x">
+ <p>To access the SVN repository from Eclipse, please use Maven's m2eclipse plugin
+ from <a class="external" rel="nofollow" target="_blank" href="http://m2eclipse.sonatype.org/sites/m2e">
+ http://m2eclipse.sonatype.org/sites/m2e</a>, and
+ the Subclispe plugin from
+<a class="external" rel="nofollow" target="_blank" href="http://subclipse.tigris.org/update_1.0.x">
http://subclipse.tigris.org/update_1.0.x</a>.
-
-You can then check out code as follows:
+</p>
+ <p class="note">Note that m2eclipse comes with a bundled version of maven 3 included. If that version is < 3.0.0-beta-1,
+ please obtain the latest maven 3 build, install it, and then use the preferences for Eclipse Maven to tell
+ it to use the later maven 3 build for running builds.</p>
+ <p>The individual projects can be checked out without worrying about relative path
+ dependencies, except for a few projects that refer to other projects using relative addresses.
+ Currently, the projects which do that are
+ <ul>
+ <li>the aggregator projects - those special maven projects
+ that only serve to aggregate build operations for a set of other projects, and</li>
+ <li>the "distribution" projects - those that build entire distributions.</li>
+ </ul></p>
+ <p>The recommended way to check out many projects at once is to use the command line (non-Eclipse) svn checkout
+ command. Use this to check out entire sets of projects under one of the trunks, for instance.
+ Once they are checked out, you can import them into an Eclipse workspace using the
+ File -> Import -> Maven -> Existing Maven Projects.
+</p>
+ <p>You can also check out individual projects using
<ol>
<li>Bring up the "SVN Repositories" View (from Window -> Show View -> Other)</li>
<li>Right click in the SVN Repositories View and select New -> Repository Location.</li>
<li>Enter the URL <code>http://svn.apache.org/repos/asf/uima/uimaj/trunk</code> (or <code>https://</code>...)</li>
- <li>Shift-click to select all of the projects, right click and choose "Checkout..."</li>
+ <li>Shift-click to multi-select the projects you want, right click and choose "Checkout as Maven Projects"</li>
<li>Select "Check out into the workspace as projects" and click "Finish"</li>
-</ol>
-
-This will check out all of the code, but as "plain" (that is, not Java) projects.
-To convert the projects to Java projects, you need to do <code>mvn install eclipse:eclipse</code>
-in the uimaj project directory, the uimaj-as project directory, and the SandboxDistr project directory,
-for the base UIMA, UIMA-AS, and the Sandbox Distribution, depending on which ones you checked out.
-See below for more details on these steps.
+</ol>
+</p>
+ <p class="note">
+ If you check out projects individually, m2eclipse may put them into individual subfolders, causing the
+ distribution and aggregation projects to no longer have the right relative directory specifications.
+ If this happens, the best thing to do is to re-checkout the entire set of related items in one go.
</p>
</blockquote>
</td></tr>
@@ -521,22 +538,16 @@ http://jira.atlassian.com/browse/SVN-37<
<tr><td>
<blockquote class="sectionBody">
<p>
-Apache UIMA uses Maven 2 to do builds. Release 2.2.x of Maven, or later, is required.
-Download Maven from <a class="external" rel="nofollow" href="http://maven.apache.org">
+Apache UIMA uses Maven 2 or 3 to do builds. Release 2.2.x of Maven, or later, is required.
+Download Maven from <a class="external" rel="nofollow" target="_blank" href="http://maven.apache.org">
http://maven.apache.org</a> and add <maven-home>/bin to your path.
</p>
<p>
- The source can be obtain in two ways:
+ The source can be obtained in two ways:
<ol><li>You can checkout the source from SVN, from trunk, or a particular tagged release, or</li>
<li>you can use the source version of the release artifact you download from the download
page.</li></ol>
</p>
- <p>
- If you want to build the DocBooks from the Docbook sources,
- you need to set up your DocBook tooling by obtaining the needed parts, either from the UIMA SVN
- or from other places on the web (see below). Note that the PDF files only build correctly on a
- Windows platform (due to font issues).
-</p>
<table class="subsectionTable" id='building.command.line'>
<tr><td>
@@ -550,29 +561,27 @@ http://maven.apache.org</a> and add <
<tr><td>
<blockquote class="subsectionBody">
<p>
- To build base UIMA from the command line,
+ These instructions apply to the release 2.3.1 and onwards version. To build base UIMA from the command line,
<longquote><pre>
-$> cd uimaj
+$> cd aggregate-uimaj
$> mvn install
</pre></longquote>
</p>
- <p>Builds for uima-as and the sandbox projects work similarly, however the build process requires that
- base UIMA be in the same containing directory. If you check out these other projects from SVN,
- you will need to copy the projects from these checkouts into the same base directory as
- base UIMA, so all the projects are siblings within that directory. The same is true for building
- from the source distribution.
+ <p>Builds for uima-as and the sandbox projects work similarly.
</p>
<p>Once the directory is set up, do:
<longquote><pre>
-$> cd uimaj-as
+$> cd aggregate-uima-as
$> mvn install
or
-$> cd Sandbox
+$> cd aggregate-addons
$> mvn install
</pre></longquote>
</p>
<p>
-This should build all of the jars and run the unit tests. Each jar will be located under the <code>target</code> subdirectory of its project, for example <code>uimaj-core/target/uima-core.jar</code>.
+This should build all of the jars, any docbooks, and run the unit tests.
+The output artifacts (Jars, html and pdf documents, etc.) are placed in each project's "target" directory, and
+also are put into your local Maven repository.
</p>
<p>If you want to build just one of the "projects", and not the whole thing, cd to the project you want to build, and run
mvn install there.</p>
@@ -591,44 +600,12 @@ mvn install there.</p>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
- <p>
- <ol>
- <li><p>First, follow all the steps under "Building from the command line, above." You
- will only need to do this once.</p></li>
- <li><p>(Optional) If you want a new workspace for the maven work, start Eclipse and create a new workspace. </p></li>
- <li><p>In a command window, execute
- <blockquote>
- <pre>
-mvn -Declipse.workspace=<eclipse workspace dir> \
- eclipse:add-maven-repo</pre>
- </blockquote>
- This adds a maven repository to your machine (On Windows, under documents & settings / .m2 /
- repository), and sets up an Eclipse Java Build Path variable to reference it.</p></li>
- <li><p>Use Eclipse's SVN Repository explorer to checkout all the projects under uimaj/trunk.
- Tell it to create new Java projects for these.</p></li>
- <li><p>
- <code>cd uimaj</code> to switch to the Eclipse workspace project for <code>uimaj</code> (it has the top level
- POM), and run the command:
- <blockquote><code>mvn eclipse:eclipse</code></blockquote>
- </p><p>
- If you haven't run the "install" using maven (because you forgot to follow all the steps under
- "Building from the command line, above"), you should do the command
- <code>mvn install eclipse:eclipse</code>. The "install" argument builds UIMA using maven,
- before the eclipse:eclipse goal is run. This
- is needed for the Eclipse Plugins that are part of UIMA - these projects have their
- "MANIFEST.MF" file built by maven from the information in the maven POMs. This step
- may take a few minutes because the "install" lifecycle includes running the unit tests.
- </p></li>
- <li><p>Return to Eclipse, and if needed, select all the projects and push F5 to "refresh" them (because the
- previous command changed the .project and .classpath files). You can set your workspace to automatically
- refresh - in which case skip this step.</p></li>
- <li><p>The projects should now compile without errors, and have build paths which reference copies of things in
- your local maven repository.</p></li>
- <li><p>You can run the unit tests in Eclipse by right-clicking on a folder (for example
- <code>uimaj-core/src/test/java</code>) and selecting Run As -> JUnit Test. This will run all tests
- under that folder.</p></li>
- </ol>
+ <p>With m2eclipse plugin, you can right-click any maven project, and select Run -> maven commands to do maven runs. Furthermore, you can
+ save run configurations you build using Run -> Run As ... -> Maven build ...; these become launchable using the standard Eclipse run menus.
</p>
+ <p>Within a project, you can run the unit tests in Eclipse by right-clicking on a folder (for example
+ <code>uimaj-core/src/test/java</code>) and selecting Run As -> JUnit Test. This will run all tests
+ under that folder.</p>
</blockquote>
</td></tr>
</table>
@@ -677,7 +654,7 @@ If not using Eclipse, you can use <code>
Please refer to this page: <a href="distribution.html">Building a distribution</a> for
details on how to do this.</p>
<p>
-To build a distribution, first do a build as described in "Building from the command line".
+ To build a distribution, first do a build as described in "Building from the command line".
Then (assuming you set up the Eclipse path using one of the first 2 methods, execute the following:
<longquote><pre>
cd ../uimaj-distr
@@ -685,8 +662,7 @@ mvn install
</pre></longquote>
</p>
<p>
-This will build the javadocs and the manual (using docbooks, as described below), will create the
- Eclipse update site for the Eclipse plugins, and will create
+This will build the javadocs, and will create
.zip and .tar.gz archives of the full UIMA distribution in the <code>uimaj-distr/target</code>
directory.
@@ -698,17 +674,14 @@ cd ..\uima-as-distr
mvn install
</pre></longquote>
</p>
- <p>Similarly, for building the sandbox distribution, first be sure you've built
- the projects themselves (see above) and then do:
-<longquote><pre>
+ <p>Sandbox projects are build for distribution individually, by cd-ing to the individual
+ sandbox project and running "mvn install". Note that this may not work on projects that
+ are not advanced to the point where they are released - not all projects in the Sandbox are
+ in a state where they are buildable.
+<!--longquote><pre>
cd annotator-package
mvn install
-</pre></longquote>
-</p>
- <p>
- This maven command will create the assemblies in the <code>target</code> directory,
- and will also run the Release Audit Tool (RAT) on the result.
- <ul><li>To skip running RAT, use the command <code>mvn package</code>.</li></ul>
+</pre></longquote-->
</p>
</blockquote>
</td></tr>
@@ -725,50 +698,11 @@ mvn install
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
- <p>
- The UIMA Source distribution includes the uima-docbook-tool project, which is the tooling needed
- to build the Docbooks; the actual Docbook sources are in the uima-docbooks project, in the src
- directory. The DocBook tooling requires several components that are not included in the source
- distribution, but instead are automatically downloaded from the internet
- the first time you run the tools; you will be asked to accept the licenses for these components.
- Please read the README.FIRST and README files in the uima-docbook directory
- for important information about setting up the tooling. In particular, in order
- to get the images to be rendered in the PDF output, you must obtain the
- "Java Advanced Imaging" library from Sun.
- </p>
- <p>Note that the uima-docbooks project is not built using Maven; it is built by an ant script. If you
-want to build the documentation without building the entire UIMA distribution,
-cd to the uima-docbooks directory, and run <code>ant</code>. This will build all 4 books into the
-uima-docbooks/target directory.</p>
- <p>Note that each book is actually built twice - the first build only runs the transforms to get the
- links established and setup of cross reference database table. The second outputs the html and pdf files,
- using the cross reference database table just created.</p>
- </blockquote>
- </td></tr>
- </table>
- <table class="subsectionTable" id='building.docbooks.a4'>
- <tr><td>
-
-
-
- <a name="Creating A4-size PDF documentation">
- <h2>Creating A4-size PDF documentation
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>If you don't live in the US, you may wish to create your PDF documentation in a different
- format, e.g., A4. To do this, edit the file
- <code>uima-docbook-tool/properties/default.docbook.properties</code>. It contains a line
- </p>
- <p>
- <code>paper.type = Letter</code>
- </p>
- <p>Change this setting to <code>A4</code> and rebuild the documentation. Note: if you've previously
- built the documentation, you need to run <code>ant clean</code> first, as the build doesn't pick
- up on this change automatically.
- </p>
+ <p>Docbook processing is done normally as a part of regular maven building of projects
+ which have Docbooks.
+ The base uimaj projects have 4 docbooks, and there is an aggregate project which builds
+ all 4 of these: aggregate-uimaj-docbooks.
+ Docbooks are built by the normal maven lifecycle, in the prepare-package phase.</p>
</blockquote>
</td></tr>
</table>
Added: uima/site/trunk/uima-website/xdocs/dev-docbook.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/dev-docbook.xml?rev=943523&view=auto
==============================================================================
--- uima/site/trunk/uima-website/xdocs/dev-docbook.xml (added)
+++ uima/site/trunk/uima-website/xdocs/dev-docbook.xml Wed May 12 14:46:36 2010
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+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.
+-->
+<document>
+
+<properties>
+<title>Using Docbook for documentation</title>
+<author email="dev@uima.apache.org">
+ UIMA Documentation Team</author>
+</properties>
+
+<body>
+ <p>This page is for developers, and describes how we use
+ <a href="http://www.docbook.org/" target="_blank">Docbook</a> for
+ technical documentation.
+ Docbook files can be incorporated with projects and processed as part of the
+ Maven build.</p>
+
+ <p style="padding-left: 2em">Docbooks are usually included in projects that
+ produce other artifacts, e.g., Jars. They can also be
+ in projects which only produce a docbook (in which case, the maven packaging type
+ should be set to "pom").
+ The current implementation allows 0 or 1 "book" to be produced, per project.
+ </p>
+
+ <p>Docbooks can hyperlink to each other. This linking includes the ability to reference details
+ about the other link, for instance, what "page" (for PDF rendering formats) the link is on.
+ To make this work, the docbook tool pipeline keeps a central database,
+ called the Olink Database, for all docbooks
+ that want to provide this information. When a docbook is processed, this information is updated,
+ and is then available when other docbooks are processed.
+ </p>
+
+ <p>Docbook processing is activated by default for all projects that have
+ docbook source in the normal folder position in the project (src/docbook).
+ Docbook processing is
+ bound to the prepare-package and package phases. It can be skipped from the
+ command line by specify the negation of the profile "processDocbook" using the
+ Maven command line option <code>-P !processDocbook</code>.
+ </p>
+
+ <section name="UIMA Docbook Bookshelf">
+ <p>To facilitate cross referencing among UIMA docbooks, we ask users
+ when downloading these books to place the downloaded files in a common
+ directory, which we refer to as the UIMA bookshelf.</p>
+
+ <p>When this is done, the user will be able to follow cross reference
+ linkages within the downloaded books, without needing an internet
+ connection.</p>
+ </section>
+
+ <section name="Docbook Conventions used">
+
+ <p>The build tooling expects the following conventions to
+ be followed:</p>
+
+ <ul>
+ <li>Docbook source(s) should be put in the directory src/docbook/. The
+ existance of this directory is what causes the normal parent pom chain
+ to notice that docbook processing is needed during the build.</li>
+ <li>Currently, the docbooks are written to the 4.4 version of Docbook;
+ begin your files with the standard boilerplate (best to copy from another
+ docbook in the "set".</li>
+ <li>There is one designated file specified in project's POM as the property
+ "<bookNameRoot>" which must have as its value the name of the docbook
+ source file to process, minus the ".xml". This supports breaking large
+ docbooks into multiple parts, perhaps one per "chapter"; you have one
+ top-level docbook which xincludes the other parts. See the file
+ uima-docbook-overview-and-setup/src/docbook/overview-and-setup.xml for
+ an example of using this technique.
+ <p>The bookNameRoot name serves also as the book "name"
+ and must be unique among all the docbooks in the UIMA bookshelf.</p>
+ </li>
+ <li>The first part of the top docbook source must include the line:
+ <pre><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="../../target/docbook-shared/common_book_info.xml"/></pre>
+ This allows it to pick up the standard license, disclaimers, and copyright notices.
+ Please set the POM element <inceptionYear>; this is used in the copyright notice.
+ </li>
+ <li>Xinclude support is automatically provided by the docbkx toolchain; you do not have to set
+ XML entities for this at the top of your file.</li>
+ <li>Images to be included are by convention expected be located in a folder named
+ "images/[bookNameRoot]", which is located in the same parent directory as
+ the top docbook source file. The [bookNameRoot] is the name of the top docbook source
+ file, less the ".xml". The "extra" directory under "images" is used to separate
+ images from the different docbooks in the uima bookshelf.</li>
+ <li>Standard entities may be included, using the form:
+ <pre><!ENTITY imgroot
+ "images/insert-booknameroot-here/optional-sub-dir/">
+<!ENTITY % uimaents SYSTEM
+ "../../target/docbook-shared/entities.ent">
+%uimaents;</pre>
+ <p>The docbook-shared/entities... are common shared entities you can use; please
+ see the source for the list, located here:
+ <a href="http://svn.apache.org/repos/asf/uima/build/trunk/uima-docbook-resource-bundle/src/main/resources/docbook-shared/entities.ent"
+ target="_blank">here</a>.</p></li>
+ </ul>
+ </section>
+
+ <section name="Cross Referencing among UIMA Docbooks">
+ <p>Docbooks support an enhanced cross-referencing among
+ docbook collections, using a link style called "olink".
+ Olinks allow cross-referencing and
+ hyperlinking among documents, using extra saved information about the
+ target document (being linked to, as contrasted with plain href style
+ links, which only have the link url). For instance, in PDFs, there's
+ extra info enabling the referring doc to say "page 123 in document abc".
+ For PDF and HTML, olinks allow the referring text to include a hyperlink
+ which includes target document's element title, and maybe a number (if it
+ has numbered items - such as our chapter / section numbers in the main
+ UIMA documentation). So you can get a link that looks like this:
+ <ul><li>see Section 1.5.1, ?Annotator Methods?</li></ul>
+ where the 1.5.1 was generated by docbook processing, and the "Annotator
+ Methods" was the title of that section.</p>
+
+ <p>
+ To make olinks work, each time a docbook is processed, an extra database
+ of info for that docbook is created, containing just the things needed for
+ this. This database, together with some other data about how the
+ multiple interlinking docbooks are arranged, is then
+ used when processing a docbook.
+ </p>
+
+ <p>
+ Olink data for all UIMA docbooks is stored in one additional project,
+ uima-docbook-olink, that has an attached artifact: a zip file of all
+ olink data.
+ </p>
+
+ <p>
+ This project is at the level 1-SNAPSHOT, and will stay there.
+ Because it's a snapshot, it is updated whenever it is "deployed".
+ Each docbook processing run updates that docbook's olink data.
+ Committers should deploy the snapshot to share updates of olink
+ data with others.
+ </p>
+
+ </section>
+
+ <section name="Creating a new Docbook">
+ <p>
+ <ul>
+ <li>Add a src/docbook directory, and put an images directory there
+ for new images (if you have images), and one or more XML files containing docbook source.</li>
+ <li>Put the name of the top docbook xml file in the project's docbookNameRoot property</li>
+ <li>Add this docbook to the UIMA bookshelf - modifying the uima-docbook-olink project's
+ src/main/docbook-olink/{html, htmlsingle, and pdf}/site.xml files.
+ <ul><li>Add a stanza to the site-map, and</li>
+ <li>add an entity for the docbookNameRoot at the top of the site file.</li>
+ </ul>
+ </li>
+ </ul>
+ </p>
+ </section>
+</body>
+</document>
Modified: uima/site/trunk/uima-website/xdocs/distribution.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/distribution.xml?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/distribution.xml (original)
+++ uima/site/trunk/uima-website/xdocs/distribution.xml Wed May 12 14:46:36 2010
@@ -33,8 +33,8 @@ under the License.
<p>This is because specifying source and target of, say, Java 1.5, and then accidentally using a
Java 6 library method, surprisingly doesn't cause a mvn driven compile failure (if Maven is running under Java 6).</p>
-<p>
- <ul>
+ <p>
+ <ul>
<li><a href="#Building the Apache UIMA base distribution">Building the Apache UIMA base distribution</a></li>
<li><a href="#Building the Apache UIMA-AS distribution">Building the Apache UIMA-AS distribution</a></li>
<li><a href="#Building Apache UIMA Sandbox distributions">Building Apache UIMA Sandbox distributions</a></li>
Modified: uima/site/trunk/uima-website/xdocs/maven-design.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/maven-design.xml?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/maven-design.xml (original)
+++ uima/site/trunk/uima-website/xdocs/maven-design.xml Wed May 12 14:46:36 2010
@@ -48,15 +48,12 @@ the Apache Nexus repository, for staging
things and arranges POMs in a parent-child hierarchy, by having the child
identify the parent POM. The other kind is aggregation - POMs which specify sub-modules
for purposes of building multi-module things, and releasing them all at once. For clarity,
-we keep these two uses in separate POMs: parent POMs do not do aggregation,
+we mostly keep these two uses in separate POMs: parent POMs do not do aggregation,
and aggregation POMs do not do common factoring.</p>
<p>Our parent poms are kept in a folder, under a top level SCM node called "build", which holds things
needed for building, but which are not part of normal aggregate distributions.
Aggregation POMs are kept with the SCM node focused on those modules being aggregated.</p>
-
- <p class="note">A recent change in Maven 3 now requires that POMs whose parent poms are not in the
- parent directory, have an empty <relativePath/> element.</p>
</section>
<section name="POM style">
@@ -65,22 +62,27 @@ and aggregation POMs do not do common fa
<ul>
<li>POMs contain a <url> element. If they don't, they will inherit from their parent
following an assumption that the url is the parent url value followed by "/" and
- this POMs artifactId. This may or may not be how our website is set up, so
- it is best to just code the url that is correct for the new project.</li>
+ this POMs artifactId. If this does not correspond to how the website is set up,
+ please specify the url that is correct for the new project.
+ In the Maven spirit of convention over configuration,
+ web pages for specific projects (such as the
+ individual annotators) will be set up this way, so the <url> element can be
+ omitted.</li>
<li>The SCM connection is needed for releasing - and needs to be accurate for this
component.</li>
<li>The POM's "version" is stated literally, not via a "property", etc. Maven 3
will complain if you use properties here, and the release mechanism for maven
manipulates these values (removing SNAPSHOT, incrementing things, etc.)</li>
- <li>The POM's groupId is usually omitted - in which case, it inherits from the
- parent. Doing this is a recommended best practice.</li>
+ <li>The POM's groupId is omitted if it is the same as the parent pom's; it inherits from the
+ parent.</li>
+ <li>The packaging is omitted if it is "jar".</li>
</ul>
</p>
<p>Maven 3 has more requirements on POMs
<p>A transition to Maven 3 is occuring in 2010. The Eclipse plugin, m2eclipse, "embeds"
Maven 3 already.</p>
<ul>
- <li>Property names have to include their path from project, etc. For instance, you cannot use
+ <li>Build variable names have to include their path from project, etc. For instance, you cannot use
${version}, you have to use ${project.version}.</li>
</ul></p>
</section>
@@ -93,53 +95,178 @@ and aggregation POMs do not do common fa
<li>Docbook</li>
<li>UIMA Website (Anakia)</li>
</ul>
-
- <p>For each Java source artifact, the Apache standard parent POM builds and attaches
- a <ul><li>source zip, and a</li><li>Javadocs zip</li></ul>
- to the main Jar artifact. It doesn't do any standard actions for other documentation (e.g., docbook style).</p>
-
- <p>We use Docbook style for much of our other documentation,
+
+ <p>We use Docbook style for much of our other documentation,
the main exception being our website, which uses Anakia.
See <a href="dev-docbook.html">the development docbook page</a> for details.</p>
- <p>Normally, all website content is kept in SVN in the uima/site/trunk/uima-website/docs directory; this directory is
+ <p>For each Java source artifact, when the apache-release profile is specified (usually during the
+ release process), the Apache standard parent POM builds and attaches
+ a <ul><li>source zip, and a</li><li>Javadocs zip</li></ul>
+ to the main Jar artifact. It doesn't do any standard actions for other documentation (e.g., docbook style).
+ Docbooks are built during the normal lifecycle.</p>
+
+ <p>Normally, all website-ready content is kept in SVN in the uima/site/trunk/uima-website/docs directory; this directory is
checked out into the right spot on people.apache.org. For large generated documents,
- we have the option to generate them from sources in svn, and deploy them directly to the right spot on people.apache.org. This avoids
- using SVN for large generated files. This satisfies the
+ we have the option to generate them from sources in svn, and deploy them directly to the right spot on people.apache.org.
+ This avoids using SVN for large generated files. This satisfies the
<a href="http://apache.org/dev/project-site.html" target="_blank">requirements</a>
for Apache websites.</p>
</section>
+<section name="Packaging Individual Projects">
+ <p>
+ The UIMA Project, in addition to the main frameworks, has Annotators and other components and tools
+ (such as the SimpleServer) that it releases. These in the past have been released as a big
+ assembly we called the Sandbox, but now are are being supported as individual items.
+ </p>
+
+ <p>
+ There are two kinds of packaging for these supported, by using one of the following parent-poms:
+ <ul><li>parent-pom-annotator - this packages things as a PEAR</li>
+ <li>parent-pom-single-project - this packages things as a tar / zip file having a lib/ directory
+ with the generated Jar and dependencies, plus other files (see below).</li></ul>
+ </p>
+
+ <p>
+ The individual Annotators are mostly packaged as a
+ <a href="http://uima.apache.org/downloads/releaseDocs/2.3.0-incubating/docs/html/references/references.html#ugr.ref.pear">
+ PEAR</a> file, which is the UIMA standard for annotator component packaging and distribution.
+ The Pear is generated using the PearPackagingMavenPlugin, which generates automatically a
+ conventional Pear Installation Descriptor, from the information in the project.
+ The PEAR artifact is generated in addition to Jar of the code, and includes
+ other items such as the generated documentation, data, and a lib/ directory with other Jars
+ needed for the PEAR to operate. This PEAR is the packaged equivalent of a binary distribution
+ artifact produced for the main framework, and comes with a license and notice that
+ covers any included libraries. Generated PEARs are included in the artifacts that are managed by
+ Maven, and are available in the Maven repository system.
+ </p>
+
+ <p class="note">
+ The PEAR internal folder "src" is not used by components here; the source is instead available
+ via the standard Maven source packaging.
+ </p>
+
+ <p>
+ Projects indicate they want PEAR packaging by making the parent pom be parent-pom-annotator.
+ </p>
+
+ <p>
+ PEARs must have a "main" descriptor, which is the one normally used to configure and run
+ the annotator. When using the parent-pom-annotator to indicate PEAR packaging, you must include a property called
+ <pearMainDescriptor> in the Annotator's POM, whose value is the path from the project base directory
+ identifying the main descriptor. For example, if the folder "desc" was at the root of your project, the
+ value might be something like "desc/my-main-descriptor.xml".
+ </p>
+
+ <p>If an annotator isn't suitable for PEAR packaging, perhaps because it is inappropriate to have
+ one pre-done main descriptor, then the annotator can be packaged as a single-project, instead, by
+ making the POM's parent parent-pom-single-project.</p>
+
+ <h2>Conventions for structuring individually releaseable projects</h2>
+ <p>Use these conventions to get your annotator properly packaged when you use the parent-pom-annotator or
+ the parent-pom-single-project as your parent pom:
+ <ul>
+ <li>Use <package>jar</package> (which is the default, so it should be omitted), if there
+ is a Jar that should be built (as is usually the case). This will cause the main
+ annotator Jar to be built, including any resources (plus the top-level desc folder, if it exists), as normal.</li>
+ <li>Create the required License, Notice, and optional Readme, and Release Notes files
+ in the project directory at the top level; these will be included in the
+ PEAR or simple project binary assembly at the top level.
+ The License and Notice files should be for the entire project, including
+ all third-party Jars etc. being distributed.
+ <p style="margin-left: 2em">The generated Jar, which only has Apache-developed code, includes
+ the normal Apache License and Notice files.</p></li>
+ <li>Dependencies: those marked with scope "compile" (the default) or "runtime"
+ are copied to the PEAR or single-project's lib/ directory. To keep a dependency needed for compiling
+ from being included in the lib/, give it a scope of "provided".</li>
+ <li>Using the following folders at the top level of your project (which is the "conventional" PEAR layout,
+ will cause the contents of these folders to be added to the corresponding files in the PEAR or binary zip/tar:
+ <ul>
+ <li>desc - for descriptiors, including the main descriptor</li>
+ <li>bin - (optional) for extra executables</li>
+ <li>lib - (optional) for libraries (not being included via the Maven dependencies mechanism)</li>
+ <li>doc - (optional) not normally used, but can have additional user-ready documentation</li>
+ <li>data - (optional) for arbitrary data</li>
+ <li>resources - (optional) not normally used, but can have additional data which should be on the classpath</li>
+ <li>conf - (optional) for extra configuration files</li>
+ <li>src - not-used</li>
+ </ul>
+ <p>The following Maven conventional information will be added to the above:
+ <ul>
+ <li>lib - dependencies with scope "compile" or "runtime" are resolved from maven repositories and added to the lib/</li>
+ <li>doc - docbook sources under src/docbook are processed and the html and pdf forms are added</li>
+ <li>Maven resources - (not the top level resources directory described above)
+ are by convention included in the Jar, and are not included in this folder</li>
+ </ul>
+ </p>
+ </li>
+ </ul>
+ </p>
+
+</section>
+
<section name="Building Assemblies for Distribution">
<p>The normal operation of Maven is concerned with the building of individual modules. Each module
when built produces maven artifacts in repositories (your local repository, or perhaps uploaded
to a snapshot or staging repository).</p>
<p>When releases are done, additional artifacts are constructed using the distribution assemblies.
- </p>
+ We have these for
+ <ul>
+ <li>UIMA - the base Java framework</li>
+ <li>UIMA-AS - the asynchronous scaleout add-on</li>
+ <li>UIMA Add-ons - not decided yet, but it's likely we'll just release these as individual projects.
+ So there is no add-ons-distr project (yet).</li>
+ <!--li>UIMA Add-ons - annotators and other add-on components such as the SimpleServer</li-->
+ <li>UIMACPP - the C++ framework</li>
+ </ul>
+ </p>
<h2>Distribution Pom - Clean phase</h2>
- <p>The clean phase
- of the distribution POMs includes running the dependency:purge-local-repository plugin
- to purge the local repository of dependencies.
+ <p>The clean phase of the distribution POMs includes running the dependency:purge-local-repository plugin
+ to purge the local repository of dependencies, when activated by the apache-release profiles.
</p>
</section>
+<section name="Build resources">
+ <p>During the build process, several resources are used, and are built into Maven Artifact Jars with
+ Maven coordinates:
+ <ul>
+ <li>uima-jar-resource-bundle - this is the standard License Notice and Dependencies from the
+ Apache common parent pom, except it allows adding post-Notice text. We use this when
+ we need to include the IBM Copyright notice, moved here from donated code from IBM.</li>
+ <li>uima-docbook-olink - this is the shared olink data. This project's source contains the
+ information about the UIMA Bookshelf - the set of books that can cross-reference each other,
+ and how they're laid out (current layout - they all are subitems of one common directory).
+ </li>
+ <li>uima-docbook-resource-bundle - holds common information needed by docbook builds, including
+ the specification for the titlepage.</li>
+ <li>uima-assembly-single-project - holds the binary assembly descriptor for single-projects.</li>
+ </ul></p>
+
+ <p>There is also one custom Maven plugin (uima-build-helper-maven-plugin) - to get the build month and build year into properties.
+ This is used, for instance, in the common docbook frontmatter - to indicate when the book was
+ built.</p>
+</section>
+
<section name="Parent Pom Hierarchy">
<p>Parent pom names start with parent-pom-:</p>
<pre>
- top
+ parent-pom-top
- docbook
+ parent-pom-docbook
+
+ parent-pom-ibm-notice
- uimaj
-
- uimaj-eclipse-plugins
+ parent-pom-eclipse-plugins
- uimaj-eclipse-plugins-ibm-notice
-
- uimaj-ibm-notice
- </pre>
+ parent-pom-eclipse-plugins-ibm-notice
+
+ parent-pom-annotator
+
+ parent-pom-single-project
+</pre>
</section>
</body>
</document>
\ No newline at end of file