System Requirements
The ASP Documentation Tool™ is written in Perl 5, but has been compiled into a Windows executable file that can be used on any machine without requiring Perl.
If you want the ASP Documentation Tool™ to create a report in HTML Help format then you will need to download and install the HTML Help Workshop. This is a free download from Microsoft.com. It is strongly recommended that you install the HTML Help Workshop to the default location, which is C:\Program Files\HTML Help Workshop. If the HTML Help Workshop is installed elsewhere then the ASP Documentation Tool™ will need to be modified to change the value of the variable called "HTMLHelpProg".
Configuring and Running the ASP Documentation Tool™
The ASP Documentation Tool™ is installed using a standard Windows installation routine. There is a graphical user interface - The ASP Documentation Tool™ Configurator - for configuring documentation jobs.
The ASP Documentation Tool™ executable file must be supplied with several command line options which control the behaviour of the script and the appearance of the output report. There are just two mandatory command line options, which are used to specify the input folder (i.e. the folder containing the ASP files that are to be documented) and the output folder (i.e. where the report should be placed).
| Option |
What it does |
Example |
| --i |
Input folder containing the website's files. Use a vertical bar to specify more than one input folder (useful if your includes are in a separate location). |
"C:\inetpub\wwwroot\mywebsite", or
"C:\Inetpub\wwwroot\SampleWeb|C:\Inetpub\wwwroot\includes" |
| --o |
Output folder where the report should be placed |
"D:\reports\mywebsite" |
So the following command when typed in the folder in which the ASPDocumentationTool.exe resides would document the web project in C:\inetpub\wwwroot\mywebsite and output the report in the folder D:\reports\mywebsite:
ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite"
Note that the script will overwrite a previous report in that folder.
The following command line options are optional:
| Option |
What it does |
Example |
| --v |
Verbose mode outputs script status to console. |
0 or 1 |
| --cs |
Specifies whether the source code of ASP pages and SQL stored procedures should by color coded and syntax highlighted. |
0 or 1 |
| --h |
Whether entities in the source code should be hyperlinked. |
0 or 1 |
| --c |
Whether entities in the source code should be color coded. |
0 or 1 |
| --l |
Whether the source code pages should display line numbers. 1 = numbering, 0 = no line numbering. Numbering is on by default. This is a useful option if you want to use the ASP Documentation Tool™ to create syntax highlighted ASP for publication purposes (like I do on my own ASPAlliance site!) |
0 or 1 |
| --txt |
Whether the report should be exported as plain text format (using the filename "projectname".txt). |
0 or 1 |
| --dsn |
Connection string allowing script to access a SQL Server 2000 database. At the very least this should contain the name of an ODBC data source, together with a SQL Server username and password. |
"DSN=Northwind;UID=webuser;PWD=Htf674HHs" |
| --db |
name of database to document. Use a vertical bar to specify more than one database. |
"Northwind", or
"Pubs|Northwind" |
| --hh |
Whether the output should be compiled in HTML Help format. |
0 or 1 |
| --project |
Specifies a name for the project. |
"SampleWeb" |
As an example, the ASP Documentation Tool™ could be called from the command line using:
ASPDocumentationTool.exe --i="C:\inetpub\wwwroot\mywebsite" --o="D:\reports\mywebsite" --cs=1 --v=0 --hh=1 --project="SampleWeb"
Don't forget that it is possible to run the ASP Documentation Tool™ on Windows machines from .bat scripts, which can of course be scheduled using the AT command or the Windows Task Scheduler.
The ASP Documentation Tool™ reports are created in standard HTML, which can be subsequently edited using any HTML editor. The HTML Help format output may also be edited by using Microsoft's HTML Help Workshop - the HTML Help Workshop project file is created in the output folder along with the rest of the report, and it has a .hhp file extension.
Figure 3. Microsoft's HTML Help Workshop can be used to modify the HTML Help report.
The ASP Documentation Tool™ creates a log file in plain text format [view sample].
