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 2006/12/05 21:39:52 UTC
svn commit: r482771 [4/9] - in /incubator/uima/uimaj/trunk/uima-docbooks: ./
src/docbook/ src/docbook/overview_and_setup/ src/docbook/references/
src/docbook/references/images/ref.cas/
src/docbook/references/images/ref.pear/ src/docbook/references/imag...
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cpe.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cpe.xml?view=diff&rev=482771&r1=482770&r2=482771
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cpe.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cpe.xml Tue Dec 5 12:39:49 2006
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/annotator_analysis_engine_files/" >
-<!ENTITY % uimaents SYSTEM "entities.ent" >
+<!ENTITY imgroot "../images/tools/tools.cpe/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
<!--
@@ -23,198 +23,182 @@
specific language governing permissions and limitations
under the License.
-->
-<chapter id="ugr.tool.cpe">
- <title></title>
- <section name="Collection Processing Engine Configurator User's Guide"><a id="_crossRef152"> </a>
-
-
-
-<para><a id="_crossRef153">A <emphasis>Collection Processing Engine
-(CPE)</emphasis> processes collections of artifacts (documents) through the
-combination of the following components: a Collection Reader, an optional CAS
-Initializer, Analysis Engines, and CAS Consumers. </a></para>
-
-<para>The <emphasis>Collection
-Processing Engine Configurator(CPE Configurator)</emphasis> is a graphical tool that
-allows you to assemble and run CPEs.</para>
-
-<para>For an
-introduction to Collection Processing Engine concepts, including developing the
-components that make up a CPE, read <a class="crossrefText" href="CPE_Developers_Guide.htm#_crossRef183">Chapter 5, <b>Collection Processing
-Engine Developer's Guide</b></a>. This chapter is a user's guide for using the CPE Configurator tool, and
-does not describe UIMA's Collection Processing Architecture itself.</para>
-
-
-
-<subsection name="Limitations of the CPE Configurator"><a id="_crossRef154"> </a>
-
-
-
-<para>The CPE Configurator only supports basic CPE
-configurations.</para>
-
-<para>It only supports <quote>Integrated</quote>
-deployments (although it will connect to remotes if particular CAS Processors
-are specified with remote service descriptors). It doesn't support configuration of the
-error handling. It doesn't support Sofa
-Mappings; it assumes all Single-View components are operating with the
-_InitialView Sofa. Multi-View components
-will not have their names mapped. It sets up a fixed-sized CAS Pool.</para>
-
-<para>For running arbitrary CPE descriptors, or
-running with other than the default configuration supplied by the CPE
-Configurator, you can write your own application, or use the runCPE script,
-which invokes an example application, SimpleRunCPE.</para>
-
-
-
-
- </subsection>
-<subsection name="Starting the CPE Configurator"><a id="_crossRef155"> </a>
-
-
-
-<para>The CPE Configurator tool can be run using the <literal>cpeGui</literal> shell script, which is located in the <literal>bin</literal> directory of the UIMA SDK. If you've installed the example Eclipse
-project (see <a class="crossrefText" href="UIMA_SDK_Installation_and_Setup.htm#_crossRef372">Chapter 3, <b>UIMA SDK Setup for
-Eclipse</b></a>), you can also run it using the
-<quote>UIMA CPE GUI</quote> run configuration provided in that project.</para>
-
-<para>Note that if you are planning to build a CPE using
-components other than the examples included in the UIMA SDK, you will first
-need to update your CLASSPATH environment variable to include the classes
-needed by these components.</para>
-
-<para>When you first start the CPE Configurator, you will see
-the main window shown here:</para>
-
-<para><img alt="" width="542" height="412"
-src="../UIMA_SDK_Guide_Ref/CPE_Configurator_Users_Manual_files/image002.jpg"/></para>
-
-
-
-
-
-
- </subsection>
-<subsection name="Selecting Component Descriptors"><a id="_crossRef156"> </a>
-
-
-
-<para>The CPE Configurator's main window is divided into 4
-sections: one for each of the types of components that constitute a CPE:
-CollectionReader, CAS Initializer, Analysis Engines, and CasConsumers. Each CPE has exactly one CollectionReader, an
-optional CAS Initializer, and at least one each of Analysis Engines and CAS
-Consumers.</para>
-
-<para>In each section of the CPE Configurator, you can select
-the component(s) you want to use by browsing to (or typing the location of)
-their XML descriptors. You must select a
-Collection Reader, at least one Analysis Engine, and at least one CAS
-Consumer. You may or may not need to
-select a CAS Initializer; this depends on the particular Collection Reader that
-you are using.</para>
-
-<para>When you select a descriptor, the configuration parameters
-that are defined in that descriptor will then be displayed in the GUI; these
-can be modified to override the values present in the descriptor.</para>
-
-<para>For example, the screen shot below shows the CPE Configurator
-after the following components have been chosen:</para>
-
-<programlisting>docs/examples/descriptors/collectionReader/FileSystemCollectionReader.xml
-docs/examples/descriptors/analysis_engine/NamesAndPersonTitles_TAE.xml
-docs/examples/descriptors/cas_consumer/XCasWriterCasConsumer.xml</programlisting>
-
-<para><img alt="" width="576" height="439"
-src="../UIMA_SDK_Guide_Ref/CPE_Configurator_Users_Manual_files/image004.jpg"/></para>
-
-
-
-
- </subsection>
-<subsection name="Running a Collection Processing Engine"><a id="_crossRef157"> </a>
-
-
-
-<para>After selecting each of the components and providing
-configuration settings, click the play (forward arrow) button at the bottom of
-the screen to begin processing. A
-progress bar should be displayed in the lower left corner. (Note that the progress bar will not begin to
-move until all components have completed their initialization, which may take
-several seconds.) Once processing has
-begun, the pause and stop buttons become enabled.</para>
-
-<para>If an error occurs, you will be informed by an error
-dialog. If processing completes
-successfully, you will be presented with a performance report.</para>
-
-
-
-
- </subsection>
-<subsection name="The File Menu"><a id="_crossRef158"> </a>
-
-
-
-<para>The CPE Configurator's File Menu has six options:</para>
-
-<itemizedlist><listitem>Open CPE Descriptor</listitem>
-
-
-<listitem>Save CPE Descriptor</listitem>
-
-
-<listitem>Refresh Descriptors from File
-System</listitem>
-
-
-<listitem>Clear All</listitem>
-
-
-<listitem>Exit
-</listitem></itemizedlist>
-
-<para><b>Open CPE Descriptor</b> will allow you to select a CPE
-Descriptor file from disk, and will read in that CPE Descriptor and configure
-the GUI appropriately.</para>
-
-<para><b>Save CPE Descriptor</b> will create a CPE Descriptor
-file that defines the CPE you have constructed. This CPE Descriptor will
-identify the components that constitute the CPE, as well as the configuration
-settings you have specified for each of these components. Later, you can use <quote>Open CPE
-Descriptor</quote> to restore the CPE Configurator to the state. Also, CPE Descriptors can be used to easily
-run a CPE from a Java program – see <a class="crossrefText" href="Application_Developers_Guide.htm#_crossRef44">Chapter 6, <b>Application Developer's
-Guide</b></a>.</para>
-
-<para>CPE Descriptors also allow specifying operational
-parameters, such as error handling options that are not currently available for
-configuration through the CPE Configurator. For more information on manually creating a CPE Descriptor, see <a class="crossrefText" href="CPE_Descriptor_Reference.htm#_crossRef160">Chapter 24, <b>Collection Processing
-Engine Descriptor Reference</b></a>.</para>
-
-<para><b>Refresh Descriptors from File System</b> will reload
-all descriptors from disk. This is
-useful if you have made a change to the descriptor outside of the CPE
-Configurator, and want to refresh the display.</para>
-
-<para><b>Clear All</b> will reset the CPE Configurator to its
-initial state, with no components selected.</para>
-
-<para><b>Exit</b> will close the CPE Configurator. If you have unsaved changes, you will be
-prompted as to whether you would like to save them to a CPE Descriptor file. If you do not save them, they will be lost.</para>
-
-<para>When you restart the CPE Configurator, it will automatically
-reload the last CPE descriptor file that you were working with.</para>
-
-
-
-
- </subsection>
-<subsection name="The Help Menu"><a id="_crossRef159"> </a>
-
-
-
-<para>The CPE Configurator's Help menu provides
-<quote>About</quote> information and some very simple instructions on how to use
-the tool.</para>
-
+<chapter id="ugr.tools.cpe">
+ <title>Collection Processing Engine Configurator User's Guide</title>
+
+ <para>A <emphasis>Collection Processing Engine (CPE)</emphasis> processes
+ collections of artifacts (documents) through the combination of the following
+ components: a Collection Reader, Analysis Engines, and CAS Consumers.
+ <footnote><para>Earlier versions of UIMA supported another component, the CAS
+ Initializer, but this component is now deprecated in UIMA Version 2.</para></footnote>
+ </para>
+
+ <para>The <emphasis>Collection Processing Engine Configurator(CPE
+ Configurator)</emphasis> is a graphical tool that allows you to assemble and run
+ CPEs.</para>
+
+ <para>For an introduction to Collection Processing Engine concepts, including
+ developing the components that make up a CPE, read <olink
+ targetdoc="&uima_docs_tutorial_guides;" targetptr="ugr.tug.cpe"/>. This
+ chapter is a user's guide for using the CPE Configurator tool, and does not describe
+ UIMA's Collection Processing Architecture itself.</para>
+
+ <section id="ugr.tools.cpe.limitations">
+ <title>Limitations of the CPE Configurator</title>
+
+ <para>The CPE Configurator only supports basic CPE configurations.</para>
+
+ <para>It only supports <quote>Integrated</quote> deployments (although it will
+ connect to remotes if particular CAS Processors are specified with remote service
+ descriptors). It doesn't support configuration of the error handling. It
+ doesn't support Sofa Mappings; it assumes all Single-View components are
+ operating with the _InitialView Sofa. Multi-View components will not have their names
+ mapped. It sets up a fixed-sized CAS Pool.</para>
+
+ <para>For running arbitrary CPE descriptors, or running with other than the default
+ configuration supplied by the CPE Configurator, you can write your own application, or
+ use the runCPE script, which invokes an example application, SimpleRunCPE.</para>
+
+ </section>
+
+ <section id="ugr.tools.cpe.starting">
+ <title>Starting the CPE Configurator</title>
+
+ <para>The CPE Configurator tool can be run using the <literal>cpeGui</literal> shell
+ script, which is located in the <literal>bin</literal> directory of the UIMA SDK. If
+ you've installed the example Eclipse project (see <olink
+ targetdoc="&uima_docs_overview;"
+ targetptr="ugr.ovv.eclipse_setup.example_code"/>, you can also run it using the
+ <quote>UIMA CPE GUI</quote> run configuration provided in that project.</para>
+ <note><para>If you are planning to build a CPE using components other than the examples
+ included in the UIMA SDK, you will first need to update your CLASSPATH environment
+ variable to include the classes needed by these components.</para></note>
+
+ <para>When you first start the CPE Configurator, you will see the main window shown here:
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="542" depth="412" format="JPG" fileref="&imgroot;image002.jpg"/>
+ </imageobject>
+ <textobject><phrase>CPE Configurator main GUI window</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+ </section>
+
+ <section id="ugr.tools.cpe.selecting_component_descriptors">
+ <title>Selecting Component Descriptors</title>
+
+ <para>The CPE Configurator's main window is divided into 4 sections: one for each of
+ the types of components that constitute a CPE: CollectionReader, CAS Initializer,
+ Analysis Engines, and CasConsumers. Each CPE has exactly one CollectionReader, an
+ optional CAS Initializer, and at least one each of Analysis Engines and CAS
+ Consumers.</para>
+
+ <para>In each section of the CPE Configurator, you can select the component(s) you want to
+ use by browsing to (or typing the location of) their XML descriptors. You must select a
+ Collection Reader, at least one Analysis Engine, and at least one CAS Consumer. You may
+ or may not need to select a CAS Initializer; this depends on the particular Collection
+ Reader that you are using.</para>
+
+ <para>When you select a descriptor, the configuration parameters that are defined in
+ that descriptor will then be displayed in the GUI; these can be modified to override the
+ values present in the descriptor.</para>
+
+ <para>For example, the screen shot below shows the CPE Configurator after the following
+ components have been chosen:
+
+
+ <programlisting>examples/descriptors/collectionReader/FileSystemCollectionReader.xml
+examples/descriptors/analysis_engine/NamesAndPersonTitles_TAE.xml
+examples/descriptors/cas_consumer/XCasWriterCasConsumer.xml</programlisting></para>
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="576" depth="439" format="JPG" fileref="&imgroot;image004.jpg"/>
+ </imageobject>
+ <textobject><phrase>CPE Configurator after components chosen</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+
+ </section>
+
+ <section id="ugr.tools.cpe.running">
+ <title>Running a Collection Processing Engine</title>
+
+ <para>After selecting each of the components and providing configuration settings,
+ click the play (forward arrow) button at the bottom of the screen to begin processing. A
+ progress bar should be displayed in the lower left corner. (Note that the progress bar
+ will not begin to move until all components have completed their initialization, which
+ may take several seconds.) Once processing has begun, the pause and stop buttons become
+ enabled.</para>
+
+ <para>If an error occurs, you will be informed by an error dialog. If processing completes
+ successfully, you will be presented with a performance report.</para>
+
+ </section>
+
+ <section id="ugr.tools.cpe.file_menu">
+ <title>The File Menu</title>
+
+ <para>The CPE Configurator's File Menu has six options:</para>
+
+ <itemizedlist><listitem><para>Open CPE Descriptor</para></listitem>
+
+ <listitem><para>Save CPE Descriptor</para></listitem>
+
+ <listitem><para>Refresh Descriptors from File System</para></listitem>
+
+ <listitem><para>Clear All</para></listitem>
+
+ <listitem><para>Exit </para></listitem></itemizedlist>
+
+ <para><emphasis role="bold">Open CPE Descriptor</emphasis> will allow you to select a
+ CPE Descriptor file from disk, and will read in that CPE Descriptor and configure the GUI
+ appropriately.</para>
+
+ <para><emphasis role="bold">Save CPE Descriptor</emphasis> will create a CPE
+ Descriptor file that defines the CPE you have constructed. This CPE Descriptor will
+ identify the components that constitute the CPE, as well as the configuration settings
+ you have specified for each of these components. Later, you can use <quote>Open CPE
+ Descriptor</quote> to restore the CPE Configurator to the state. Also, CPE
+ Descriptors can be used to easily run a CPE from a Java program – see <olink
+ targetdoc="&uima_docs_tutorial_guides;"
+ targetptr="ugr.tug.application.running_a_cpe_from_a_descriptor"/>
+ .</para>
+
+ <para>CPE Descriptors also allow specifying operational parameters, such as error
+ handling options that are not currently available for configuration through the CPE
+ Configurator. For more information on manually creating a CPE Descriptor, see <olink
+ targetdoc="&uima_docs_ref;" targetptr="ugr.ref.xml.cpe_descriptor"/>
+ .</para>
+
+ <para><emphasis role="bold">Refresh Descriptors from File System</emphasis> will
+ reload all descriptors from disk. This is useful if you have made a change to the
+ descriptor outside of the CPE Configurator, and want to refresh the display.</para>
+
+ <para><emphasis role="bold">Clear All</emphasis> will reset the CPE Configurator to
+ its initial state, with no components selected.</para>
+
+ <para><emphasis role="bold">Exit</emphasis> will close the CPE Configurator. If you
+ have unsaved changes, you will be prompted as to whether you would like to save them to a
+ CPE Descriptor file. If you do not save them, they will be lost.</para>
+
+ <para>When you restart the CPE Configurator, it will automatically reload the last CPE
+ descriptor file that you were working with.</para>
+
+ </section>
+
+ <section id="ugr.tools.cpe.help_menu">
+ <title>The Help Menu</title>
+
+ <para>The CPE Configurator's Help menu provides <quote>About</quote>
+ information and some very simple instructions on how to use the tool.</para>
+
+ </section>
</chapter>
Added: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cvd.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cvd.xml?view=auto&rev=482771
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cvd.xml (added)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.cvd.xml Tue Dec 5 12:39:49 2006
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
+<!ENTITY imgroot "../images/tools/tools.cvd/" >
+<!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.cvd">
+ <title>CAS Visual Debugger</title>
+ <para>tbd</para>
+</chapter>
\ No newline at end of file
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?view=diff&rev=482771&r1=482770&r2=482771
==============================================================================
--- 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 Tue Dec 5 12:39:49 2006
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/annotator_analysis_engine_files/" >
-<!ENTITY % uimaents SYSTEM "entities.ent" >
+<!ENTITY imgroot "../images/tools/tools.doc_analyzer/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
<!--
@@ -23,28 +23,25 @@
specific language governing permissions and limitations
under the License.
-->
-<chapter id="ugr.tool.doc_analyzer">
- <title></title>
- <section name="Document Analyzer User's Guide"><a id="_crossRef205"> </a>
+<chapter id="ugr.tools.doc_analyzer">
+ <title>Document Analyzer User's Guide</title>
+
-
-
-<para>The <emphasis>Document Analyz</emphasis>er is a tool provided by the
-UIMA SDK for testing annotators and TAEs. It reads text files from your disk, processes them using a TAE, and
+<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 <a class="crossrefText" href="Annotator_and_Analysis_Engine_Developers_Guide.htm#_crossRef1">Chapter 4, <b>Annotator and Analysis Engine Developer's Guide</b></a>. This chapter is a user's guide for using the Document Analyzer tool, and
+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>
-
-
-<subsection name="Starting the Document Analyzer"><a id="_crossRef206"> </a>
-
-
-
+<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>
@@ -55,61 +52,73 @@
that Analysis Engine.</para>
<para>When you first run the Document Analyzer, you should see a
-screen that looks like this:</para>
-
-<para><img alt="" width="564" height="314"
-src="../UIMA_SDK_Guide_Ref/Document_Analyzer_Users_Manual_files/image002.jpg"/></para>
-
-
-
-
-
+screen that looks like this:
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="564" depth="314" 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>
- </subsection>
-<subsection name="Running a TAE"><a id="_crossRef207"> </a>
-
-<para>To run a TAE, you must first configure the six fields on
+<para>To run a AE, you must first configure the six fields on
the main screen of the Document Analyzer.</para>
-<para><b>Input Directory</b>: Browse to or type the path of a directory containing text files that you
+<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>docs/examples/data</literal>
+are provided in the UIMA SDK under the <literal>examples/data</literal>
directory.</para>
-<para><b>Output Directory:</b> Browse to or type the path of a directory where you want output to be
+<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 you leave
-this field blank, your TAE will be run but no output will be generated.</para>
+this field blank, your AE will be run but no output will be generated.</para>
-<para><b>Location of TAE XML Descriptor</b>: Browse to or type the path of the descriptor
-for the TAE that you want to run. There
-are some example descriptors provided in the UIMA SDK under the <literal>docs/examples/descriptors/analysis_engine</literal> and <literal>docs/examples/descriptors/tutorial</literal> directories.</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><b>XML Tag containing Text</b>: This is an optional feature. If you enter a value here, it specifies the
+<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 TAE to only
+example, the value <literal>TEXT</literal> would cause the AE to only
analyze the portion of the document enclosed within <TEXT>...</TEXT>
tags.</para>
-<para><b>Language: </b>Specify
+<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: <literal><a
-href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</a></literal>
+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><b>Character Encoding:</b> The character encoding of the input files. The default, UTF-8, also works fine for ASCII
+<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>
+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>
@@ -122,36 +131,46 @@
-
-
-
- </subsection>
-<subsection name="Viewing the Analysis Results"><a id="_crossRef208"> </a>
-
-
+</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.</para>
+Results</quote> window will appear.
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="434" depth="262" format="JPG" fileref="&imgroot;image004.jpg"/>
+ </imageobject>
+ <textobject><phrase>Analysis Results Window</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
-<para><img alt="" width="434" height="262"
-src="../UIMA_SDK_Guide_Ref/Document_Analyzer_Users_Manual_files/image004.jpg"/></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>
+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 TAE descriptor <literal>docs/examples/descriptors/tutorial/ex4/MeetingDetectorTAE.xml</literal>):</para>
+(for the AE descriptor <literal>examples/descriptors/tutorial/ex4/MeetingDetectorAE.xml</literal>):
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="575" depth="413" format="JPG" fileref="&imgroot;image006.jpg"/>
+ </imageobject>
+ <textobject><phrase>Analysis Results Window showing results from tutorial example 4</phrase></textobject>
+ </mediaobject>
+ </screenshot></para>
-<para><img alt="" width="575" height="413"
-src="../UIMA_SDK_Guide_Ref/Document_Analyzer_Users_Manual_files/image006.jpg"/></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>
@@ -165,13 +184,10 @@
choose the Sofa that you wish to view. Note that only text Sofas containing a non-null document are available
for viewing.</para>
-
-
-
- </subsection>
-<subsection name="Configuring the Annotation Viewer"><a id="_crossRef209"> </a>
-
-
+</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
@@ -180,10 +196,18 @@
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:</para>
+Map</quote> button on the <quote>Analysis Results</quote> dialog.
+ You should see a dialog that looks like this:
-<para><img alt="" width="576" height="220"
-src="../UIMA_SDK_Guide_Ref/Document_Analyzer_Users_Manual_files/image008.jpg"/></para>
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="576" depth="220" 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
@@ -200,17 +224,15 @@
<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 TAE descriptor. From now on, when you view analysis results
-produced by this TAE using the <quote>JV User Colors</quote> or <quote>HTML</quote>
+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>
-
-
- </subsection>
-<subsection name="Interactive Mode"><a id="_crossRef210"> </a>
-
-
+<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
@@ -219,53 +241,38 @@
<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:</para>
-
-<para><img alt="" width="502" height="355"
-src="../UIMA_SDK_Guide_Ref/Document_Analyzer_Users_Manual_files/image010.jpg"/></para>
+display a dialog that looks like this:
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="502" depth="355" 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 TAE will be run on the text
+button. Your AE will be run on the text
that you supplied and the results will be displayed as usual.</para>
-
-
- </subsection>
-<subsection name="View Mode"><a id="_crossRef211"> </a>
-
-
-
-<para>If you have previously run a TAE and saved its analysis
+</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 <a class="crossrefText" href="Document_Analyzer_Users_Manual.htm#_crossRef208">17.3, <b><emphasis>Viewing the Analysis
-Results</emphasis></b></a>.</para>
-
-
-
-</div>
-
-<br/>
-
-
-<div class="Section2">
-
-
-
-
- </subsection>
+view your analysis results as described in Section
+ <xref linkend="ugr.tools.doc_analyzer.viewing_results"/>.</para>
</section>
-<section name="CAS Visual Debugger"><a id="_crossRef212"> </a>
-
-
-
-<para>The documentation for this component is found in a
-separate file in the docs/ directory, called <literal>CASVisualDebugger.pdf</literal>.</para>
+ </chapter>
-</chapter>
\ No newline at end of file
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?view=diff&rev=482771&r1=482770&r2=482771
==============================================================================
--- 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 Tue Dec 5 12:39:49 2006
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/annotator_analysis_engine_files/" >
-<!ENTITY % uimaents SYSTEM "entities.ent" >
+<!ENTITY imgroot "../images/tools/tools.jcasgen/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
<!--
@@ -23,121 +23,137 @@
specific language governing permissions and limitations
under the License.
-->
-<chapter id="ugr.tool.jcasgen">
- <title></title>
- <section name="JCasGen User Guide"><a id="_crossRef222"> </a>
-
-
-
-<para>JCasGen reads a descriptor for an application, 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, except for the <literal>uima.tcas.DocumentAnnotation</literal>
-built-in type, which is the only built-in type that can be extended by users by
-adding features to it.</para>
-
-<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 page <a class="crossrefPage" href="JCas_Reference.htm#_crossRef230">27-369</a> 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 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:</para>
-
-<para><img alt="" width="576" height="334"
-src="../UIMA_SDK_Guide_Ref/JCasGen_Users_Guide_files/image002.jpg"/></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>
-
-<h4><a id="_crossRef223">Running stand-alone without Eclipse</a></h4>
-
-<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>
-
-<h4><a id="_crossRef224">Running stand-alone with Eclipse</a></h4>
-
-<para>If you have Eclipse and EMF (EMF = Eclipse Modeling
-Framework; both of these are available from <a href="http://www.eclipse.org/">http://www.eclipse.org</a>)
-installed (version 2.1 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 2.1 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>
-
-<h4><a id="_crossRef225">Running within Eclipse</a></h4>
-
-<para>There are two ways to run JCasGen within Eclipse, with
-this release. 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...).</para>
-
-<para><img alt="" width="503" height="547"
-src="../UIMA_SDK_Guide_Ref/JCasGen_Users_Guide_files/image004.jpg"/></para>
-
-<para>The second way to run within Eclipse is to use the
-Analysis Engine Configurator tool <emphasis>Chapter 7. The UIMA Component Descriptor
-Editor User's Guide</emphasis>. This tool can be configured to automatically launch
-JCasGen whenever the descriptor is modified. In this release, this operation completely regenerates the files, even
-if just a small thing changed. So you probably don't want to enable this all
-the time. The configurator tool has an
-option to enable/disable this function.</para>
-
+<chapter id="ugr.tools.jcasgen">
+ <title>JCasGen User Guide</title>
+
+ <para>JCasGen reads a descriptor for an application, 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, except for the <literal>uima.tcas.DocumentAnnotation</literal>
+ built-in type, which is the only built-in type that can be extended by users by adding
+ features to it.</para>
+
+ <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="576" depth="334" 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="503" depth="547" 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>
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?view=diff&rev=482771&r1=482770&r2=482771
==============================================================================
--- 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 Tue Dec 5 12:39:49 2006
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/annotator_analysis_engine_files/" >
-<!ENTITY % uimaents SYSTEM "entities.ent" >
+<!ENTITY imgroot "../images/tools/tools.pear.installer/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
<!--
@@ -23,63 +23,63 @@
specific language governing permissions and limitations
under the License.
-->
-<chapter id="ugr.tool.pear.installer">
- <title></title>
- <section name="PEAR Installer User's Guide"><a id="_crossRef246"> </a>
-
-
-
-<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.</para>
-
-<para><img alt="" width="575" height="470"
-src="../UIMA_SDK_Guide_Ref/PEAR_Installer_files/image002.jpg"/></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). 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 <literal>CASVisualDebugger.pdf</literal>
-in the <literal>docs</literal> directory 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 the <literal>setenv.txt</literal>
-file in the <literal><component_root>/metadata</literal>
-directory. This file contains environment variables required to run your
-component in any UIMA application. For instance, if you want to run your
-component in the Collection Processing Engine Configurator GUI application, you
-need to add the environment variables settings from the component's <literal>setenv.txt</literal> file to the <literal>cpeGui.bat
-(cpeGui.sh)</literal> script file in the <literal><UIMA_HOME>/bin</literal>
-directory.</para>
-
+<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="575" depth="470" 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). 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> file in the
+ <literal><component_root>/metadata</literal> directory. This file contains
+ environment variables required to run your component in any UIMA application. For
+ instance, if you want to run your component in the Collection Processing Engine
+ Configurator GUI application, you need to add the environment variables settings from
+ the component's <literal>setenv.txt</literal> file to the <literal>cpeGui.bat
+ (cpeGui.sh)</literal> script file in the <literal><UIMA_HOME>/bin</literal>
+ directory.</para>
+
</chapter>
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?view=diff&rev=482771&r1=482770&r2=482771
==============================================================================
--- 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 Tue Dec 5 12:39:49 2006
@@ -1,8 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
-<!ENTITY imgroot "images/annotator_analysis_engine_files/" >
-<!ENTITY % uimaents SYSTEM "entities.ent" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
%uimaents;
]>
<!--
@@ -23,162 +22,144 @@
specific language governing permissions and limitations
under the License.
-->
-<chapter id="ugr.tool.pear.merger">
- <title></title>
- <section name="PEAR Merger User's Guide"><a id="_crossRef247"> </a>
-
-
-
-<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 text 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>This is a command-line utility; there are shell scripts
-(.bat for Windows, and .sh for Unix) to run it.</para>
-
-<para><literal>runPearMerger 1<sup>st</sup>_input_pear_file
-... n<sup>th</sup>_input_pear_file <br/>
- -n
-output_analysis_engine_name [ -f output_pear_file ]</literal></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_tae_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>
-
-
-
-<subsection name="Details of the merging process"><a id="_crossRef248"> </a>
-
-
-
-<para>The PEARs are merged using the following steps:</para>
-
-<orderedlist><listitem>A temporary working directory, is created for the output aggregate
-component.</listitem>
-
-
-<listitem>Each input PEAR file is extracted into a separate 'input_component_name'
-folder under the working directory.</listitem>
-
-
-<listitem>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.</listitem>
-
-
-<listitem>The output PEAR directory structure, 'metadata' and 'desc' folders under the working
-directory, are created.</listitem>
-
-
-<listitem>The UIMA TAE 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.</listitem>
-
-
-<listitem>A new PEAR installation descriptor is created in the 'metadata' folder,
-referencing the new output aggregate descriptor built in the previous step. </listitem>
-
-
-<listitem>The content of the temporary output working directory is zipped to
-created the output PEAR, and then the temporary working directory is deleted.
-</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>
-
-
-
-
- </subsection>
-<subsection name="Testing and Modifying the resulting PEAR"><a id="_crossRef249"> </a>
-
-
-
-<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>
-
-
-
-
- </subsection>
-<subsection name="Restrictions and Limitations"><a id="_crossRef250"> </a>
-
-
-
-<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>The Merge operation specifies Fixed Flow sequencing for the Aggregate.</listitem>
-
-
-<listitem>The merged aggregate does not define any parameters, so the delegate
-parameters cannot be overridden.</listitem>
-
-
-<listitem>No External Resource definitions are generated for the aggregate.</listitem>
-
-
-<listitem>No Sofa Mappings are generated for the aggregate.</listitem>
-
-
-<listitem>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.</listitem>
-
-
-<listitem>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.</listitem>
-
-
-<listitem>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.</listitem>
-
-
-<listitem>You can only merge Analysis Engines and CAS Consumers. </listitem>
-
-
-<listitem>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:<br/>
-<literal><SUBMITTED_COMPONENT> <br/>
- <DESC>the_component.xml</DESC>... <br/>
-</SUBMITTED_COMPONENT></literal>. <br/>
-
-</listitem></orderedlist>
-
-</chapter>
\ No newline at end of file
+<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 text
+ 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>This is a command-line utility; there are shell scripts (.bat for Windows, and .sh for
+ Unix) to run it.</para>
+
+ <para><command>runPearMerger 1<superscript>st</superscript>_input_pear_file ...
+ n<superscript>th</superscript>_input_pear_file -n output_analysis_engine_name [
+ -f output_pear_file ]</command></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_tae_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 TAE 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>