Improving the documentation

docs/javaBootcampNoEclipse.org

@@ -7,7 +7,7 @@
 #+OPTIONS: author:t c:nil creator:comment d:(not "LOGBOOK") date:t
 #+OPTIONS: e:t email:nil f:t inline:t num:t p:nil pri:nil stat:t
 #+OPTIONS: tags:t tasks:t tex:t timestamp:t toc:t todo:t |:t
-#+CREATOR: Emacs 24.5.1 (Org mode 9.0)
+#+CREATOR:
 #+DESCRIPTION: A java bootcamp module on building an app for tomcat with just the command-line
 #+EXCLUDE_TAGS: noexport
 #+KEYWORDS:
@@ -19,12 +19,13 @@
 ** Pre-requisites
    You will need a linux server with the following installed:
    - tomcat :: This demo was prepare with tomcat-8.
-   - tomcat manager :: Used for deploying the your built application
+   - tomcat manager :: Used for deploying your built application
-   - A web browser :: for accessing the tomcat manager
+   - A web browser :: For accessing the tomcat manager
-   - git :: to access the project
+   - git :: To access the project
-   - a text editor :: to fix any bugs you find (*Not* =eclipse=,
+   - a text editor :: To fix any bugs you find (*Don't* use =eclipse=,
-                      because that's the whole point.)
+        or any other "IDE", because that's the whole point.)
-   - java 8 JDK :: to build code
+   - java 8 JDK :: To build code
+
    If you develop on one machine and deploy to the other, then
    *tomcat* and *tomcat manager* are to be on the system you're
    deploying to, and the rest where you're developing.
@@ -39,7 +40,8 @@
       where the git repository has been cloned to.
    1. Get the code
       : git clone https://gitlab.com/eibhear/javaBootcampNoEclipse.git
-      The repository is now in =${DEV_HOME}=. Change into it:
+      The repository is now in =${DEV_HOME}=. Set that as an
+      environment variable and change into it:
       : export DEV_HOME=$(pwd)/javaBootcampNoEclipse
       : cd ${DEV_HOME}
    2. Make sure you're at the starting point:
@@ -56,47 +58,53 @@
 *** Steps
     0. [@0] Confirm you can access the java compiler:
        : javac -version
-       If this doesn't result in a message like =javac 1.8.0_141=,
+       If this doesn't result in a message that looks something like
-       you'll need to find where =javac= installed and place it on
+       =javac 1.8.0_141=, you'll need to find where =javac= is
-       your =${PATH}=.
+       installed and place it on your =${PATH}=.
     1. Change to where the code is:
        : cd ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse
     2. Compile the files:
        : javac *.java
-    3. Check the errors. If you see the message =error: package
+    3. Check the errors. If you see the message
-       javax.servlet does not exist=, then look at your =CLASSPATH=
+       : error: package javax.servlet does not exist
-       setting, as dependend libraries are missing.
+       then look at your =CLASSPATH= setting, as dependent libraries
+       are missing.
     4. Fix your =CLASSPATH= and compile the java files:
        : export CLASSPATH=/usr/share/java/tomcat8-servlet-api.jar:${CLASSPATH}
        : javac *.java
-    5. If the successful, you will have the following additional files:
+    5. If successful, you will have the following additional files
-       : ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/MyHelloWorldBean.class
+       under =${DEV_HOME}/source/java/=:
-       : ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.class
+       : org/gibiris/javaBootcampNoEclipse/MyHelloWorldBean.class
+       : org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.class
        If this is the case, move on to lesson 2:
        : git checkout lesson-2
 
 ** Lesson 2 -- build the jar file
 
 *** Starting point
-    A clean git working area with two additional class files
+    A clean git working area with two additional class files in
+    =${DEV_HOME}/source/java/=:
+    : org/gibiris/javaBootcampNoEclipse/MyHelloWorldBean.class
+    : org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.class
 
 *** Goal
     Class files archived into a jar file
 
 *** Steps
     1. Decide whether you want to include the source (=*.java=) files
-       in the jar file
+       in the jar file.
     2. Determine other files to be included in the jar file
-       (e.g. config files, property files, etc.)
+       (e.g. config files, property files, etc.).
     3. Change to the top-level of the package in the source:
        : cd ${DEV_HOME}/source/java
        Create the =lib/= directory to take the jar file:
        : mkdir -pv ../lib
-       If you're *not* including the source files in the jar:
+    4. If you're *not* including the source files in the jar:
-       : jar cvf ../lib/javaBootcampNoEclipse.jar org/gibiris/javaBootcampNoEclipse/*.class
+       : jar cvf ../lib/javaBootcampNoEclipse.jar \
-       If you *are* including the source files in the jar:
+       :     org/gibiris/javaBootcampNoEclipse/*.class
-       : jar cvf ../lib/javaBootcampNoEclipse.jar org/gibiris/javaBootcampNoEclipse/*
+    5. If you *are* including the source files in the jar:
-    4. If the successful, you will now have a new file:
+       : jar cvf ../lib/javaBootcampNoEclipse.jar org
+    6. If successful, you will now have a new file:
        : ${DEV_HOME}/source/lib/javaBootcampNoEclipse.jar
        If this is the case, move on to lesson 3:
        : git checkout lesson-3
@@ -104,8 +112,12 @@
 ** Lesson 3 -- build the war file
 
 *** Starting point
-    A clean git working area with two additional class files and one
+    A clean git working area with two additional class files in
-    additional jar file.
+    =${DEV_HOME}/source/java/=:
+    : org/gibiris/javaBootcampNoEclipse/MyHelloWorldBean.class
+    : org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.class
+    and one additional jar file in =${DEV_HOME}/source/lib/=:
+    : javaBootcampNoEclipse.jar
 
 *** Goal
     A deployable war file
@@ -113,64 +125,83 @@
 *** Steps
     0. [@0] Review the following:
        - http://tomcat.apache.org/tomcat-8.0-doc/appdev/deployment.html
-         to understand the structure of the =war= file and the
+         to understand the structure of the file =web.xml= and the
-         =web.xml= file
+         =war= file
        - =${DEV_HOME}/source/res/web.xml= to understand how this
-         application is to be used.
+         application is to be used
     1. Create an empty directory in =${DEV_HOME}= called =webapp=,
-       then its directory structure and then change into it:
+       then its directory structure, and then change into it:
        : mkdir -vp ${DEV_HOME}/webapp
        : mkdir -vp ${DEV_HOME}/webapp/WEB-INF/lib
        : cd ${DEV_HOME}/webapp
     2. Copy in the jsps:
        : cp -rv ${DEV_HOME}/source/jsps/* ${DEV_HOME}/webapp
     3. Copy in the jar file:
-       : cp -rv ${DEV_HOME}/source/lib/javaBootcampNoEclipse.jar ${DEV_HOME}/webapp/WEB-INF/lib
+       : cp -rv ${DEV_HOME}/source/lib/javaBootcampNoEclipse.jar \
+       :     ${DEV_HOME}/webapp/WEB-INF/lib
     4. Copy in the =web.xml= file:
-       : cp -rv ${DEV_HOME}/source/res/web.xml ${DEV_HOME}/webapp/WEB-INF
+       : cp -rv ${DEV_HOME}/source/res/web.xml \
+       :     ${DEV_HOME}/webapp/WEB-INF
     5. Create the war file:
        : jar cvf ${DEV_HOME}/source/lib/javaBootcampNoEclipse.war *
     6. If this was successful you will now have a new file:
        : ${DEV_HOME}/source/lib/javaBootcampNoEclipse.war
-       If this is the case, remove the direcory =${DEV_HOME}/webapp=
+    7. If this is the case, remove the direcory =${DEV_HOME}/webapp=
        and move on to lesson 4:
-       : rm -fr ${DEV_HOME}/webapp
+       : cd ${DEV_HOME}; rm -fr ${DEV_HOME}/webapp
        : git checkout lesson-4
 
 ** Lesson 4 -- deploy and test
 
 *** Starting point
-    A clean working area with two additional class files, one
+    1. A clean working area with two additional class files in
-    additional jar file and one additional war file.
+       =${DEV_HOME}/source/java/=:
+       : org/gibiris/javaBootcampNoEclipse/MyHelloWorldBean.class
+       : org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.class
+       one additional jar file and one additional war file, both in
+       =${DEV_HOME}/source/lib=:
+       : javaBootcampNoEclipse.jar
+       : javaBootcampNoEclipse.war
 
 *** Goal
-    A deployed, working application
+    A working application
 
 *** Steps
     0. [@0] Some pre-steps
        - If this isn't the first time to deploy, be sure to /undeploy/
          the previous version of the application.
-    1. Navigate to =http://server:8080/manager=
+       - To follow these steps, you'll need your file
+         =javaBootcampNoEclipse.war= to be accessible locally to your
+         browser.
+    1. Navigate to =http://server:8080/manager= (where =server= is
+       where your tomcat instance is running)
     2. Go to the /WAR file to deploy/ section and use the /Browse.../
-       button to select the war file to deploy.
+       button to select the war file to deploy
+       (=javaBootcampNoEclipse.war=).
     3. Press the /Deploy/ button. If successful, you'll see your
        application shown in the list.
     4. Go to =http://server:8080/javaBootcampNoEclipse= to access your
        app.
-    5. Test the application. If all is well, move on to lesson 5:
+    5. Test the application. If all is well, clean up your development
+       environment altogether:
+       : rm -vf ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/*.class
+       : rm -vf ${DEV_HOME}/source/lib/javaBootcampNoEclipse.?ar
+       : rm -vfr ${DEV_HOME}/webapp
+    6. Move on to lesson 5:
        : git checkout lesson-5
 
 ** Lesson 5 -- Add new functionality
 
 *** Starting point
-    A clean working brought up to date to include the two new files:
+    A clean working area, brought up to date to include the two new
-    =${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/Astro/AstroFun.java=
+    files -- =Astro/AstroFun.java= in
-    and =${DEV_HOME}/source/lib/AstroLib-1.1.5ws.jar=, and an update
+    =${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse= and
-    to
+    =AstroLib-1.1.5ws.jar= in =${DEV_HOME}/source/lib= -- and an
-    =${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/MyHelloWorldServlet.java=.
+    update to =MyHelloWorldServlet.java= in
+    =${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse=.
 
 *** Goal
-    A working, updated application deployed to tomcat
+    A working, updated application deployed to tomcat.
 
 *** Steps
     0. [@0] Pre-steps
@@ -178,33 +209,42 @@
          + =DEV_HOME= is set to where the git repository is cloned to
          + =CLASSPATH= contains =tomcat8-servlet-api.jar=
        - Clean out the working area if there are unnecessary/unwanted files:
-         : rm -vf ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/*.class
+         : cd ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse; \
-         : rm -vf ${DEV_HOME}/source/java/org/gibiris/javaBootcampNoEclipse/Astro/*.class
+         :     rm -vf *.class; rm -vf Astro/*.class
          : rm -vf ${DEV_HOME}/source/lib/javaBootcampNoEclipse.?ar
          : rm -vfr ${DEV_HOME}/webapp
        - Review the changes that have been applied to the working area
     1. Compile the java files (including the new java file) as per
-       Lesson 1.
+       /Lesson 1/.
 
-       Does it compile? If not, why. Three hints:
+       Does it compile? If not, why not? Three hints:
-       - there was a new sub-package added,
+       - There was a new sub-package added,
          =org.gibiris.javaBootcampNoEclipse.Astro=, which your java
-         compiler needs to be able to find.
+         compiler needs to be able to find
-       - there was a new jar file introduced to the repository
+       - There was a new jar file introduced to the repository
-       - there's a bug in the package specification in the new java
+       - There's a bug in the package specification in the new java
          file. Looking closely at the branches of this git repository,
          you might even find a fix for it.
 
-    2. Build the jar file as per Lesson 2 (except, this time, the
+    2. Build the jar file as per /Lesson 2/ (except, this time, the
        =lib= directory exists already).
 
-    3. Build the war file as per Lesson 3.
+    3. Build the war file as per /Lesson 3/.
 
-    4. Deploy the updated application as per lesson 4. You will need
+    4. Deploy the updated application as per /Lesson 4/. You will need
        to undeploy the previous version first.
 
-       Does it deploy? Why not? (Hint: there was a new jar file
+       Does it deploy? Why not? If it deploys, does it work? Why not?
-       introduced to the repository)
+       (Hint: there was a new jar file introduced to the repository)
 
     5. Fix the new bug, undeploy the bad application and deploy the
        corrected one.
+
+** Fin
+
+   *Look closely. At last, you get to see an eclipse!*
+
+   Hint: what's happening[fn:longPast:... or "what /happened/" if it
+   has gone past] in Grand Island in Nebraska at ~13:00 local time on
+   [2017-08-21 Mon]?
+