The ashkelon command-line tool is called "ashkelon". It is a wrapper shell script for a Java program. On win32, the file is "ashkelon.bat" while on unix it's "ashkelon." These files reside in $ASHK_HOME/bin
You will primarily use the ashkelon tool to add content to your database. Here is a listing of some of the subcommands:
use to add APIs to your database
use to "nuke" the contents of the database (start from scratch)
lists the APIs currently documented in the database
opposite of ashkelon add, use it to remove APIs from the repository
You can obtain a listing of all the subcommands by invoking ashkelon with no arguments. For help per subcommand, invoke ashkelon like this:
ashkelon subcommandname -h
ashkelon reset and ashkelon list require no parameters and likewise require no explanation.
ashkelon add is richer. Let's talk about "ashkelon add".
Traditionally (i.e. with javadoc) one documents a single API. So the inputs to the javadoc tool are a list of package names, such as {java.lang, java.io, java.net, ..}
When documenting multiple APIs in a single repository, it's important to also keep track of what API each java package belongs to. That is, org.apache.tools.ant is part of the ant API whereas org.apache.log4j is part of the log4j API.
The ashkelon project has devised a simple XML structure to describe an API. Here's an example API XML file for DOM4J (see apis/dom4j.xml):
Example 4.1. DOM4J API XML file descriptor for ashkelon
<?xml version="1.0" encoding="UTF-8"?>
<api>
<name>dom4j</name>
<summarydescription>The flexible XML framework for Java</summarydescription>
<description>dom4j is an easy to use, open source library...</description>
<publisher>SourceForge</publisher>
<download_url>http://www.dom4j.org/</download_url>
<release_date>2005-04-15T08:00:00</release_date>
<version>1.6</version>
<packages>
<package>org.dom4j</package>
<package>org.dom4j.bean</package>
<package>org.dom4j.datatype</package>
<package>org.dom4j.dom</package>
<package>org.dom4j.dtd</package>
<package>org.dom4j.io</package>
<package>org.dom4j.jaxb</package>
<package>org.dom4j.rule</package>
<package>org.dom4j.rule.pattern</package>
<package>org.dom4j.swing</package>
<package>org.dom4j.tree</package>
<package>org.dom4j.util</package>
<package>org.dom4j.xpath</package>
<package>org.dom4j.xpp</package>
</packages>
<repository>
<type>cvs</type>
<url>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/dom4j</url>
<modulename>dom4j</modulename>
<sourcepath>src/java</sourcepath>
</repository>
</api>
This file is similar to the package.html file that you usually have to write for javadoc package documentation. Except that this file is xml-based and thus more structured, and easier to interpret by a program.
These xml api descriptors are the primary input to the ashkelon command (aside from the actual source code that you're trying to document). Many descriptors already exist in in ashkelon's apis directory.