changed documentation to asciidoc

Author: raverkamp

.gitignore

@@ -5,3 +5,4 @@
 config.bat
 config.sh
 *.bak
+readme.html

readme.txt

@@ -1,41 +1,36 @@
-* plsql-codecoverage
+= plsql-codecoverage
 
 plsqlcodecoverage is a program to do code coverages of Oracle PL/SQL code
 running in the database. Currently only code coverage for packages is
 supported.
 
-** How it works
+== How it works
 The program creates the following database objects:
-the tables 
-aaa_coverage
-aaa_coverage_statements
-
-the sequence 
-aaa_coverage_seq
-
-and the package 
-aaa_coverage_tool
+the tables +aaa_coverage+ and +aaa_coverage_statements+, 
+the sequence +aaa_coverage_seq+ and the package +aaa_coverage_tool+.
 
 The codecoverage process works by instrumenting the PL/SQL code, a logging
 statement is placed before each statement.
 
 Example:
 A function
+----
 function f2(x varchar2) return varchar2 is
 begin
   return 'd'||x;
 end;
-
+----
 becomes
-
+----
 function f2(x varchar2) return varchar2 is
 begin
   "$log"(4);return 'd'||x;
 end;
+----
 
-The execution of the statments is logged into the tables aaa_coverage and
-aaa_coverage_statements. Only the first execution of a statement is logged.
-The original package state is stored in a clob in table aaa_coverage.
+The execution of the statments is logged into the tables +aaa_coverage+ and
++aaa_coverage_statements+. Only the first execution of a statement is logged.
+The original package state is stored in a clob in table +aaa_coverage+.
 
 The codecoverage process is started for each package individually.
 The codecoverage process works for all sessions that use the instrumented 
@@ -52,60 +47,65 @@ Each schema/user has its own version of the database objects.
 Needless to say that you should have a copy of your packages. Before instrumemting,
 the original source code is saved into a clob, but one never knows.
 
-** How to build
+== How to build
 
 plsqlodecoverage is currently developed as a netbeans project.
 The platform is java 7, but the root classes are still java 8. 
 I use this setup for developing/debugging.
 
 The system can also be build with a simple ant build file:
-build-plsqlcodecoverage.xml. 
++build-plsqlcodecoverage.xml+. 
 
 On windows you need an ant installation and you have to
-set JAVA_HOME correctly. I do this with a configuration script
+set +JAVA_HOME+ correctly. I do this with a configuration script
 which has these contents on my machine:
 
+--------------------------
 set java_home=C:\Program Files\Java\jdk1.8.0_25
 set ant="C:\Program Files\NetBeans 8.0.1\extide\ant\bin\ant.bat"
 set orajdbclib=C:\oraclexe\app\oracle\product\11.2.0\server\jdbc\lib\ojdbc6.jar
 set jre7=C:\Program Files (x86)\Java\jre7
+--------------------------
 
 The variables orajdbclib is used in the build for obvious reasons.
-The variable jre7 is used to set the bootclasspath.
+The variable +jre7+ is used to set the bootclasspath.
 
 To build the system, run
-%ant% -f build-plsqlcodecoverage.xml dist|dist-fat|dist-lean
-
-The target dist creates a jar file psqlcodecoverage.jar in the directory dist.
-The folder lib in the same directory contains the file ojdbc6.jar
-which is referenced in the manifest of psqlcodecoverage.jar.
-
-The target dist-fat creates a jar file psqlcodecoverage.jar in the directory dist.
+----
+%ant% -f build-plsqlcodecoverage.xml target
+----
+where target is one of the following:
+
+* +dist+: create a jar file +psqlcodecoverage.jar+ in the directory +dist+.
+The folder lib in the same directory contains the file +ojdbc6.jar+
+which is referenced in the manifest of +psqlcodecoverage.jar+.
+* +dist-fat+: create a jar file +psqlcodecoverage.jar+ in the directory dist.
 This jar file contains the class files of the project as well as the class files
 of the oracle jdbc library.
-
-The target dist-lean creates a jar file psqlcodecoverage.jar in the directory dist.
+* +dist-lean+: create a jar file +psqlcodecoverage.jar+ in the directory dist.
 This jar file contains only the class files of the project. The user must supply the 
 Oracle jdbc classes via the classpath variable or command line.
 If the oracle jdbc classes are not found during startup the user has to locate
 the oracle jdbc jar file. The location is stored in the preferences. 
-If the program is started with the single argument "-clear-jdbc-file" the
-location in the preferences is deleted.
+If the program is started with the single argument +-clear-jdbc-file+ the
+location stored in the preferences is deleted.
 
-** How to use
+== How to use
 Run the program with
+----
 java -jar psqlcodecoverage.jar
-
+----
 If you are using the jar file created by the target dist, the lib directory 
-with the oracle jar file must be in the same directory as psqlcodecoverage.jar.
+with the oracle jar file must be in the same directory as +psqlcodecoverage.jar+.
 
 If you are using the jar file created by the dist-lean target, you are asked 
 to locate the oracle jdbc jar file on first startup. The chosen location will
 be saved.
 Then you will be presented with a login dialog. 
-You can use two kind conenctions
-fat: you just have to supply the tns name
-thin: you have to supply host, port and service for the database
+You can use two kind connections
+
+ * *fat* you just have to supply the tns name
+ * *thin* you have to supply host, port and service for the database
 
 In practice there are problems with the fat type connection. 
 Using this kind of connection loads a dynamic link/shared library into the
@@ -115,9 +115,10 @@ The thin connection is implemented in pure java and does not have this problem.
 
 The window shows the packages on the left. 
 The letter in front of a package is
-  V for packages that are valid but currently not covered.
-  I for packages that are invalid
-  C for packages that are covered
+
+* *V* for packages that are valid but currently not covered.
+* *I* for packages that are invalid
+* *C* for packages that are covered
 
 The red-to-green square in front of a package indicates the coverage state
 of a package, more green => more coverage.
@@ -135,4 +136,4 @@ The button stop/start coverage are used for starting code coverage and stopping
 code coverage of the currenty selected package.
 After a the code coverage of a package is stopped, the program still shows the
 state of the last code coverage session. Even if the source code of the package 
-is changed.
+is changed.