Software Documentation Toolkit Files

Source Documentation Toolkit (SDToolkit) Readme
-----------------------------------------------

Version: 0.4.8a

Copyright
---------

SDToolkit is held under the LGPL see copyright.txt and license.txt for
copyright and license information.


Getting Started
---------------

1. Download one of the following files from
http://sourceforge.net/projects/sdtoolkit.
- sdtoolkit.zip is an executable jar file with a zip extension which
includes both pasdoc and vbdoc.
- sdt_pasdoc.zip is an executable jar file with a zip extension
containing pasdoc.
- sdt_vbdoc.zip is an executable jar file with a zip extension
containing vbdoc.
- sdtoolkit.exe is a windows executable which can process both pascal
and VB source.
- pasdoc.exe is a windows executable which can process pascal source.
- vbdoc.exe is a windows executable which can process VB source.

2. (zip files only) Optionally extract the zip file to somewhere on
your system.

3. Optionally create a pasdoc.conf and/or vbdoc.conf somewhere on your
system path or your current work directory.

Edit the filelist entry to include the files you would like to examine.
Use the '\\' or '/' path separator instead of '\' and separate multiple
entries with a comma. Wildcards are supported.

Here is an example config file:

	# A comment
	debug=1
	filelist=*.pas

This file instructs the toolkit to turn on debuging and process all
files in the local directory ending with .pas.

4a. To execute from extracted directory structure (from step 2) type
something like:

  [java executable] [classpath inc. dir. where zip file extracted]
      bjsoftware.pasdoc.Main [additional args]

or

  [java executable] [classpath inc. dir. where zip file extracted]
      bjsoftware.vbdoc.Main [additional args]

4b. To execute from zip:

  [java executable] -jar [name of zip file] [additional args]


Command Line Arguments
----------------------

All command line arguments are the same as those found in the .defaults
and .conf property files and have the form:

  --[arg name]=[value]

reader - An alternate DocReader to read the source files.
writer - An alternate DocWriter to extract the data from the created
	DocObjects and produce output.
debug - Set to 1 to write debug/stack trace information to System.err.
errorlog - A file to redirect System.err to.
copyfiles - Copy any associated files, ie style sheets to destination
	directory.
copyfilelist - An alternate comma separated list of associated files to
	copy to destination directory. Wildcards are supported.
extension - Extension to append to output files, for example: afile.pas
	becomes afile.pas.<extension>.
headertext - Text to be placed at the front of each output file.
footertext - Text to be placed at the end of each output file.
readerproperties - Name of a file holding additional properties to be
merged with the current reader's properties
writerproperties - Name of a file holding additional properties to be
merged with the current writer's properties
filelist - A comma separated list of source files to process, defaults
	to System.in in which case output will be to System.out. Wildcards
	are supported. See note above (Getting Started: Step 3).


Additional Arguments
--------------------

-copyright - display copyright and exit
-readme - display this readme file and exit
-version - display version and exit


Additional Arguments for sdtoolkit (all formats)
------------------------------------------------

The following two arguments are also supported only when executing from
the sdtoolkit.zip archive or sdtoolkit binaries:

-vb - Process source files as VB source.
-pas - Process source files as pascal source.

These flags can be modified or redirected to different handlers via the
sdtoolkit.properties file. Addtional flags and handlers can also be
declared via this file. An entry in sdtoolkit.properties has the form:

pas=bjsoftware.pasdoc.Main

This informs sdtoolkit to call bjsoftware.pasdoc.Main.main when -pas is
specified and also to call bjsoftware.pasdoc.Main.canHandleFile to
determine which parser to use when no argument is given.


Change Log
----------
v0.4.8a
-------
Special bug fix release which fixes a crippling bug (669118) in
VBParser. This bug caused the parser to fail when parsing normal
VB source (ie not VBScript) with no document sections. See project
home page for more details.

v0.4.8
------
- Corrected bugs (661597, 665039, 665041, 665042) in pasparser.
- Corrected bug (665040) in pasdoc.xsl.
- Corrected bugs (665048, 665353, 665566) in vbparser.

v0.4.7
------
- Copy file list in pasdoc and vbdoc completely soft coded in config
files.
- Corrected bug (658143) in pasparser.
- Corrected bugs (658180 and 658181) in vbparser.
- Included external references in function declarations in xslt files.
- -vb and -pas are now optional, if not included sdtoolkit determines
which parser to use based on file extension and/or file snooping.
- Parsers used and related "file type" flags (i.e. -vb) are now soft-
coded in sdtoolkit.properties.

v0.4.6
------
- Simplified second pass in pasparser and VBParser, in theory this
should increase performance.
- Removed tar.gz files from release.
- Completly revamped xsl files to give cleaner output.

v0.4.5
------
- Added VBScript support (not ASP) to VBParser.
- Minor tweeks.

v0.4.4
------
- Fixed a couple of bugs.
- Made bjsoftware.pasparser.pasparser slightly more efficient.
- Made significant optimisations to bjsoftware.vbparser.vbparser.

v0.4.3
------
- Initial release of SDToolkit on Sourceforge.


For further documentation and updates visit http://sourceforge.net/projects/sdtoolkit.