doc changes

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@14994 1b8cb986-b30d-0410-93ca-fae66ebed9b2

documentation/manual/src/main/docbook/en-US/content/tutorial.xml

@@ -27,86 +27,120 @@
         <!ENTITY mdash "-">
 ]>
 
+        <!-- todo : need searate sections, one for each tutorial -->
+
 <chapter id="tutorial">
     <title>Introduction to Hibernate</title>
     
-    <sect1 id="tutorial-intro" revision="1">
+    <sect1 id="tutorial-intro">
         <title>Preface</title>
 
         <para>
-            This chapter is an introductory tutorial for new users of Hibernate. We start
+            This chapter is an introduction to Hibernate by way of a tutorial,
-            with a simple command line application using an in-memory database and develop
+            intended for new users of Hibernate.  We start with a simple
-            it in easy to understand steps.
+            application using an in-memory database.  We build the
-        </para>
+            application in small, easy to understand steps.  The tutorial is
-
+            based on another, earlier one developed by Michael Gloegl.  All
-        <para>
+            code is contained in the <filename>tutorials/web</filename> directory
-            This tutorial is intended for new users of Hibernate but requires Java and
+            of the project source.
-            SQL knowledge. It is based on a tutorial by Michael Gloegl, the third-party
-            libraries we name are for JDK 1.4 and 5.0. You might need others for JDK 1.3.
-        </para>
-
-        <para>
-            The source code for the tutorial is included in the distribution in the
-            <literal>doc/reference/tutorial/</literal> directory.
         </para>
 
     </sect1>
 
-    <sect1 id="tutorial-firstapp" revision="2">
+    <important>
+        <para>
+            This tutorial expects the user have knowledge of both Java and
+            SQL.  If you are new or uncomfortable with either, it is advised
+            that you start with a good introduction to that technology prior
+            to attempting to learn Hibernate.  It will save time and effort
+            in the long run.
+        </para>
+    </important>
+
+    <note>
+        <para>
+            There is another tutorial/example application in the
+            <filename>/tutorials/eg</filename> directory of the project source.
+            That example is console based and as such would not have the
+            dependency on a servlet container to execute.  The basic setup is
+            the same as the instructions below.
+        </para>
+    </note>
+
+    <sect1 id="tutorial-firstapp">
         <title>Part 1 - The first Hibernate Application</title>
 
         <para>
-            First, we'll create a simple console-based Hibernate application. We use an
+            Let's assume we need a small database application that can store
-            Java database (HSQL DB), so we do not have to install any database server.
+            events we want to attend, and information about the host(s) of
+            these events.  We will use an in-memory, Java database named HSQLDB
+            to avoid describing installation/setup of any particular database
+            servers.  Feel free to tweak this tutorial to use whatever database
+            you feel comfortable using.
         </para>
             
         <para>
-            Let's assume we need a small database application that can store events we want to
+            The first thing we need to do is set up our development environment,
-            attend, and information about the hosts of these events.
+            and specifically to setup all the required dependencies to Hibernate
-        </para>
+            as well as other libraries.  Hibernate is built using Maven which 
-            
+            amongst other features provides <literal>dependecy management</literal>;
-        <para>
+            moreover it provides <emphasis>transitive</emphasis>
-            The first thing we do, is set up our development directory and put all the
+            <literal>dependecy management</literal> which simply means that to use
-            Java libraries we need into it. Download the Hibernate distribution from the
+            Hibernate we can simply define our dependency on Hibernate, Hibernate
-            Hibernate website. Extract the package and place all required libraries
+            itself defines the dependencies it needs which then become transitive
-            found in <literal>/lib</literal> into into the <literal>/lib</literal> directory
+            dependencies of our project.
-            of your new development working directory. It should look like this:
         </para>
 
         <programlisting><![CDATA[.
-+lib
+<project xmlns="http://maven.apache.org/POM/4.0.0"
-  antlr.jar
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  cglib.jar
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-  asm.jar
-  asm-attrs.jars
-  commons-collections.jar
-  commons-logging.jar
-  hibernate3.jar
-  jta.jar
-  dom4j.jar
-  log4j.jar ]]></programlisting>
 
+    ...
+
+    <dependencies>
+        <dependency>
+            <groupId>${groupId}</groupId>
+            <artifactId>hibernate-core</artifactId>
+        </dependency>
+
+        <!-- Because this is a web app, we also have a dependency on the servlet api. -->
+        <dependency>
+            <groupId>javax.servlet</groupId>
+            <artifactId>servlet-api</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>]]></programlisting>
+
+        <note>
             <para>
-            This is the minimum set of required libraries (note that we also copied
+                Essentially we are describing here the
-            hibernate3.jar, the main archive) for Hibernate <emphasis>at the time of writing</emphasis>.
+                <filename>/tutorials/web/pom.xml</filename> file.  See the
-            The Hibernate release you are using might require more or less libraries. See the
+                <ulink url="http://maven.org">Maven</ulink> site for more information.
-            <literal>README.txt</literal> file in the <literal>lib/</literal> directory of the
-            Hibernate distribution for more information about required and optional third-party
-            libraries. (Actually, Log4j is not required but preferred by many developers.)
             </para>
+        </note>
+
+        <tip>
+            <para>
+                While not strictly necessary, most IDEs have integration with Maven
+                to read these POM files and automatically set up a project for you
+                which can save lots of time and effort.
+            </para>
+        </tip>
 
         <para>
             Next we create a class that represents the event we want to store in database.
         </para>
       
-        <sect2 id="tutorial-firstapp-firstclass" revision="1">
+        <sect2 id="tutorial-firstapp-firstclass">
             <title>The first class</title>
             
             <para>
                 Our first persistent class is a simple JavaBean class with some properties:
             </para>
 
-            <programlisting><![CDATA[package events;
+            <programlisting><![CDATA[package org.hibernate.tutorial.domain;
 
 import java.util.Date;
 
@@ -188,7 +222,7 @@ public class Event {
                 
         </sect2>
 
-        <sect2 id="tutorial-firstapp-mapping" revision="1">
+        <sect2 id="tutorial-firstapp-mapping">
             <title>The mapping file</title>
 
             <para>