SQL Documentation Capabilities of ASPHelp

Users of Pikauba Software's SQLHelp product have had the capability of documenting the intent behind stored database procedures, but the capability of indicating their usage in the ASPHelp projects has previously been lacking. Beginning with ASPHelp 1.6, linkage is present, providing SQLHelp is installed on the same computer. Version 2.0 of ASPHelp extends the linkage to include DBDocumentor™ thus effectively providing a means to refer to any aspect of the database as it may be used in an ASP page.

SQLHelp Capabilities

For those who may not be fully aware of the SQLHelp product; it is able to parse the SQL batch scripts that create the stored procedures used in a dynamic web site and produce developers reference documentation on those procedures. Like ASPHelp, SQLHelp has a rich set of annotation options available to it. With SQLHelp you can document the intent of the procedure, all the parameters passed, and all the various return values including result sets.

DBDocumentor™ Capabilities

For those who may not be fully aware of the DBDocumentor product; it is able to parse the SQL batch scripts that create and manipulate the database for your dynamic web site and create reference documentation for the database. Like ASPHelp and SQLHelp, DBDocumentor has a rich set of annotation options available to it. With DBDocumentor you can document to the intent of stored procedures and data views which may be used in the web page and from that form a more complete view of the web functionality as implemented. To learn more about DBDocumentor, please click here.

Integrating ASPHelp and SQLHelp/DBDocumentor™

Integration of SQLHelp/DBDocumentor and ASPHelp is done at the ASP level. That is to say, all ASP files referencing SQL objects have directives indicating which SQL objects are used in a given file. ASPHelp labels these directives the ##SQL tag. During processing ASPHelp loads the SQLHelp/DBDocumentor project file you specified, and applies the SQLHelp/DBDocumentor project settings. During final compilation, ASPHelp will generate the required HTML directives to merge the SQLHelp/DBDocumentor project and the ASPHelp project, and the linkage is complete.

All that is required is for the ASPHelp output file and and SQLHelp/DBDocumentor output file to be located in the same folder for the final merge to be operational. The resulting documentation allows users to browse and search both projects using the full capabilities of the HTML Help viewer.

Requirements

For successful merging of projects to occur, there are a few guidelines to follow:

You must have ASPHelp 1.6 or greater
You must have SQLHelp 1.6 or greater (version 1.7 or greater recommended)
If you are working with unregistered (shareware) versions of either ASPHelp or SQLHelp/DBDocumentor, you may run into problems with the merge process due to the limitation on the number of files in the unregistered versions.
The output folder for both the ASPHelp and SQLHelp/DBDocumentor projects must be the same.
When you distribute the final help files, they must be located in the same folder for proper merging to occur
If you are working with a case sensitive database, your usage of the SQL tag must also be case sensitive
If you are working with DBDocumentor, you will need to have selected SQLDocumentation™ as an output option. SQLDocumentation is a XML representation of the database, and is present in DBDocumentor 3 and higher.