svn commit: r555946 - in /incubator/uima/uimaj/trunk/uima-docbooks/src/docbook: overview_and_setup/eclipse_setup.xml tutorials_and_users_guides/annotator_analysis_engine_guide.xml

[tw...@apache.org]

Author: twgoetz
Date: Fri Jul 13 04:48:28 2007
New Revision: 555946

URL: http://svn.apache.org/viewvc?view=rev&rev=555946
Log:
Jira UIMA-499: added documentation on how to attach source jars.

https://issues.apache.org/jira/browse/UIMA-499

Modified:
    incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/eclipse_setup.xml
    incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml

Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/eclipse_setup.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/eclipse_setup.xml?view=diff&rev=555946&r1=555945&r2=555946
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/eclipse_setup.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/overview_and_setup/eclipse_setup.xml Fri Jul 13 04:48:28 2007
@@ -255,6 +255,60 @@
     <para>To verify that you have set up the project correctly, check that there are no error
       messages in the <quote>Problems</quote> view.</para>
     
+  </section>
+  
+  <section id="ugr.ovv.eclipse_setup.linking_uima_source_code">
+    <title>Attaching UIMA source code</title>
+    
+    <para>The binary distribution also includes the UIMA Java source code.  This makes it easy to
+      inspect the source code and step through it with the debugger.  All you need to do is to
+      attach the source jars to the binary jars in Eclipse.  You only need to do this once for each
+      jar file.
+    </para>
+    
+    <para>Attaching the source code is not only interesting for looking at the code itself, or for
+    debugging.  It also enables javadoc help for UIMA APIs.  All you need to do is hover your mouse
+    over a certain element, and the corresponding javadoc will appear.  Click on an element and
+    press <quote>F3</quote> to jump to the definition of that element.
+    </para>
+  
+      <informalfigure>
+        <mediaobject>
+          <imageobject>
+            <imagedata scale="100" format="JPG" fileref="&imgroot;image003.jpg"/>
+          </imageobject>
+          <textobject><phrase>Screenshot of uimaj-examples project</phrase>
+          </textobject>
+        </mediaobject>
+      </informalfigure>
+      
+    <para>This is a screenshot of the uimaj-examples project in Eclipse 3.3 with the "Referenced
+      Libraries" section expanded.  If you look closely, you can see that in this instance, the
+      uimaj-core.jar file already has source code or javadoc attached.  The icon is slightly 
+      different from the others.
+    </para>
+    
+    <para>To attach source code to one of the other jars, for example, uima-tools.jar, proceed as
+      follows.
+    </para>
+    
+    <itemizedlist spacing="compact">
+      <listitem><para>Right-click uima-tools.jar and select <quote>Properties</quote>.
+      </para></listitem>
+      <listitem><para>Select <quote>Java Source Attachment</quote> and click the <quote>Variable...</quote>
+      button.
+      </para></listitem>
+      <listitem><para>Select <quote>UIMA_HOME</quote> and click <quote>OK</quote>.
+      </para></listitem>
+      <listitem><para>Now click the <quote>Extension...</quote> button, select <quote>src/uima-tools-sources.jar</quote>
+      and click <quote>OK</quote>, and <quote>OK</quote> again.
+      </para></listitem>
+    </itemizedlist>
+    
+    <para>Do this with every jar you think you might be interested in.  It makes most sense
+      for the uima-core.jar, you'll probably use the core APIs most of all.
+    </para>
+
   </section>
   
   <section id="ugr.ovv.eclipse_setup.running_external_tools_from_eclipse">

Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml?view=diff&rev=555946&r1=555945&r2=555946
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tutorials_and_users_guides/annotator_analysis_engine_guide.xml Fri Jul 13 04:48:28 2007
@@ -145,7 +145,11 @@
       be imported into your Eclipse workspace; see <olink
         targetdoc="&uima_docs_overview;"
         targetptr="ugr.ovv.eclipse_setup.example_code"/> for instructions on how to do
-      this. Also you may wish to refer to the UIMA SDK JavaDocs located in the <ulink
+      this.  See <olink
+        targetdoc="&uima_docs_overview;"
+        targetptr="ugr.ovv.eclipse_setup.linking_uima_source_code"/> for how to attach the UIMA 
+        source code to the jar files.
+      Also you may wish to refer to the UIMA SDK JavaDocs located in the <ulink
         url="file:../../api/index.html">docs/api</ulink> directory.</para>
     <note><para>In Eclipse 3.1, if you highlight a UIMA class or method defined in the UIMA SDK
     JavaDocs, you can conveniently have Eclipse open the corresponding JavaDoc for that