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 2008/08/28 23:28:16 UTC
svn commit: r689997 [19/32] - in /incubator/uima/uimaj/trunk/uima-docbooks:
./ src/ src/docbook/overview_and_setup/ src/docbook/references/
src/docbook/tools/ src/docbook/tutorials_and_users_guides/
src/docbook/uima/organization/ src/olink/references/
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.doc_analyzer.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.doc_analyzer.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.doc_analyzer.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.doc_analyzer.xml Thu Aug 28 14:28:14 2008
@@ -1,275 +1,275 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY imgroot "../images/tools/tools.doc_analyzer/" >
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
-%uimaents;
-]>
-<!--
-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.
--->
-<chapter id="ugr.tools.doc_analyzer">
- <title>Document Analyzer User's Guide</title>
-
-
-<para>The <emphasis>Document Analyzer</emphasis> is a tool provided by the
-UIMA SDK for testing annotators and AEs. It reads text files from your disk, processes them using an AE, and
-allows you to view the results. The
-Document Analyzer is designed to work with text files and cannot be used with
-Analysis Engines that process other types of data.</para>
-
-<para>For an introduction to developing annotators and Analysis
-Engines, read
- <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/>.
- This chapter is a user's guide for using the Document Analyzer tool, and
-does not describe the process of developing annotators and Analysis Engines.</para>
-
-<section id="ugr.tools.doc_analyzer.starting">
- <title>Starting the Document Analyzer</title>
-
-<para>To run the Document Analyzer, execute the <literal>documentAnalyzer</literal> script that is in the <literal>bin</literal> directory of your UIMA SDK installation, or, if you
-are using the example Eclipse project, execute the <quote>UIMA Document Analyzer</quote>
-run configuration supplied with that project.</para>
-
-<para>Note that if you're planning to run an Analysis Engine
-other than one of the examples included in the UIMA SDK, you'll first need to
-update your CLASSPATH environment variable to include the classes needed by
-that Analysis Engine.</para>
-
-<para>When you first run the Document Analyzer, you should see a
-screen that looks like this:
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>Document Analyzer GUI</phrase>
- </textobject>
- </mediaobject>
- </screenshot></para>
-
-
- </section>
-
- <section id="ugr.tools.doc_analyzer.running_an_ae">
- <title>Running an AE</title>
-
-
-
-<para>To run a AE, you must first configure the six fields on
-the main screen of the Document Analyzer.</para>
-
-<para><emphasis role="bold">Input Directory:</emphasis>
- Browse to or type the path of a directory containing text files that you
-want to analyze. Some sample documents
-are provided in the UIMA SDK under the <literal>examples/data</literal>
-directory.</para>
-
-<para><emphasis role="bold">Output Directory:</emphasis> Browse to or type the path of a directory where you want
- output to be written. (As we'll see later, you won't normally need to look directly at these files, but the
- Document Analyzer needs to know where to write them.) The files written to this directory will be an XML
- representation of the analyzed documents. If this directory doesn't exist, it will be created. If the
- directory exists, any files in it will be deleted (but the tool will ask you to confirm this before doing so). If you
- leave this field blank, your AE will be run but no output will be generated.</para>
-
-<para><emphasis role="bold">Location of AE XML Descriptor:</emphasis>
- Browse to or type the path of the descriptor
-for the AE that you want to run. There
-are some example descriptors provided in the UIMA SDK under the <literal>examples/descriptors/analysis_engine</literal> and <literal>examples/descriptors/tutorial</literal> directories.</para>
-
-<para><emphasis role="bold">XML Tag containing Text:</emphasis>
- This is an optional feature. If you enter a value here, it specifies the
-name of an XML tag, expected to be found within the input documents, that
-contains the text to be analyzed. For
-example, the value <literal>TEXT</literal> would cause the AE to only
-analyze the portion of the document enclosed within <TEXT>...</TEXT>
-tags. Also, any XML tags occuring within that text will be removed prior to analysis.</para>
-
-<para><emphasis role="bold">Language:</emphasis>
- Specify
-the language in which the documents are written. Some Analysis Engines, but not all, require
-that this be set correctly in order to do their analysis. You can select a value from the drop-down
-list or type your own. The value entered
-here must be an ISO language identifier, the list of which can be found here:
- <ulink url="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"/>.
-</para>
-
-<para><emphasis role="bold">Character Encoding:</emphasis>
- The character encoding of the input files. The default, UTF-8, also works fine for ASCII
-text files. If you have a different
-encoding, enter it here. For more
-information on character sets and their names, see the Javadocs for
- <literal>java.nio.charset.Charset</literal>.</para>
-
-<para>Once you've filled in the appropriate values, press the
-<quote>Run</quote> button.</para>
-
-<para>If an error occurs, a dialog will appear with the error
-message. (A stack trace will also be
-printed to the console, which may help you if the error was generated by your
-own annotator code.) Otherwise, an
-<quote>Analysis Results</quote> window will appear.</para>
-
-
-
-</section>
-
- <section id="ugr.tools.doc_analyzer.viewing_results">
- <title>Viewing the Analysis Results</title>
-
-<para>After a successful analysis, the <quote>Analysis
-Results</quote> window will appear.
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="4.2in" format="JPG" fileref="&imgroot;image004.jpg"/>
- </imageobject>
- <textobject><phrase>Analysis Results Window</phrase></textobject>
- </mediaobject>
- </screenshot></para>
-
-
-<para>The <quote>Results Display Format</quote> options at the
-bottom of this window show the different ways you can view your analysis – the
-Java Viewer, Java Viewer (JV) with User Colors, HTML, and XML.
- The default, Java Viewer, is recommended.</para>
-
-<para>Once you have selected your desired Results Display
-Format, you can double-click on one of the files in the list to view the
-analysis done on that file.</para>
-
-<para>For the Java viewer, the results display looks like this
-(for the AE descriptor <literal>examples/descriptors/tutorial/ex4/MeetingDetectorAE.xml</literal>):
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image006.jpg"/>
- </imageobject>
- <textobject><phrase>Analysis Results Window showing results from tutorial example 4</phrase></textobject>
- </mediaobject>
- </screenshot></para>
-
-
-<para>You can click the mouse on one of the highlighted
-annotations to see a list of all its features in the frame on the right.</para>
-
-<para>If there are multiple annotation types in the view, you
-can control which ones are selected by using the checkboxes in the legend, the
-Select All button, or the Deselect All button.</para>
-
-<para>If you are viewing a CAS that contains multiple subjects
-of analysis, then a selector will appear at the bottom right of the Annotation
-Viewer window. This will allow you to
-choose the Sofa that you wish to view. Note that only text Sofas containing a non-null document are available
-for viewing.</para>
-
-</section>
-
- <section id="ugr.tools.doc_analyzer.configuring">
- <title>Configuring the Annotation Viewer</title>
-
-<para>The <quote>JV User Colors</quote> and the HTML viewer allow
-you to specify exactly which colors are used to display each of your annotation
-types. For the Java Viewer, you can also
-specify which types should be initially selected, and you can hide types
-entirely.</para>
-
-<para>To configure the viewer, click the <quote>Edit Style
-Map</quote> button on the <quote>Analysis Results</quote> dialog.
- You should see a dialog that looks like this:
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image008.jpg"/>
- </imageobject>
- <textobject><phrase>Configuring the Analysis Results Viewer</phrase></textobject>
- </mediaobject>
- </screenshot></para>
-
-<para>To change the color assigned to a type, simply click on
-the colored cell in the <quote>Background</quote> column for the type you wish to
-edit. This will display a dialog that
-allows you to choose the color. For the
-HTML viewer only, you can also change the foreground color.</para>
-
-<para>If you would like the type to be initially checked
-(selected) in the legend when the viewer is first launched, check the box in
-the <quote>Checked</quote> column. If you
-would like the type to never be shown in the viewer, click the box in the
-<quote>Hidden</quote> column. These
-settings only affect the Java Viewer, not the HTML view.</para>
-
-<para>When you are done editing, click the <quote>Save</quote>
-button. This will save your choices to a
-file in the same directory as your AE descriptor. From now on, when you view analysis results
-produced by this AE using the <quote>JV User Colors</quote> or <quote>HTML</quote>
-options, the viewer will be configured as you have specified.</para>
-
-</section>
-
-<section id="ugr.tools.doc_analyzer.interactive_mode">
- <title>Interactive Mode</title>
-
-
-<para>Interactive Mode allows you to analyze text that you type
-or cut-and-paste into the tool, rather than requiring that the documents be
-stored as files.</para>
-
-<para>In the main Document Analyzer window, you can invoke
-Interactive Mode by clicking the <quote>Interactive</quote> button instead of the
-<quote>Run</quote> button. This will
-display a dialog that looks like this:
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.5in" format="JPG" fileref="&imgroot;image010.jpg"/>
- </imageobject>
- <textobject><phrase>Invoking Interactive Mode</phrase></textobject>
- </mediaobject>
- </screenshot></para>
-
-<para>You can type or cut-and-paste your text into this window,
-then choose your Results Display Format and click the <quote>Analyze</quote>
-button. Your AE will be run on the text
-that you supplied and the results will be displayed as usual.</para>
-
-
-</section>
-
- <section id="ugr.tools.doc_analyzer.view_mode">
- <title>View Mode</title>
-
-<para>If you have previously run a AE and saved its analysis
-results, you can use the Document Analyzer's View mode to view those results,
-without re-running your analysis. To do
-this, on the main Document Analyzer window simply select the location of your
-analyzed documents in the <quote>Output Directory</quote> dialog and click the
-<quote>View</quote> button. You can then
-view your analysis results as described in Section
- <xref linkend="ugr.tools.doc_analyzer.viewing_results"/>.</para>
-
-</section>
- </chapter>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY imgroot "../images/tools/tools.doc_analyzer/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
+%uimaents;
+]>
+<!--
+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.
+-->
+<chapter id="ugr.tools.doc_analyzer">
+ <title>Document Analyzer User's Guide</title>
+
+
+<para>The <emphasis>Document Analyzer</emphasis> is a tool provided by the
+UIMA SDK for testing annotators and AEs. It reads text files from your disk, processes them using an AE, and
+allows you to view the results. The
+Document Analyzer is designed to work with text files and cannot be used with
+Analysis Engines that process other types of data.</para>
+
+<para>For an introduction to developing annotators and Analysis
+Engines, read
+ <olink targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.aae"/>.
+ This chapter is a user's guide for using the Document Analyzer tool, and
+does not describe the process of developing annotators and Analysis Engines.</para>
+
+<section id="ugr.tools.doc_analyzer.starting">
+ <title>Starting the Document Analyzer</title>
+
+<para>To run the Document Analyzer, execute the <literal>documentAnalyzer</literal> script that is in the <literal>bin</literal> directory of your UIMA SDK installation, or, if you
+are using the example Eclipse project, execute the <quote>UIMA Document Analyzer</quote>
+run configuration supplied with that project.</para>
+
+<para>Note that if you're planning to run an Analysis Engine
+other than one of the examples included in the UIMA SDK, you'll first need to
+update your CLASSPATH environment variable to include the classes needed by
+that Analysis Engine.</para>
+
+<para>When you first run the Document Analyzer, you should see a
+screen that looks like this:
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
+ </imageobject>
+ <textobject><phrase>Document Analyzer GUI</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+
+
+ </section>
+
+ <section id="ugr.tools.doc_analyzer.running_an_ae">
+ <title>Running an AE</title>
+
+
+
+<para>To run a AE, you must first configure the six fields on
+the main screen of the Document Analyzer.</para>
+
+<para><emphasis role="bold">Input Directory:</emphasis>
+ Browse to or type the path of a directory containing text files that you
+want to analyze. Some sample documents
+are provided in the UIMA SDK under the <literal>examples/data</literal>
+directory.</para>
+
+<para><emphasis role="bold">Output Directory:</emphasis> Browse to or type the path of a directory where you want
+ output to be written. (As we'll see later, you won't normally need to look directly at these files, but the
+ Document Analyzer needs to know where to write them.) The files written to this directory will be an XML
+ representation of the analyzed documents. If this directory doesn't exist, it will be created. If the
+ directory exists, any files in it will be deleted (but the tool will ask you to confirm this before doing so). If you
+ leave this field blank, your AE will be run but no output will be generated.</para>
+
+<para><emphasis role="bold">Location of AE XML Descriptor:</emphasis>
+ Browse to or type the path of the descriptor
+for the AE that you want to run. There
+are some example descriptors provided in the UIMA SDK under the <literal>examples/descriptors/analysis_engine</literal> and <literal>examples/descriptors/tutorial</literal> directories.</para>
+
+<para><emphasis role="bold">XML Tag containing Text:</emphasis>
+ This is an optional feature. If you enter a value here, it specifies the
+name of an XML tag, expected to be found within the input documents, that
+contains the text to be analyzed. For
+example, the value <literal>TEXT</literal> would cause the AE to only
+analyze the portion of the document enclosed within <TEXT>...</TEXT>
+tags. Also, any XML tags occuring within that text will be removed prior to analysis.</para>
+
+<para><emphasis role="bold">Language:</emphasis>
+ Specify
+the language in which the documents are written. Some Analysis Engines, but not all, require
+that this be set correctly in order to do their analysis. You can select a value from the drop-down
+list or type your own. The value entered
+here must be an ISO language identifier, the list of which can be found here:
+ <ulink url="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"/>.
+</para>
+
+<para><emphasis role="bold">Character Encoding:</emphasis>
+ The character encoding of the input files. The default, UTF-8, also works fine for ASCII
+text files. If you have a different
+encoding, enter it here. For more
+information on character sets and their names, see the Javadocs for
+ <literal>java.nio.charset.Charset</literal>.</para>
+
+<para>Once you've filled in the appropriate values, press the
+<quote>Run</quote> button.</para>
+
+<para>If an error occurs, a dialog will appear with the error
+message. (A stack trace will also be
+printed to the console, which may help you if the error was generated by your
+own annotator code.) Otherwise, an
+<quote>Analysis Results</quote> window will appear.</para>
+
+
+
+</section>
+
+ <section id="ugr.tools.doc_analyzer.viewing_results">
+ <title>Viewing the Analysis Results</title>
+
+<para>After a successful analysis, the <quote>Analysis
+Results</quote> window will appear.
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="4.2in" format="JPG" fileref="&imgroot;image004.jpg"/>
+ </imageobject>
+ <textobject><phrase>Analysis Results Window</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
+
+
+<para>The <quote>Results Display Format</quote> options at the
+bottom of this window show the different ways you can view your analysis – the
+Java Viewer, Java Viewer (JV) with User Colors, HTML, and XML.
+ The default, Java Viewer, is recommended.</para>
+
+<para>Once you have selected your desired Results Display
+Format, you can double-click on one of the files in the list to view the
+analysis done on that file.</para>
+
+<para>For the Java viewer, the results display looks like this
+(for the AE descriptor <literal>examples/descriptors/tutorial/ex4/MeetingDetectorAE.xml</literal>):
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image006.jpg"/>
+ </imageobject>
+ <textobject><phrase>Analysis Results Window showing results from tutorial example 4</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
+
+
+<para>You can click the mouse on one of the highlighted
+annotations to see a list of all its features in the frame on the right.</para>
+
+<para>If there are multiple annotation types in the view, you
+can control which ones are selected by using the checkboxes in the legend, the
+Select All button, or the Deselect All button.</para>
+
+<para>If you are viewing a CAS that contains multiple subjects
+of analysis, then a selector will appear at the bottom right of the Annotation
+Viewer window. This will allow you to
+choose the Sofa that you wish to view. Note that only text Sofas containing a non-null document are available
+for viewing.</para>
+
+</section>
+
+ <section id="ugr.tools.doc_analyzer.configuring">
+ <title>Configuring the Annotation Viewer</title>
+
+<para>The <quote>JV User Colors</quote> and the HTML viewer allow
+you to specify exactly which colors are used to display each of your annotation
+types. For the Java Viewer, you can also
+specify which types should be initially selected, and you can hide types
+entirely.</para>
+
+<para>To configure the viewer, click the <quote>Edit Style
+Map</quote> button on the <quote>Analysis Results</quote> dialog.
+ You should see a dialog that looks like this:
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image008.jpg"/>
+ </imageobject>
+ <textobject><phrase>Configuring the Analysis Results Viewer</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
+
+<para>To change the color assigned to a type, simply click on
+the colored cell in the <quote>Background</quote> column for the type you wish to
+edit. This will display a dialog that
+allows you to choose the color. For the
+HTML viewer only, you can also change the foreground color.</para>
+
+<para>If you would like the type to be initially checked
+(selected) in the legend when the viewer is first launched, check the box in
+the <quote>Checked</quote> column. If you
+would like the type to never be shown in the viewer, click the box in the
+<quote>Hidden</quote> column. These
+settings only affect the Java Viewer, not the HTML view.</para>
+
+<para>When you are done editing, click the <quote>Save</quote>
+button. This will save your choices to a
+file in the same directory as your AE descriptor. From now on, when you view analysis results
+produced by this AE using the <quote>JV User Colors</quote> or <quote>HTML</quote>
+options, the viewer will be configured as you have specified.</para>
+
+</section>
+
+<section id="ugr.tools.doc_analyzer.interactive_mode">
+ <title>Interactive Mode</title>
+
+
+<para>Interactive Mode allows you to analyze text that you type
+or cut-and-paste into the tool, rather than requiring that the documents be
+stored as files.</para>
+
+<para>In the main Document Analyzer window, you can invoke
+Interactive Mode by clicking the <quote>Interactive</quote> button instead of the
+<quote>Run</quote> button. This will
+display a dialog that looks like this:
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.5in" format="JPG" fileref="&imgroot;image010.jpg"/>
+ </imageobject>
+ <textobject><phrase>Invoking Interactive Mode</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
+
+<para>You can type or cut-and-paste your text into this window,
+then choose your Results Display Format and click the <quote>Analyze</quote>
+button. Your AE will be run on the text
+that you supplied and the results will be displayed as usual.</para>
+
+
+</section>
+
+ <section id="ugr.tools.doc_analyzer.view_mode">
+ <title>View Mode</title>
+
+<para>If you have previously run a AE and saved its analysis
+results, you can use the Document Analyzer's View mode to view those results,
+without re-running your analysis. To do
+this, on the main Document Analyzer window simply select the location of your
+analyzed documents in the <quote>Output Directory</quote> dialog and click the
+<quote>View</quote> button. You can then
+view your analysis results as described in Section
+ <xref linkend="ugr.tools.doc_analyzer.viewing_results"/>.</para>
+
+</section>
+ </chapter>
+
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.doc_analyzer.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.jcasgen.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.jcasgen.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.jcasgen.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.jcasgen.xml Thu Aug 28 14:28:14 2008
@@ -1,181 +1,181 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY imgroot "../images/tools/tools.jcasgen/" >
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
-%uimaents;
-]>
-<!--
-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.
--->
-<chapter id="ugr.tools.jcasgen">
- <title>JCasGen User's Guide</title>
-
- <para>JCasGen reads a descriptor for an application (either an Analysis Engine Descriptor,
- or a Type System Descriptor), creates the merged type system
- specification by merging all the type system information from all the components
- referred to in the descriptor, and then uses this merged type system to create Java source
- files for classes that enable JCas access to the CAS. Java classes are not produced for the
- built-in types, since these classes are already provided by the UIMA SDK. (An exception is
- the built-in type <literal>uima.tcas.DocumentAnnotation</literal>, see the warning below.) </para>
-
- <warning><para>If the components comprising the input to the type merging process
- have different definitions for the same type name,
- JCasGen will show a warning, and in some environments may offer to abort the operation.
- If you continue past this warning,
- JCasGen will produce correct Java source files representing the merged types
- (that is, the
- type definition containing all of the features defined on that type by all of the
- components). It is recommended that you do not use this capability (of having
- two different definitions for the same type name, with different feature sets) since it can make it
- difficult to combine/package your annotator with others. See <olink
- targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.jcas.merging_types_from_other_specs"/> for more information.
- </para>
-
- <para>Also note that if your type system declares a custom version of the
- <literal>uima.tcas.DocumentAnnotation</literal>
- built-in type, then JCasGen will generate a Java source file for it. If you do this, you need to be
- aware of the issues discussed in
- <olink
- targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.jcas.documentannotation_issues"/>.</para></warning>
-
- <para>There are several versions of JCasGen. The basic version reads an XML descriptor
- which contains a type system descriptor, and generates the corresponding Java Class
- Models for those types. Variants exist for the Eclipse environment that allow merging the
- newly generated Java source code with previously augmented versions; see <olink
- targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.jcas.augmenting_generated_code"/> for a discussion of how the
- Java Class Models can be augmented by adding additional methods and fields.</para>
-
- <para>Input to JCasGen needs to be mostly self-contained. In particular, any types that are
- defined to depend on user-defined supertypes must have that supertype defined, if the
- supertype is <literal>uima.tcas.Annotation </literal>or a subtype of it. Any features
- referencing ranges which are subtypes of uima.cas.String must have those subtypes
- included. If this is not followed, a warning message is given stating that the resulting
- generation may be inaccurate.</para>
-
- <para>JCasGen is typically invoked automatically when using the Component Descriptor
- Editor (see <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.cde.auto_jcasgen"/>), but can also be run using a shell
- script. These scripts can take 0, 1, or 2 arguments. The first argument is the location of
- the file containing the input XML descriptor. The second argument specifies where the
- generated Java source code should go. If it isn't given, JCasGen generates its
- output into a subfolder called JCas (or sometimes JCasNew – see below), of the first
- argument's path.</para>
-
- <para>If no arguments are given to JCasGen, then it launches a GUI to interact with the user
- and ask for the same input. The GUI will remember the arguments you previously used.
- Here's what it looks like:
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>JCasGen tool showing fields for input arguments</phrase>
- </textobject>
- </mediaobject>
- </screenshot></para>
-
- <para>When running with automatic merging of the generated Java source with previously
- augmented versions, the output location is where the merge function obtains the source
- for the merge operation.</para>
-
- <para>As is customary for Java, the generated class source files are placed in the
- appropriate subdirectory structure according to Java conventions that correspond to
- the package (name space) name.</para>
-
- <para>The Java classes must be compiled and the resulting class files included in the class
- path of your application; you make these classes available for other annotator writers
- using your types, perhaps packaged as an xxx.jar file. If the xxx.jar file is made to
- contain only the Java Class Models for the CAS types, it can be reused by any users of these
- types.</para>
-
- <section id="ugr.tools.jcasgen.running_without_eclipse">
- <title>Running stand-alone without Eclipse</title>
-
- <para>There is no capability to automatically merge the generated Java source with
- previous versions, unless running with Eclipse. If run without Eclipse, no automatic
- merging of the generated Java source is done with any previous versions. In this case,
- the output is put in a folder called <quote>JCasNew</quote> unless overridden by
- specifying a second argument.</para>
-
- <para>The distribution includes a shell script/bat file to run the stand-alone version,
- called jcasgen.</para>
-
- </section>
-
- <section id="ugr.tools.jcasgen.running_standalone_with_eclipse">
- <title>Running stand-alone with Eclipse</title>
-
- <para>If you have Eclipse and EMF (EMF = Eclipse Modeling Framework; both of these are
- available from <ulink url="http://www.eclipse.org"/>) installed (version 3 or
- later) JCasGen can merge the Java code it generates with previous versions, picking up
- changes you might have inserted by hand. The output (and source of the merge input) is in a
- folder <quote>JCas</quote> under the same path as the input XML file, unless
- overridden by specifying a second argument.</para>
-
- <para>You must install the UIMA plug-ins into Eclipse to enable this function.</para>
-
- <para>The distribution includes a shell script/bat file to run the stand-alone with
- Eclipse version, called jcasgen_merge. This works by starting Eclipse in
- <quote>headless</quote> mode (no GUI) and invoking JCasGen within Eclipse. You will
- need to set the ECLIPSE_HOME environment variable or modify the jcasgen_merge shell
- script to specify where to find Eclipse. The version of Eclipse needed is 3 or higher,
- with the EMF plug-in and the UIMA runtime plug-in installed. A temporary workspace is
- used; the name/location of this is customizable in the shell script.</para>
-
- <para>Log and error messages are written to the UIMA log. This file is called uima.log, and
- is located in the default working directory, which if not overridden, is the startup
- directory of Eclipse.</para>
-
- </section>
-
- <section id="ugr.tools.jcasgen.running_within_eclipse">
- <title>Running within Eclipse</title>
-
- <para>There are two ways to run JCasGen within Eclipse. The first way is to configure an
- Eclipse external tools launcher, and use it to run the stand-alone shell scripts, with
- the arguments filled in. Here's a picture of a typical launcher configuration
- screen (you get here by navigating from the top menu: Run –> External Tools
- –> External tools...).
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image004.jpg"/>
- </imageobject>
- <textobject><phrase>Running JCasGen within Eclipse using the external tool launcher</phrase>
- </textobject>
- </mediaobject>
- </screenshot></para>
-
- <para>The second way (which is the normal way it's done) to run within Eclipse is to use the
- Component Descriptor Editor (CDE) (see <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.cde"/>). This tool can be configured to automatically
- launch JCasGen whenever the type system descriptor is modified. In this release, this
- operation completely regenerates the files, even if just a small thing changed. For
- very large type systems, you probably don't want to enable this all the time. The
- configurator tool has an option to enable/disable this function.</para>
- </section>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY imgroot "../images/tools/tools.jcasgen/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
+%uimaents;
+]>
+<!--
+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.
+-->
+<chapter id="ugr.tools.jcasgen">
+ <title>JCasGen User's Guide</title>
+
+ <para>JCasGen reads a descriptor for an application (either an Analysis Engine Descriptor,
+ or a Type System Descriptor), creates the merged type system
+ specification by merging all the type system information from all the components
+ referred to in the descriptor, and then uses this merged type system to create Java source
+ files for classes that enable JCas access to the CAS. Java classes are not produced for the
+ built-in types, since these classes are already provided by the UIMA SDK. (An exception is
+ the built-in type <literal>uima.tcas.DocumentAnnotation</literal>, see the warning below.) </para>
+
+ <warning><para>If the components comprising the input to the type merging process
+ have different definitions for the same type name,
+ JCasGen will show a warning, and in some environments may offer to abort the operation.
+ If you continue past this warning,
+ JCasGen will produce correct Java source files representing the merged types
+ (that is, the
+ type definition containing all of the features defined on that type by all of the
+ components). It is recommended that you do not use this capability (of having
+ two different definitions for the same type name, with different feature sets) since it can make it
+ difficult to combine/package your annotator with others. See <olink
+ targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.jcas.merging_types_from_other_specs"/> for more information.
+ </para>
+
+ <para>Also note that if your type system declares a custom version of the
+ <literal>uima.tcas.DocumentAnnotation</literal>
+ built-in type, then JCasGen will generate a Java source file for it. If you do this, you need to be
+ aware of the issues discussed in
+ <olink
+ targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.jcas.documentannotation_issues"/>.</para></warning>
+
+ <para>There are several versions of JCasGen. The basic version reads an XML descriptor
+ which contains a type system descriptor, and generates the corresponding Java Class
+ Models for those types. Variants exist for the Eclipse environment that allow merging the
+ newly generated Java source code with previously augmented versions; see <olink
+ targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.jcas.augmenting_generated_code"/> for a discussion of how the
+ Java Class Models can be augmented by adding additional methods and fields.</para>
+
+ <para>Input to JCasGen needs to be mostly self-contained. In particular, any types that are
+ defined to depend on user-defined supertypes must have that supertype defined, if the
+ supertype is <literal>uima.tcas.Annotation </literal>or a subtype of it. Any features
+ referencing ranges which are subtypes of uima.cas.String must have those subtypes
+ included. If this is not followed, a warning message is given stating that the resulting
+ generation may be inaccurate.</para>
+
+ <para>JCasGen is typically invoked automatically when using the Component Descriptor
+ Editor (see <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.cde.auto_jcasgen"/>), but can also be run using a shell
+ script. These scripts can take 0, 1, or 2 arguments. The first argument is the location of
+ the file containing the input XML descriptor. The second argument specifies where the
+ generated Java source code should go. If it isn't given, JCasGen generates its
+ output into a subfolder called JCas (or sometimes JCasNew – see below), of the first
+ argument's path.</para>
+
+ <para>If no arguments are given to JCasGen, then it launches a GUI to interact with the user
+ and ask for the same input. The GUI will remember the arguments you previously used.
+ Here's what it looks like:
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
+ </imageobject>
+ <textobject><phrase>JCasGen tool showing fields for input arguments</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+
+ <para>When running with automatic merging of the generated Java source with previously
+ augmented versions, the output location is where the merge function obtains the source
+ for the merge operation.</para>
+
+ <para>As is customary for Java, the generated class source files are placed in the
+ appropriate subdirectory structure according to Java conventions that correspond to
+ the package (name space) name.</para>
+
+ <para>The Java classes must be compiled and the resulting class files included in the class
+ path of your application; you make these classes available for other annotator writers
+ using your types, perhaps packaged as an xxx.jar file. If the xxx.jar file is made to
+ contain only the Java Class Models for the CAS types, it can be reused by any users of these
+ types.</para>
+
+ <section id="ugr.tools.jcasgen.running_without_eclipse">
+ <title>Running stand-alone without Eclipse</title>
+
+ <para>There is no capability to automatically merge the generated Java source with
+ previous versions, unless running with Eclipse. If run without Eclipse, no automatic
+ merging of the generated Java source is done with any previous versions. In this case,
+ the output is put in a folder called <quote>JCasNew</quote> unless overridden by
+ specifying a second argument.</para>
+
+ <para>The distribution includes a shell script/bat file to run the stand-alone version,
+ called jcasgen.</para>
+
+ </section>
+
+ <section id="ugr.tools.jcasgen.running_standalone_with_eclipse">
+ <title>Running stand-alone with Eclipse</title>
+
+ <para>If you have Eclipse and EMF (EMF = Eclipse Modeling Framework; both of these are
+ available from <ulink url="http://www.eclipse.org"/>) installed (version 3 or
+ later) JCasGen can merge the Java code it generates with previous versions, picking up
+ changes you might have inserted by hand. The output (and source of the merge input) is in a
+ folder <quote>JCas</quote> under the same path as the input XML file, unless
+ overridden by specifying a second argument.</para>
+
+ <para>You must install the UIMA plug-ins into Eclipse to enable this function.</para>
+
+ <para>The distribution includes a shell script/bat file to run the stand-alone with
+ Eclipse version, called jcasgen_merge. This works by starting Eclipse in
+ <quote>headless</quote> mode (no GUI) and invoking JCasGen within Eclipse. You will
+ need to set the ECLIPSE_HOME environment variable or modify the jcasgen_merge shell
+ script to specify where to find Eclipse. The version of Eclipse needed is 3 or higher,
+ with the EMF plug-in and the UIMA runtime plug-in installed. A temporary workspace is
+ used; the name/location of this is customizable in the shell script.</para>
+
+ <para>Log and error messages are written to the UIMA log. This file is called uima.log, and
+ is located in the default working directory, which if not overridden, is the startup
+ directory of Eclipse.</para>
+
+ </section>
+
+ <section id="ugr.tools.jcasgen.running_within_eclipse">
+ <title>Running within Eclipse</title>
+
+ <para>There are two ways to run JCasGen within Eclipse. The first way is to configure an
+ Eclipse external tools launcher, and use it to run the stand-alone shell scripts, with
+ the arguments filled in. Here's a picture of a typical launcher configuration
+ screen (you get here by navigating from the top menu: Run –> External Tools
+ –> External tools...).
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image004.jpg"/>
+ </imageobject>
+ <textobject><phrase>Running JCasGen within Eclipse using the external tool launcher</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+
+ <para>The second way (which is the normal way it's done) to run within Eclipse is to use the
+ Component Descriptor Editor (CDE) (see <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.cde"/>). This tool can be configured to automatically
+ launch JCasGen whenever the type system descriptor is modified. In this release, this
+ operation completely regenerates the files, even if just a small thing changed. For
+ very large type systems, you probably don't want to enable this all the time. The
+ configurator tool has an option to enable/disable this function.</para>
+ </section>
+
</chapter>
\ No newline at end of file
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.jcasgen.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.installer.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.installer.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.installer.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.installer.xml Thu Aug 28 14:28:14 2008
@@ -1,91 +1,91 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY imgroot "../images/tools/tools.pear.installer/" >
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
-%uimaents;
-]>
-<!--
-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.
--->
-<chapter id="ugr.tools.pear.installer">
- <title>PEAR Installer User's Guide</title>
-
- <para>PEAR (Processing Engine ARchive) is a new standard for packaging UIMA compliant
- components. This standard defines several service elements that should be included in
- the archive package to enable automated installation of the encapsulated UIMA
- component. The major PEAR service element is an XML Installation Descriptor that
- specifies installation platform, component attributes, custom installation
- procedures and environment variables. </para>
-
- <para>The installation of a UIMA compliant component includes 2 steps: (1) installation of
- the component code and resources in a local file system, and (2) verification of the
- serviceability of the installed component. Installation of the component code and
- resources involves extracting component files from the archive (PEAR) package in a
- designated directory and localizing file references in component descriptors and other
- configuration files. Verification of the component serviceability is accomplished
- with the help of standard UIMA mechanisms for instantiating analysis engines.
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>PEAR Installer GUI</phrase>
- </textobject>
- </mediaobject>
- </screenshot></para>
-
- <para>PEAR Installer is a simple GUI based Java application that helps installing UIMA
- compliant components (analysis engines) from PEAR packages in a local file system. To
- install a desired UIMA component the user needs to select the appropriate PEAR file in a
- local file system and specify the installation directory (optional). If no installation
- directory is specified, the PEAR file is installed to the current working directory.
- By default the PEAR packages are not installed directly to the specified installation directory.
- For each PEAR a subdirectory with the name of the PEAR's ID is created where the PEAR package is
- installed to. If the PEAR installation directory already exists, the old content is automatically
- deleted before the new content is installed. During the
- component installation the user can read messages printed by the installation program in
- the message area of the application window. If the installation fails, appropriate error
- message is printed to help identifying and fixing the problem.</para>
-
- <para>After the desired UIMA component is successfully installed, the PEAR Installer
- allows testing this component in the CAS Visual Debugger (CVD) application, which is
- provided with the UIMA package. The CVD application will load your UIMA component using
- its XML descriptor file. If the component is loaded successfully, you'll be able to
- run it either with sample documents provided in the
- <literal><UIMA_HOME>/examples/data</literal> directory, or with any other
- sample documents. See <olink targetdoc="&uima_docs_tools;"
- targetptr="ugr.tools.cvd"/> for more information about the CVD application.
- Running your component in the CVD application helps to make sure the component will run in
- other UIMA applications. If the CVD application fails to load or run your component, or
- throws an exception, you can find more information about the problem in the uima.log file
- in the current working directory. The log file can be viewed with the CVD.</para>
-
- <para>PEAR Installer creates a file named <literal>setenv.txt</literal> in the
- <literal><component_root>/metadata</literal> directory. This file contains
- environment variables required to run your component in any UIMA application.
- It also creates a PEAR descriptor (see also <olink targetdoc="&uima_docs_ref;"
- targetptr="ugr.ref.pear.specifier"/>)
- file named <literal><componentID>_pear.xml</literal>
- in the <literal><component_root></literal> directory that can be used to directly run
- the installed pear file in your application.
- </para>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY imgroot "../images/tools/tools.pear.installer/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
+%uimaents;
+]>
+<!--
+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.
+-->
+<chapter id="ugr.tools.pear.installer">
+ <title>PEAR Installer User's Guide</title>
+
+ <para>PEAR (Processing Engine ARchive) is a new standard for packaging UIMA compliant
+ components. This standard defines several service elements that should be included in
+ the archive package to enable automated installation of the encapsulated UIMA
+ component. The major PEAR service element is an XML Installation Descriptor that
+ specifies installation platform, component attributes, custom installation
+ procedures and environment variables. </para>
+
+ <para>The installation of a UIMA compliant component includes 2 steps: (1) installation of
+ the component code and resources in a local file system, and (2) verification of the
+ serviceability of the installed component. Installation of the component code and
+ resources involves extracting component files from the archive (PEAR) package in a
+ designated directory and localizing file references in component descriptors and other
+ configuration files. Verification of the component serviceability is accomplished
+ with the help of standard UIMA mechanisms for instantiating analysis engines.
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
+ </imageobject>
+ <textobject><phrase>PEAR Installer GUI</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+
+ <para>PEAR Installer is a simple GUI based Java application that helps installing UIMA
+ compliant components (analysis engines) from PEAR packages in a local file system. To
+ install a desired UIMA component the user needs to select the appropriate PEAR file in a
+ local file system and specify the installation directory (optional). If no installation
+ directory is specified, the PEAR file is installed to the current working directory.
+ By default the PEAR packages are not installed directly to the specified installation directory.
+ For each PEAR a subdirectory with the name of the PEAR's ID is created where the PEAR package is
+ installed to. If the PEAR installation directory already exists, the old content is automatically
+ deleted before the new content is installed. During the
+ component installation the user can read messages printed by the installation program in
+ the message area of the application window. If the installation fails, appropriate error
+ message is printed to help identifying and fixing the problem.</para>
+
+ <para>After the desired UIMA component is successfully installed, the PEAR Installer
+ allows testing this component in the CAS Visual Debugger (CVD) application, which is
+ provided with the UIMA package. The CVD application will load your UIMA component using
+ its XML descriptor file. If the component is loaded successfully, you'll be able to
+ run it either with sample documents provided in the
+ <literal><UIMA_HOME>/examples/data</literal> directory, or with any other
+ sample documents. See <olink targetdoc="&uima_docs_tools;"
+ targetptr="ugr.tools.cvd"/> for more information about the CVD application.
+ Running your component in the CVD application helps to make sure the component will run in
+ other UIMA applications. If the CVD application fails to load or run your component, or
+ throws an exception, you can find more information about the problem in the uima.log file
+ in the current working directory. The log file can be viewed with the CVD.</para>
+
+ <para>PEAR Installer creates a file named <literal>setenv.txt</literal> in the
+ <literal><component_root>/metadata</literal> directory. This file contains
+ environment variables required to run your component in any UIMA application.
+ It also creates a PEAR descriptor (see also <olink targetdoc="&uima_docs_ref;"
+ targetptr="ugr.ref.pear.specifier"/>)
+ file named <literal><componentID>_pear.xml</literal>
+ in the <literal><component_root></literal> directory that can be used to directly run
+ the installed pear file in your application.
+ </para>
+
</chapter>
\ No newline at end of file
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.installer.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.merger.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.merger.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.merger.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.merger.xml Thu Aug 28 14:28:14 2008
@@ -1,164 +1,164 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
-%uimaents;
-]>
-<!--
-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.
--->
-<chapter id="ugr.tools.pear.merger">
- <title>PEAR Merger User's Guide</title>
-
- <para>The PEAR Merger utility takes two or more PEAR files and merges their contents,
- creating a new PEAR which has, in turn, a new Aggregate analysis engine whose delegates are
- the components from the original files being merged. It does this by (1) copying the
- contents of the input components into the output component, placing each component into a
- separate subdirectory, (2) generating a UIMA descriptor for the output Aggregate
- analysis engine and (3) creating an output PEAR file that encapsulates the output
- Aggregate.</para>
-
- <para>The merge logic is quite simple, and is intended to work for simple cases. More complex
- merging needs to be done by hand. Please see the Restrictions and Limitations section,
- below.</para>
-
- <para>To run the PearMerger command line utility you can use the runPearMerger scripts (.bat for Windows, and .sh for
- Unix). The usage of the tooling is shown below:</para>
-
- <para><programlisting>runPearMerger 1st_input_pear_file ... nth_input_pear_file
- -n output_analysis_engine_name [-f output_pear_file ]</programlisting></para>
-
- <para>The first group of parameters are the input PEAR files. No duplicates are allowed
- here. The <literal>-n</literal> parameter is the name of the generated Aggregate
- Analysis Engine. The optional <literal>-f</literal> parameter specifies the name of
- the output file. If it is omitted, the output is written to
- <literal>output_analysis_engine_name.pear</literal> in the current working directory.</para>
-
- <para>During the running of this tool, work files are written to a temporary directory
- created in the user's home directory.</para>
-
- <section id="ugr.tools.pear.merger.merge_details">
- <title>Details of the merging process</title>
-
- <para>The PEARs are merged using the following steps:</para>
-
- <orderedlist><listitem><para>A temporary working directory, is created for the
- output aggregate component.</para></listitem>
-
- <listitem><para>Each input PEAR file is extracted into a separate
- 'input_component_name' folder under the working directory.</para>
- </listitem>
-
- <listitem><para>The extracted files are processed to adjust the
- '$main_root' macros. This operation differs from the PEAR installation
- operation, because it does not replace the macros with absolute paths.</para>
- </listitem>
-
- <listitem><para>The output PEAR directory structure, 'metadata' and
- 'desc' folders under the working directory, are created.</para>
- </listitem>
-
- <listitem><para>The UIMA AE descriptor for the output aggregate component is built
- in the 'desc' folder. This aggregate descriptor refers to the input
- delegate components, specifying 'fixed flow' based on the original
- order of the input components in the command line. The aggregate descriptor's
- 'capabilities' and
- 'operational properties' sections are built based on the input
- components' specifications.</para></listitem>
-
- <listitem><para>A new PEAR installation descriptor is created in the
- 'metadata' folder, referencing the new output aggregate descriptor
- built in the previous step. </para></listitem>
-
- <listitem><para>The content of the temporary output working directory is zipped to
- created the output PEAR, and then the temporary working directory is deleted.
- </para></listitem></orderedlist>
-
- <para>The PEAR merger utility logs all the operations both to standard console output and
- to a log file, pm.log, which is created in the current working directory.</para>
-
- </section>
-
- <section id="ugr.tools.pear.merger.testing_modifying_resulting_pear">
- <title>Testing and Modifying the resulting PEAR</title>
-
- <para>The output PEAR file can be installed and tested using the PEAR Installer. The
- output aggregate component can also be tested by using the CVD or DocAnalyzer
- tools.</para>
-
- <para>The PEAR Installer creates Eclipse project files (.classpath and .project) in the
- root directory of the installer PEAR, so the installed component can be imported into
- the Eclipse IDE as an external project. Once the component is in the Eclipse IDE,
- developers may use the Component Descriptor Editor and the PEAR Packager to modify the
- output aggregate descriptor and re-package the component.</para>
-
- </section>
- <section id="ugr.tools.pear.merger.restrictions_limitations">
- <title>Restrictions and Limitations</title>
-
- <para>The PEAR Merger utility only does basic merging operations, and is limited as
- follows. You can overcome these by editing the resulting PEAR file or the resulting
- Aggregate Descriptor.</para>
-
- <orderedlist><listitem><para>The Merge operation specifies Fixed Flow sequencing
- for the Aggregate.</para></listitem>
-
- <listitem><para>The merged aggregate does not define any parameters, so the delegate
- parameters cannot be overridden.</para></listitem>
-
- <listitem><para>No External Resource definitions are generated for the
- aggregate.</para></listitem>
-
- <listitem><para>No Sofa Mappings are generated for the aggregate.</para>
- </listitem>
-
- <listitem><para>Name collisions are not checked for. Possible name collisions could
- occur in the fully-qualified class names of the implementing Java classes, the names
- of JAR files, the names of descriptor files, and the names of resource bindings or
- resource file paths.</para></listitem>
-
- <listitem><para>The input and output capabilities are generated based on merging the
- capabilities from the components (removing duplicates). Capability sets are
- ignored - only the first of the set is used in this process, and only one set is created
- for the generated Aggregate. There is no support for merging Sofa
- specifications.</para></listitem>
-
- <listitem><para>No Indexes or Type Priorities are created for the generated
- Aggregate. No checking is done to see if the Indexes or Type Priorities of the
- components conflict or are inconsistent.</para></listitem>
-
- <listitem><para>You can only merge Analysis Engines and CAS Consumers. </para>
- </listitem>
-
- <listitem><para>Although PEAR file installation descriptors that are being merged
- can have specific XML elements describing Collection Reader and CAS Consumer
- descriptors, these elements are ignored during the merge, in the sense that the
- installation descriptor that is created by the merge does not set these elements. The
- merge process does not use these elements; the output PEAR's new aggregate only
- references the merged components' main PEAR descriptor element, as
- identified by the PEAR element:
-
- <programlisting><![CDATA[<SUBMITTED_COMPONENT>
- <DESC>the_component.xml</DESC>...
-</SUBMITTED_COMPONENT>
-]]></programlisting></para>
- </listitem></orderedlist>
-
- </section>
-
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
+%uimaents;
+]>
+<!--
+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.
+-->
+<chapter id="ugr.tools.pear.merger">
+ <title>PEAR Merger User's Guide</title>
+
+ <para>The PEAR Merger utility takes two or more PEAR files and merges their contents,
+ creating a new PEAR which has, in turn, a new Aggregate analysis engine whose delegates are
+ the components from the original files being merged. It does this by (1) copying the
+ contents of the input components into the output component, placing each component into a
+ separate subdirectory, (2) generating a UIMA descriptor for the output Aggregate
+ analysis engine and (3) creating an output PEAR file that encapsulates the output
+ Aggregate.</para>
+
+ <para>The merge logic is quite simple, and is intended to work for simple cases. More complex
+ merging needs to be done by hand. Please see the Restrictions and Limitations section,
+ below.</para>
+
+ <para>To run the PearMerger command line utility you can use the runPearMerger scripts (.bat for Windows, and .sh for
+ Unix). The usage of the tooling is shown below:</para>
+
+ <para><programlisting>runPearMerger 1st_input_pear_file ... nth_input_pear_file
+ -n output_analysis_engine_name [-f output_pear_file ]</programlisting></para>
+
+ <para>The first group of parameters are the input PEAR files. No duplicates are allowed
+ here. The <literal>-n</literal> parameter is the name of the generated Aggregate
+ Analysis Engine. The optional <literal>-f</literal> parameter specifies the name of
+ the output file. If it is omitted, the output is written to
+ <literal>output_analysis_engine_name.pear</literal> in the current working directory.</para>
+
+ <para>During the running of this tool, work files are written to a temporary directory
+ created in the user's home directory.</para>
+
+ <section id="ugr.tools.pear.merger.merge_details">
+ <title>Details of the merging process</title>
+
+ <para>The PEARs are merged using the following steps:</para>
+
+ <orderedlist><listitem><para>A temporary working directory, is created for the
+ output aggregate component.</para></listitem>
+
+ <listitem><para>Each input PEAR file is extracted into a separate
+ 'input_component_name' folder under the working directory.</para>
+ </listitem>
+
+ <listitem><para>The extracted files are processed to adjust the
+ '$main_root' macros. This operation differs from the PEAR installation
+ operation, because it does not replace the macros with absolute paths.</para>
+ </listitem>
+
+ <listitem><para>The output PEAR directory structure, 'metadata' and
+ 'desc' folders under the working directory, are created.</para>
+ </listitem>
+
+ <listitem><para>The UIMA AE descriptor for the output aggregate component is built
+ in the 'desc' folder. This aggregate descriptor refers to the input
+ delegate components, specifying 'fixed flow' based on the original
+ order of the input components in the command line. The aggregate descriptor's
+ 'capabilities' and
+ 'operational properties' sections are built based on the input
+ components' specifications.</para></listitem>
+
+ <listitem><para>A new PEAR installation descriptor is created in the
+ 'metadata' folder, referencing the new output aggregate descriptor
+ built in the previous step. </para></listitem>
+
+ <listitem><para>The content of the temporary output working directory is zipped to
+ created the output PEAR, and then the temporary working directory is deleted.
+ </para></listitem></orderedlist>
+
+ <para>The PEAR merger utility logs all the operations both to standard console output and
+ to a log file, pm.log, which is created in the current working directory.</para>
+
+ </section>
+
+ <section id="ugr.tools.pear.merger.testing_modifying_resulting_pear">
+ <title>Testing and Modifying the resulting PEAR</title>
+
+ <para>The output PEAR file can be installed and tested using the PEAR Installer. The
+ output aggregate component can also be tested by using the CVD or DocAnalyzer
+ tools.</para>
+
+ <para>The PEAR Installer creates Eclipse project files (.classpath and .project) in the
+ root directory of the installer PEAR, so the installed component can be imported into
+ the Eclipse IDE as an external project. Once the component is in the Eclipse IDE,
+ developers may use the Component Descriptor Editor and the PEAR Packager to modify the
+ output aggregate descriptor and re-package the component.</para>
+
+ </section>
+ <section id="ugr.tools.pear.merger.restrictions_limitations">
+ <title>Restrictions and Limitations</title>
+
+ <para>The PEAR Merger utility only does basic merging operations, and is limited as
+ follows. You can overcome these by editing the resulting PEAR file or the resulting
+ Aggregate Descriptor.</para>
+
+ <orderedlist><listitem><para>The Merge operation specifies Fixed Flow sequencing
+ for the Aggregate.</para></listitem>
+
+ <listitem><para>The merged aggregate does not define any parameters, so the delegate
+ parameters cannot be overridden.</para></listitem>
+
+ <listitem><para>No External Resource definitions are generated for the
+ aggregate.</para></listitem>
+
+ <listitem><para>No Sofa Mappings are generated for the aggregate.</para>
+ </listitem>
+
+ <listitem><para>Name collisions are not checked for. Possible name collisions could
+ occur in the fully-qualified class names of the implementing Java classes, the names
+ of JAR files, the names of descriptor files, and the names of resource bindings or
+ resource file paths.</para></listitem>
+
+ <listitem><para>The input and output capabilities are generated based on merging the
+ capabilities from the components (removing duplicates). Capability sets are
+ ignored - only the first of the set is used in this process, and only one set is created
+ for the generated Aggregate. There is no support for merging Sofa
+ specifications.</para></listitem>
+
+ <listitem><para>No Indexes or Type Priorities are created for the generated
+ Aggregate. No checking is done to see if the Indexes or Type Priorities of the
+ components conflict or are inconsistent.</para></listitem>
+
+ <listitem><para>You can only merge Analysis Engines and CAS Consumers. </para>
+ </listitem>
+
+ <listitem><para>Although PEAR file installation descriptors that are being merged
+ can have specific XML elements describing Collection Reader and CAS Consumer
+ descriptors, these elements are ignored during the merge, in the sense that the
+ installation descriptor that is created by the merge does not set these elements. The
+ merge process does not use these elements; the output PEAR's new aggregate only
+ references the merged components' main PEAR descriptor element, as
+ identified by the PEAR element:
+
+ <programlisting><![CDATA[<SUBMITTED_COMPONENT>
+ <DESC>the_component.xml</DESC>...
+</SUBMITTED_COMPONENT>
+]]></programlisting></para>
+ </listitem></orderedlist>
+
+ </section>
+
+</chapter>
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.merger.xml
------------------------------------------------------------------------------
svn:eol-style = native