CowCatcher - Java Course Development Files

Just Objects HolyCow!
=====================

A more extended README will be there.

What is it
---------
With HolyCow you can generate (D)HTML/PDF course materials from XML sources
in a flexible and powerful way. See www.cowcatcher.org where an enormous
bulk of Java course materials is produced to get an idea.

Once you get used to using HolyCow! (as I have) you will never want to 
go back to PowerPoint or hacking some HTML slides. There are many advantages:

- complete:includes all that belongs to a course (not just slides)
- integrated: integrate your code examples and labs within the slides (no copy/paste)
- web-enabled output
- reuse: reuse lessons/modules
- multi-skin: change L&F instantaneously
- multi-platform: all XML and Java
- powerful DHTML browsing through Just Objects XMenu
- PowerPoint-presentation-like slide change with keystrokes (type 'h' in a slide for help)
- local browsing, no need to run a server
- include applets in your slides (especially for the Java folks)
- meta info: generate flyer and program content
- catalog: generate catalog and planning for larger projects
- joint projects: combine with CVS to work together on materials

The main audience for HolyCow! are developers of course materials, although you can also 
put your photo album online. See e.g. http://www.justobjects.nl/merel

Installation
------------
Unzip the distribution.
./bin - commands to generate materials and meta info
./doc - documentation as ever growing ;-)
./lib - all libs required (no need for external jars)
./rsc - resources for generation (XSL, DTD etc)
./samples - sample projects to test and tutor
./src - all sources

The only external tool required is HTMLDOC but only if you require
PDF generation. Download from http://www.easysw.com/htmldoc
Compatible version 1.8.9.
Note that PDF generation is not yet working on Unix (see TODO).

Configuration
-------------
winX: modify the indicated environment vars in bin/hcenv.bat
unixes: modify the indicated environment vars in bin/hcenv.sh
        other commands to be supplied (you may figure out from the .bat files, sorry)

The vars are indicated between: 
=== START: SET THESE VARS FOR YOUR LOCAL ENVIRONMENT !!! ===
and 
=== END: SET THESE VARS FOR YOUR LOCAL ENVIRONMENT !!! ===

important vars:
JAVA_HOME home of your Java2 J2SDK (or however you set up Java2)
HC_HOME home of the unzipped HolyCow! distribution
PROJECT_HOME home of the project for course source materials
HTMLDOC_HOME install dir of HTMLDOC tool (optional)

Rebuilding
----------
You may want to rebuild holycow.jar. Simply generate the .jar from the
./src directory. The jar holycowaux.jar bundles all external jars and should be
in your CLASSPATH.

Gotcha: also include all /rsc/* and .properties files from the ./src dir
into holycow.jar otherwise it will not work.

I will distribute a full source version with ANT scripts soon.

Running
-------
All commands are in ./bin:
hc.bat|sh - generate HTML/PDF materials for a course
meta.bat - generate meta info (flyer, program)
catalog.bat - generate catalogue of course, modules, lessons

hc.bat|sh is the most important command. The best is to first try to generate
the sample project. Here are the steps:

- open a DOS (UNIX) window
- modify hcenv.bat|sh to reflect the *_HOME directories most importantly PROJECT_HOME
to point to samples/myproject
- execute hcenv.bat|sh once (. hcenv.sh on Unix).
- run hc -course <courseId> -o <outputDir> (see all options by typing just 'hc')

You may see warnings, in particular if you have not configured HTMLDOC. 
On serious errors the hc will terminate.

You may also generate a lightweight HTML menu using the -lite option

When developing it is often desirable to generate a single module and even single lesson.
This can be done using the -module and -lesson options

Developing your own courses
---------------------------
Define your own PROJECT_HOME. Best is to initially make a copy from 
./samples/myproject and work from there. In the ./doc directory is
tutorial material.


Version info
------------
see VERSION

Planned modifications
---------------------
see TODO

License info
------------
see LICENSE

Author/Contact
--------------
Just van den Broecke
Just Objects B.V.
just@justobjects.nl

Contributors;
Gerald de Jong
Beautiful Code B.V.
gerald@beautifulcode.nl

Jacco Kok 
0XCAFEBABE
jacco@beautifulcode.nl

see also:
www.justobjects.nl
www.cowcatcher.org