Overview ASPHelp

Overview

ASPHelp

Welcome to ASPHelp, the Active Server Pages (ASP) documentation tool from Pikauba Software. ASPHelp allows ASP developers, QA professionals, and information architects the ability to document the paths of execution, including parameters passed for their ASP. ASPHelp produces industry standard HTMLHelp documentation familiar to virtually all developers working with Microsoft toolsets. In documenting the pages as you design them, and by defining an interface contract for your pages, you can ensure the stability and reliability of you web application.

The rich feature set and simple user interface allows the developer a simplified method for creating the documentation. The tag replacement capability permits "document as you go" methodologies.

The benefits of ASPHelp are numerous and range from; decoupling the ASP and object development, to facilitating coding standards adherence, to providing production quality documentation for web report writers.

Important Note: Since this documentation is available for separate download from the ASPHelp product, it contains its own licensing agreement. If you are running this documentation from within ASPHelp itself, you can safely ignore this section, otherwise, please view the licensing agreement here.

© Pikauba Software 2001 - 2005. All rights reserved.


ASPHelp - Benefits

Overview ASPHelp

Benefits

The ASPHelp system offers numerous benefits to ASP developers, QA professionals, report writers, and information architects. It can be used to ensure that a quality web application is developed by documenting the interface to each page in the system.

Benefits to the Information Architect

The information architect is generally charged with defining the flow of the web application. They will describe each page, where the page transitions are, and the information that is collected and displayed on each page. The challenge is transferring the architecture to the actual developers building the application.

Enter ASPHelp. With ASPHelp, the information architect can place stub documentation for the entire interface to the page into an empty ASP file that the developer can build out. The IA can describe each page transition of the flow, including error conditions. They can define the anchors on the pages, the various forms that may be present, even the expected means of accessing data across pages. They can define all the input variables, including what they mean, and if they are part of a form, or are a query parameter. Repeat this process for each page in the application, and you have the flow of the web application completely defined before a single line of code is written. All the ASP developer needs to do is transfer the interface into ASP, then marry the ASP to HTML for display.

Benefits to the QA Professional

QA professionals provide an incredibly valuable service to the web application development effort, but are frequently operating with less than ideal levels of information as to the desired behavior of the site they are working with. To help deal with this strain, they often resort to using tools to characterize the site and hopefully glean this missing information.

One of the most common tools used is the spider. This tool literally crawls the site listing out the various links encountered. Unfortunately, the spider can only look at one possible representation of a site. If the site is personalized, and that personalization extends to the actual pages displayed to the user, the spider will not be able to list all paths of execution. There is no way for the spider to actually know the intent behind the page, or for it to know if all the expected parameters are being passed to any given page. It merely documents what is. How then can the QA professional determine if they have spent sufficient attention to a given page?

Enter ASPHelp again. By taking the interface contract defined by the information architect, the QA professional can determine the intent behind each page, and each parameter in the page. If the information architect documented everything prior to development, then the QA professional can be developing their test cases and determining effective coverage plans before the application is even close to being completed.

Once the web application is delivered to QA, the QA professional can run ASPHelp against the delivered code and can compare the defined interface to the implemented interface, perhaps uncovering missing parameters, new parameters, or new pages.

Benefits to Report Writers

Report writers are often working to determine how a site is being used. They have tools that pour through the web logs generated by the web application looking for trends that can be used to the site owners advantage. This task is made easier if the interface to the pages is defined. Things like the use of cookies or parameters passed by querystring (GET), are important. The interface contract established by the information architect is invaluable to a report writer, but often the interface contract is defined as an after thought.

ASPHelp can resolve this inconsistency by allowing the report writer to run ASPHelp against the web application and using it to determine those parameters expected by a given page. They then can use this information to minimally define the list of expected parameters, but additionally to inquire from the web developer as to each unknown parameters' meaning.


ASPHelp - Documentation Features

Overview ASPHelp

Features

The ASPHelp system possesses a large number of features designed to assist web application development staff in the production of professional quality HTMLHelp documenting the web application. This documentation can then be used to reduce the number of defects present in the system by ensuring the interface contracts defined are followed.

Documentation items include the ability to:

  • Fully define the default behavior for HTML elements and redirections.
  • Describe cookie keys and their purpose.
  • Describe input form parameters.
  • Describe input Query String parameters.
  • Describe generic input request parameters. Generic parameters allow the developer to read the value of a parameter from either the Forms, QueryString, or Cookies collections without specifying which collection. Bugs can often surface when the a page can be accessed both by GET and POST, but the page developer has not taken appropriate action to guard against duplicate parameters.
  • Describe session variables.
  • Describe project specific session object names.
  • Describe project specific default property names for the custom session object.
  • Describe application variables.
  • Process global.asa
  • Describe redirections in the output.
  • Describe anchors.
  • Describe anchor variables
  • Describe forms, and their destination.
  • Describe HTML form variables.
  • Optionally include the source for a page.
  • Optionally recurse into include files, and optionally include their source
  • Specify the physical location of virtual include folders
  • Describe image maps
  • Describe image map areas and associated query string variables
  • Describe frames and inline frames (IFrames)
  • Document static HTML and SHTML files in addition to ASP files
  • Describe project specific copyright notices.
  • Describe project specific project file descriptions.
  • Describe the purpose of the web page.
  • Optionally launch the compiled help file
  • Optionally include only the tags defined in the file. This option allows the information architect the ability to define the interface to the page without having the code present.
  • Determine which of the interface elements (e.g. cookies, forms, QueryStrings, etc) are to be included in the compiled help.
  • Provide hyper links in the redirections, anchors, and forms listings to allow the user the ability to navigate a potential path of execution. The option is designed to facilitate the work of the QA professional in determining appropriate test cases for the web application.


Documentation Procedures

Documentation Procedures ASPHelp

What attributes of ASP and HTML files are documented by ASPHelp?

Looking at the sample output, this manual and running ASPHelp against some sample projects may not answer this fundamental question. This section seeks to describe those attributes and how they are documented within ASPHelp. If there is an aspect you are seeking, please don't hesitate to contact us, it may already be in the product, or may be planned for a future version.

Web page interfaces

In traditional object oriented programming, the interface is the public view of the object being exposed. Using web concepts, an interface is the public view of the variables accepted by an ASP page, the hyperlinks present on a web page, or the forms present on the web page. Each of these items is responsible for generating data, or processing user inputted data.

In most web projects, the end user has no knowledge, and no requirement to know the interface exposed by the ASP page. This isn't true for developers or testers who are responsible for knowing what types of data the ASP page is expecting. Using object oriented terminology, each web page becomes an object, and the data flow between pages is key to proper site operation.

ASPHelp defines interface elements as those which pass data from one page to another. This definition includes anchors, forms, frames, image maps request object methods and redirections.

The following interface items are listed in the default table of contents for ASPHelp generated documentation.

  • Page processes data submitted from a FORM POST
  • Page collects data via a FORM
  • Page processes data submitted via FORM GET, or on the query string
  • Page processes data submitted via both the POST and GET methods
  • Page accesses or modifies the cookie collection

ASPHelp will list the name of the variable for all data access items (POST, GET and cookies), and if any description is supplied with the variable, that description will be included with the variable in the output document.

For more information on documenting interfaces, click here.

Client side script interfaces

Dynamic web content is not only controlled by the HTML data flow, but client side script has the potential to intercept, and modify the data content. In addition, client script has the ability to present web dialog pages, open new windows in response to client actions and control user navigation. While the end user generally has limited knowledge of the presence of client side script, they do have the ability to control script execution; including disabling all script access, or installing applications which render certain client script functionality inert. As a result, developers and testers can benefit greatly from determining the extent to which the web site content can be affected by the end user's configuration.

Client side interface elements are defined as those which result in a change in navigation. The default table of contents includes web dialogs.

ASPHelp provides the following information on all web dialogs:

  • An index of the location of the dialog in the HTML. Support is provided for supplying a description of the intent of each dialog.
  • The location accessed to display the dialog
  • The modality of the dialog
  • A list of the parameters passed to the page displaying the dialog. ASPHelp will attempt to determine the values processed, and where they are supplied from (e.g. the value is defined based on the client or server side). Descriptions for the intent behind each variable is supported.

ASPHelp provides the following information on all client navigation requests:

  • An index of the location of the window in the HTML. Support is provided for supplying a description of the intent of each navigation.
  • The location accessed to display the content
  • The target of the new content. In the case of simple navigations (e.g. window.navigate), this value will be "Self"
  • A list of the parameters passed to the page displaying the new content. ASPHelp will attempt to determine the values processed, and where they are supplied from (e.g. the value is defined based on the client or server side). Descriptions for the intent behind each variable is supported.

For more information on documenting client script interfaces, click here.

Server side data manipulation

Most dynamic web sites are driven with server side processing of client side requests. In order to maintain system and user state, these sites make use of application and session caches of some form. Depending on the user's actions, server side redirections can also occur. ASPHelp is able to document the contents of the intrinsic ASP Application and Session objects. If your web site makes use of a custom session object, you can optionally specify the custom session object, and ASPHelp will attempt to document session object usage of the custom object.

ASPHelp will list the name of the variable for all application and session object variables used, and if any description is supplied with the variable, that description will be included with the variable in the output document.

For more information on documenting server side data manipulation, click here.

HTML action elements

HTML action elements are those items in the HTML specification which cause an action to occur on the web page. These are the items an end user is normally interacting with, and which users assume cause site navigation to occur. In the case of dynamic web pages, the actual action elements available to the user will change with previous user actions (e.g. removing an item from a comparison list), user identity (e.g. personalized web sites), current server configuration (e.g. contents of Application variables), and the browser chosen by the end user (e.g. an older browser not supporting certain functionality).

ASPHelp defines the following items as HTML action elements:

  • Anchor tags
  • FORM elements
  • FRAME elements
  • IFRAME elements
  • Image map and area tags.

The following items are documented for anchor tags:

  • If the anchor is a label, ASPHelp will attempt to determine the first 10 words of the label and use those ten words for the anchor name. The anchor will be categorized as a label
  • If the anchor link is textual, ASPHelp will show the text
  • If the anchor link is a clickable image, ASPHelp will show the name of the image, its source and title.
  • The target for the anchor
  • The href for the anchor. Any query string values passed with the href are documented.
  • The contents of any OnClick event for the anchor

The following items are documented for FORM elements:

  • The name of the FORM element.
  • The action and method of the FORM element.
  • Any INPUT, SELECT and TEXTAREA elements contained within the FORM

The following items are documented for FRAME and IFRAME elements:

  • The name of the FRAME
  • The source for the FRAME. Any query string values passed with the source are documented

The following items are documented for MAP and AREA elements:

  • The name of the MAP
  • The href for the AREA. Any query stringvalues passed with the href are documented.

For more information on documenting HTML action elements, click here.

Procedural object and method usage

Procedural objects are methods and objects present in either the server side or client side script. ASPHelp documents the following procedural objects and methods:

  • Server.CreateObject
  • CreateObject (server and client side VBScript)
  • ActiveXObject (server and client side JavaScript)
  • new object creation in JavaScript
  • HTML OBJECT element
  • HTML METADATA element describing a type library
  • Private Function and Sub declarations (server and client side VBScript)
  • Public Function and Sub declarations (server and client side VBScript)
  • JavaScript function declarations

The following items are documented for Server.CreateObject calls:

  • The ProgID of the object being created
  • The name of the server where the object is being created (if specified)

The following items are documented for CreateObject and ActiveXObject calls:

  • The ProgID of the object being created
  • The name of the server where the object is being created (if specified)
  • The location of the creation (client or server side)

The following items are documented for objects created in JavaScript using the new keyword:

  • The name of the class being created
  • The location where the class is being created (client or server side)

The following items are documented for HTML OBJECT elements:

  • The name and id of the element
  • The ProgID of the element, if specified
  • The CLSID of the element, if specified
  • The MIME type of the element, if specified
  • The scope of the call
  • If a codebase is specified, the codebase location and code items are included
  • If a data source is specified, the location of the data source is included

The following items are documented for HTML METABASE elements describing type libraries:

  • The object name
  • The UUID of the type library
  • The version of the library
  • The file to obtain the library from

The following items are documented for all procedural method declarations:

  • The type of procedure (e.g. Private Sub)
  • The execution context of the procedure
  • If there is an event associated with the procedure, which object the event is associated with
  • If the procedure accepts parameters, the name of each parameter and if it is passed by reference or value is included.
  • If source code is included in the output document, a hyperlink will be present from the summary page to the source code page location where the procedure is defined.

For more information on documenting method and object usage, click here.


ASPHelp Command line options

User Interface ASPHelp

Command Line Options

To support the batch documentation of SQL databases, as would be present in build scripts, ASPHelp has a command line version. This command line version, or console version, has the filename of ASPHelpConsole.exe. ASPHelpConsole will only operate if ASPHelp has been registered. If you attempt to execute ASPHelpConsole.exe while running in shareware mode, ASPHelpConsole will exit immediately with an error informing you of the registration requirement.

Please note that running ASPHelpConsole.exe and running ASPHelp.exe will produce exactly the same output file.

Usage

ASPHelpConsole takes several command line parameters.

ASPHelpConsole.exe -f[:]ProjectFile [-d[:]0/1] [-o[:]OutputPath] [-L[:]LogPath] [-e[:]ErrorLevel] [-p]

Where ProjectFile is the fully specified path, including filename, to the ASPHelp project file. If the path resides on a network share, please ensure that the user running the command line compilation has access rights to network share.

0/1 is a flag (default of 0) indicating if the HTML Help output should be launched when the compilation completes. This value always overrides the value specified in Step 2 - Output options.

OutputPath is a fully specified path, including filename, to the output file to produce, if different than that contained in the project file. If the file resides on a network share, please ensure that the user running the command line compilation has write access to the network share. The path can specified relative to the working folder.

LogPath is a fully specified path to an optional processing log file. If the file resides on a network share, please ensure that the user running the command line compilation has write access to the network share. The path can specified relative to the working folder. If the file can not be created, processing of the project will still occur.

ErrorLevel is an optional value corresponding to the level of detail to be contained in the output log file. Regardless of the error level, certain errors which would impact the quality of the output will always be displayed. It must be expressed as a decimal value.

Specifying the P option will cause the output log file to be piped to the console (stdout).

Specifying no options will cause ASPHelpConsole to display a usage screen to the console window.

ErrorLevel Values

The ErrorLevel value is any combination of the following values. It must be expressed as a decimal value.

1 | Show the current file being processed
2 | Reserved. Does not affect output.
4 | Show the script, include, or element name currently being processed.
8 | Reserved. Does not affect output.
16 | Show any parameters passed to an element (e.g. query string or form variables)
1024 | Show the CHM compilation output from hhc.exe

Return values

ASPHelpConsole will report any errors to the console window in which it is running. It will also return an error number (errorlevel) to the console. Valid errorlevel values are:

  • 0 Indicates a successful run, but also indicates that the usage screen was returned
  • 1 An internal error was encountered. This value was not written to any log file, but was printed to the console window
  • 2 A standard processing error occurred. The error message may have been written to a log file, but was also printed to the console window.
  • 3 The ASPHelp processing engine was not correctly registered. An error message was returned to the console window.

All error messages returned to the console window are sent to stdout not stderr.

© 2001 - 2005 Pikauba Software. All rights reserved.


ASPHelp.ini

The ASPHelp.ini file is a simple text file that you should create in the root folder selected in step 2. This file is used to contain project specific information.

The functionality of ASPHelp.ini is also supported within global.asa. All tags that are valid for ASPHelp.ini are also valid for global.asa.

If you choose to place project level tags within either global.asa or ASPHelp.ini, please do not duplicate them in the opposite file. To do so may result in duplicate text in the compiled output.

Note: If you wish to use XML project files, please include a file named ASPHelp.xml in same folder where the .ASPHelp file is placed. Normally this folder would be the same as where global.asa would be placed.


Global.asa

Global.asa is a centralized application configuration file for ASP applications. It is only logical that ASPHelp consider this file to be a central location for the various tags that govern the project. All tags that are used within ASPHelp.ini are valid within global.asa. Additionally, global.asa is also available for normal processing allowing effective documentation of application variables.

Note: If you use global.asa to document project settings, you may wish to avoid using ASPHelp.ini to reduce the possibility of duplications.


Trouble Shooting

Overview ASPHelp

Troubleshooting the system

This page is a collection of items that have been shown to come up in the installation or operation of the system.

Installation

1. The system is designed under Microsoft Visual Basic® system. In order to run properly, the system needs to have Service Pack 4 installed. If it is not installed, the DLLs will be updated. Running the Setup application will normally take care of this step automatically.

2. The system also needs to have the Windows Script Host installed. The current version can be obtained from Microsoft at: http://msdn.microsoft.com/scripting/

3. Under no situations should the files located in the installation directory be modified. These files are encrypted, and if modified will cause the system to perform poorly at best, or not at all at worst.

4. You need to have the HTML Help Workshop installed on your system for the application to compile an output file. If this is not installed, you may experience errors in the application during its final phase. The current version of the HTML Help workshop can be obtained from Microsoft at: http://msdn.microsoft.com/library/default.asp?URL=/library/tools/htmlhelp/chm/hh1start.htm

Compiled Output Errors

The majority of errors associated with the compiled HTML output can be traced to misreads of the ASP or associated HTML. Most of these can be solved using the ##OV tag. The remainder are described here.

1. No output file is generated.

Verify that the HTML Help Workshop from Microsoft® is installed.

Note that this situation may also manifest itself as a warning error box at the end of compilation of the project.

2. The project name is incorrect.

The project name is determined by the destination file name chosen in step 2. If the name is incorrect, then verify you've chosen the correct name.

3. How do I remove the Pikauba copyright?

If you are not seeing your organizations copyright notice (as defined in the ##CO tag) at the bottom of the pages then you are working with an unregistered version of the software. When you register the software, this notice is removed.

4. How do I remove the document preparation copyright?

The Pikauba copyright notice stating that this document was prepared by a Pikauba software product can not be removed. If the presence of this copyright notice posses an issue for your organization, please contact Pikauba.

5. I do not see any project definition or copyright notices.

Copyright and project definition information may only be present in the ASPHelp .ini files. If the file is not present, then no information can be obtained. Placing the ##PR and ##CO tags in any other location will cause them to be ignored.

6. Only 20 files are processed, but I've included many more.

The shareware version of the software only processes the first 20 files that are included. When you register the software, this notice is removed.

Note that this situation may also manifest itself as a warning error box while adding files to the included file list.

7. I'm working with the shareware version, and some of the anchors, redirects, and HTML forms have broken links.

As mentioned previously, the shareware version will only process up to 20 files per run. Previous versions of ASPHelp would not make an effort to determine if the file being referenced was in the project or not which frequently resulted in broken links. With ASPHelp 2.0 and higher this should no longer be a problem, and if you are still experiencing it, please contact our support department at support@pikauba.com.

8. I have defined SQLHelp linkage, but all I get are broken links when I click on the stored procedure name I've entered.

This can happen for a variety of reasons.

  • A simple typographical error is present in either the name of the procedure entered with the SPL tag, or with the actual procedure name.
  • The named procedure is not actually in the SQLHelp project
  • If none of the stored procedures are listed, the SQLHelp output file and the ASPHelp output file may be in different folders. HTML Help files are merged at runtime and thus all files to be merged must be in the same folder.
  • The name of the procedure contains a user access qualifier (e.g. dbo.spName). If the stored procedure as it is known to SQLHelp uses such a qualifier, then the SPL tag must as well
  • The database is case sensitive and the case of the procedure name in the SPL tag does not match that of the actual procedure


ASPHelp - Error Messages

Overview ASPHelp

Error messages

In the course of ASPHelp operation, you may experience a number of popup messages boxes. These message boxes are intended to provide users with the information they need to resolve issues arising during ASPHelp execution. If you find an error message that does not guide you in the correct direction, please consult the troubleshooting guide, or send an email to our support staff at support@pikauba.com.

Configuration Warning

ASPHelp has been designed to run on Windows95, Windows98, Windows ME, Windows NT 4.0 SP3 and above, and Windows 2000, so the probability that you do not have a version of Internet Explorer installed on your system is fairly remote. If you have gone to the difficulty of removing all instances of Internet Explorer from your system, you will not be able to view compiled HTML Help files due to the HTML Help file viewers' dependency upon Internet Explorer.

Please note that ASPHelp does not require you to set your default browser to Internet Explorer, rather a version of Internet Explorer must be installed on your system.

Note also that the absence of Internet Explorer does not affect the systems' ability to correctly process you ASP files.

This error message may appear at ASPHelp system startup.

Which Version of IE?

We would generally recommend IE 4.02 or higher. This is due to various issues including support for DHTML, and resolution of various Y2K bugs that were present in previous versions.

ASPHelp Validation Error

Input folder validation

If you elect to enter a folder name for the input folder directly, rather than browsing for it, you may inadvertently enter a folder that does not exist. This warning indicates just that situation.

This condition is validated when the next button is pressed on step 2.

Output folder validation

If you elect to enter a folder name for the output folder directly, rather than just browsing for it, you may inadvertently or intentionally enter a folder that does not exist. This warning indicates just that situation. If you accidentally entered an incorrect folder, simply press No and update the folder name (perhaps to the extent of browsing for it). If you intentionally entered a folder name that does not exist, pressing Yes will instruct ASPHelp to attempt to create it. If no system error message occurs, the folder has been created.

This condition is validated when the next button is pressed on step 2.

ASPHelp Evaluation Warning

While in evaluation mode (i.e. not yet purchased), ASPHelp has certain limitations. One of these limitations is the number of files it will process. Previous versions were limited to 10 files in evaluation mode, but that has been increased to 20 files beginning in version 1.1. Pikauba Software feels that generating compiled help against a 20 file project provides sufficient data points with which to properly evaluate ASPHelp.

You will see this warning whenever you attempt to add more than 20 files to the project while running in evaluation mode.

Compilation Error - Missing Microsoft HTMLHelp Compiler

This error message will occur after all processing has occurred if your system does not have the requisite Microsoft HTML Help compiler installed. The current version of the HTML Help compiler can be obtained from Microsoft at: http://msdn.microsoft.com/library/default.asp?URL=/library/tools/htmlhelp/chm/hh1start.htm

The required files to generate the output have been created, so once the HTML Help compiler is installed, you have the option of either re-running ASPHelp, or simply running the .hhp file located in the output directory.

ASPHelp Internal Exception

If ASPHelp encounters an internal error it generally will present a message box similar to the one shown above. If you encounter such a box, the indicated file has encountered a processing error that will prevent its inclusion in the final output file. The reason is also indicated. Generally this information is helpful to Pikauba support personnel. If you elect to contact Pikauba support at mailto:support@pikauba.com, please include the error message and a detailed description of what your system configuration is.

You are presented with the option of continuing processing. If you elect to continue, the file which experienced the error will be skipped, but other files will be included. If you elect to not continue, ASPHelp will exit.


Documentation options

In step 2 of the ASPHelp user interface, you have the opportunity to define the various documentation options to use for this project. The options are broken down the categories of HTML, ASP and Request options.

ASP Options

The ASP options indicate which types of internal ASP operations to include in the output file. Only those items listed are available for inclusion, and the file type plays no role. Thus for example if you have files with an extension of HTML, but which really are ASP files, these ASP tags remain valid. If you elect to not include a given ASP construct, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the ASP constructs to include. If a given ASP construct is not selected for inclusion, any documentation tags relating to it will be ignored.

View the ASP documentation tags.

HTML Options

HTML options indicate which types of HTML elements you wish ASPHelp to include in the output file. Only those tags listed are available for inclusion, and the file extension or type plays no role in the determination. If you elect to not include a given HTML element, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the HTML elements to include. If a given HTML element is not selected for inclusion, any documentation tags relating to it will be ignored.

View the HTML documentation tags.

Request (Interface) Options

The request or interface options define which inbound data flow types to include in the project. If you elect to not include a given request collection, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the request collections to include. If a given collection is not selected for inclusion, any documentation tags relating to it will be ignored.

Note: Selection of the Cookies option will enable documentation of the Response.Cookies collection for documentation.

View the interface documentation tags.


ASP Options

The ASP options indicate which types of internal ASP operations to include in the output file. Only those items listed are available for inclusion, and the file type plays no role. Thus for example if you have files with an extension of HTML, but which really are ASP files, these ASP tags remain valid. If you elect to not include a given ASP construct, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the ASP constructs to include. If a given ASP construct is not selected for inclusion, any documentation tags relating to it will be ignored.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix if _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

ASP Option Tags

These documentation tags correspond to the ASP constructs that can be documented with ASPHelp.

Tag | Description
##AV | Describes an application variable.
##RR | Describes a redirection in the response.
##RQI | Describes the query string associated with a redirection
##SV | Describes a session variable.


##AV Tag

The ##AV tag defines an application variable.

The block comment version of this tag is ##AV_BEGIN and ##AV_END. The end tag must be present for the tag to be valid.

Syntax

##AV VariableName ^^ Comment

Or

##AV_BEGIN
VariableName ^^ Comment
##AV_END

Where VariableName is the name of the application variable,
and Comment is the comment text to use.

Example

The following tag, and its comment:

strConnectionString = Application( "Connection String")

' ##AV Connection String ^^ The cached database connection string.

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


##RQI Tag

The ##RQI tag defines a query string variable for a redirection. The RQI tag will be ignored if no corresponding ##RR tag exists to define the redirection. It will also be ignored if no corresponding redirection exists.

The block comment version of this tag is ##RQI_BEGIN and ##RQI_END. The end tag must be present for the tag to be valid.

Syntax

##RQI Redirection ^^ VariableName ^^ Comment

Or

##RQI_BEGIN
Redirection ^^ VariableName ^^ Comment
##RQI_END

Where Redirection is the hyperlinked text for the parent redirection,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

The following tag and its comment:

Response.Redirect "/logonConfirmation.asp?user=known"

' ##RQI /logonConfirmation.asp ^^ user ^^ A simple user type directive for the destination

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


##RR Tag

The ##RR tag defines a redirection. If the redirection page is specified as a quoted string string in the script, the page will be a hyperlink in the compiled help. Please note that if the redirection is root relative, then the redirection page in the comments must also be root relative.

Query parameters associated with redirections can be documented using the ##RQI syntax

The block comment version of this tag is ##RR_BEGIN and ##RR_END. The end tag must be present for the tag to be valid.

Syntax

##RR RedirectionPage ^^ Comment

Or

##RR_BEGIN
RedirectionPage ^^ Comment
##RR_END

Where RedirectionPage is the name of the page we are redirecting to,
and Comment is the comment text to use.

Example

The following tag, and its comment:

Response.Redirect ("/Home.asp")

' ##RR /Home.asp ^^ The user's personalized home page.

Sample Output

This particular page has more than one redirection on it. Since the HTTP specification allows for but one redirection per resource request, this page obviously has more than one path of execution. The lack of documentation for these links might also indicate unspecified intention for their actions.

Either way, this would indicate to QA that this particular page needs to be exercised more than might otherwise be done.

The presence of hyper links for the destination page names allows development and QA the opportunity to compare the output parameters of this page with the input requirements of the destination page(s).


##SV Tag

The ##SV tag defines a session variable. Unless overridden, all session variables will be returned in the collection.

The block comment version of this tag is ##SV_BEGIN and ##SV_END. The end tag must be present for the tag to be valid.

Note: Many web applications use a customized session object. If this is true for your application, please ensure that you have set the correct object name, and default property in step 2.

Syntax

##SV Variable Name ^^ Comment

Or

##SV_BEGIN
Variable Name ^^ Comment
##SV_END

Where Variable Name is the name of the session variable we are using,
and Comment is the comment text to use.

Example

The following tag, and its comment:

strTitle = Session ("Title")

' ##SV Title ^^ The title of the book to be modified.

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


Script Object and Method Documentation

ASPHelp supports the annotation of server and client side methods and object usage. To enable, or disable, object or method documentation, please see the documented items section of the user interface.

Script Objects

Objects are available for annotation if they meet one of the following invocation types:

  • Server.CreateObject
  • CreateObject
  • <OBJECT>
  • <!-- METADATA -->
  • JavaScript new keyword
  • ActiveXObject invocation in JavaScript

Depending on the object invocation, one or more of the following values will automatically be documented with the object reference:

  • The name attribute
  • The id attribute
  • The ProgId
  • The CLASSID or CLSID
  • The MIME type
  • The code attribute
  • The codebase attribute
  • The datalocation attribute
  • The remote execution server
  • The object version

Script Methods

Server side and client side methods are available for annotation providing they are written in either VBScript or JavaScript. The method, its parameters and return value can all be documented.

Script Documentation Tags

These documentation tags follow a modified JavaDoc syntax and permit the annotation method and objects in the script.

Tag | Description
* @object | Describes an object reference.
* @description | Describes a method.
* @param | Describes a method variable.
* @return | Describes the return value of a function.


*@object Tag

The @object tag describes the intended usage of an object referenced in the current page context. Unlike the data flow tags of ASPHelp, *@object follows a modified JavaDoc syntax. The *@object tags can be located anywhere in the ASP file.

The following object types are automatically handled by ASPHelp:

  • Server.CreateObject
  • CreateObject
  • <OBJECT>
  • <!-- METADATA -->

Syntax

'*@object ObjectName Comment

Where ObjectName is the name of the object,
and Comment is the comment text to use.

The object name differs depending upon the type of object being described:

  • Server.CreateObject, the object name is the ProgId used to create the object
  • CreateObject, the object name is the ProgId used to create the object
  • <OBJECT>, the object name is the ProgId if a ProgId is defined, otherwise it is the CLASSID
  • <!--METADATA-->, the object name is the name associated with the object if defined, otherwise the CLASSID is used if defined, lastly the ProgId is used if neither of the preceeding are defined.

Example

Set objFoo = Server.CreateObject ("MyObject.Foo")

'*@object MyObject.Foo A sample object


*@description Tag

The *@description tag describes the intended usage of a method defined in the current page context. Unlike the data flow tags of ASPHelp, *@description follows a modified JavaDoc syntax. The *@description tags must be located within the function block (i.e. between the Function/End Function or Sub/End Sub directives).

ASPHelp is able to automatically distinguish between server and client side methods.

Method parameters are defined using the *@param syntax, and return values are defined using the *@return syntax.

Syntax

'*@description Comment

Where Comment is the comment text to use.


*@param Tag

The *@param tag describes the intended usage of a parameter on a method defined in the current page context. Unlike the data flow tags of ASPHelp, *@param follows a modified JavaDoc syntax. The *@param tags must be located within the function block (i.e. between the Function/End Function or Sub/End Sub directives of the relevant method)

ASPHelp is able to automatically distinguish between server and client side methods.

Method intent is defined using the *@description syntax, and return values are defined using the *@return syntax.

Syntax

'*@param ParameterName, Comment

Where ParameterName is the name of the parameter being described,
and Comment is the comment text to use.


*@return Tag

The *@return tag describes the return value of a method defined in the current page context. Unlike the data flow tags of ASPHelp, *@return follows a modified JavaDoc syntax. The *@return tags must be located within the function block (i.e. between the Function/End Function or Sub/End Sub directives).

ASPHelp is able to automatically distinguish between server and client side methods.

Method parameters are defined using the *@param syntax, and method intent is defined using the *@description syntax.

Syntax

'*@return Comment

Where Comment is the comment text to use.


Client Side Script Documentation

ASPHelp supports the annotation of client side window operations. Examples of window operations supported include any client side script which causes the current window to navigate, and client side script operation which causes a new window to open, and any client side script operation which causes a web dialog to be spawned.

Current Window Navigation

The following client side script operations are considered current window navigation, and are available for documentation:

  • document.location
  • document.URL
  • location.href
  • layer.src (where layer is from some named layer)
  • link.href (where link is from some named link)
  • frame.src (where frame is from some named frame)
  • iframe.src (where iframe is from some named iframe)
  • window.URL
  • window.back
  • window.navigate
  • window.home

New Window Navigation

Client side script executing a window.open can be documented.

Web Dialogs

Microsoft Internet Explorer supports the concept of web page dialogs. As with desktop applications, these dialog boxes can be either modal or modeless.

Note: ASPHelp can not parse the argument arrays commonly passed to showModalDialog and showModelessDialog. It is recommended that these arrays be documented in the description of the dialog.

Client Side Script Documentation Tags

These documentation tags permit the annotation or documentation of client side script operations.

Tag | Description
##DW | Describes a web dialog window opened in client side code
##DWQ | Describes querystring parameters used to open a web dialog window from client side code
##CN | Describes client side navigation
##CNQ | Describes querystring parameters used in client side navigation
##WO | Describes a web dialog window opened in client side code whose target is a window other than the current window
##WOQ | Describes querystring parameters used to open a web dialog window from client side code whose target is a window other than the current window


##CN Tag

The ##CN tag defines client side navigation. All client navigation is considered an unnamed operation, so ASPHelp will assign an ordinal to each navigation attempt as the parser encounters new navigation attempts. Ordinals are assigned in physical sequence starting with the first navigation encountered in the file and incrementing from there. This ordinal approach is intended to allow for multiple navigations to refer to the same physical page, but have different intents.

Query string items of client navigation can be documented using the ##CNQ tag.

Client side navigation attempts consist of any of the following directives:

  • document.location
  • document.URL
  • location.href
  • layer.src (where layer is from some named layer)
  • link.href (where link is from some named link)
  • frame.src (where frame is from some named frame)
  • iframe.src (where iframe is from some named iframe)
  • window.URL
  • window.back
  • window.navigate
  • window.home

The block comment version of this tag is ##CN_BEGIN and ##CN_END. The end tag must be present for the tag to be valid.

Syntax

##CN Ordinal ^^ Comment

Or

##CN_BEGIN
Ordinal ^^ Comment
##CN_END

Where Ordinal is the ordinal of the navigation,
and Comment is the comment text to use.


##CNQ Tag

The ##CNQ tag defines a query string parameter associated with client navigation. The CNQ tag will be ignored if no corresponding ##CN tag exists to define the client navigation.

The block comment version of this tag is ##CNQ_BEGIN and ##CNQ_END. The end tag must be present for the tag to be valid.

Syntax

##CNQ Ordinal ^^ VariableName ^^Comment

Or

##CNQ_BEGIN
Ordinal ^^ VariableName ^^ Comment
##CNQ_END

Where Ordinal is the ordinal of the parent client navigation,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.


##DW Tag

The ##DW tag defines dialog window opened as part of client script. All dialog windows are considered unnamed windows so ASPHelp will assign an ordinal to each window as the parser encounters new windows. Ordinals are assigned in physical sequence starting with the first dialog window encountered in the file and incrementing from there. This ordinal approach is intended to allow for multiple dialog windows to refer to the same physical page, but have different intents.

Query string items of a dialog window can be documented using the ##DWQ tag.

Dialog parameters are not currently available for comment. Pikauba suggests that users document dialog parameters using the ##DW tag.

The block comment version of this tag is ##DW_BEGIN and ##DW_END. The end tag must be present for the tag to be valid.

Syntax

##DW Ordinal ^^ Comment

Or

##DW_BEGIN
Ordinal ^^ Comment
##DW_END

Where Ordinal is the ordinal of the dialog window,
and Comment is the comment text to use.

Example

The following tag and its comment:

window.showModalDialog ( "page.htm" )

window.showModelesslDialog ( "page.htm" )

' ##DW 1 ^^ Opens a modal dialog

' ##DW 2 ^^ Opens a modeless dialog


##DWQ Tag

The ##DWQ tag defines a query string parameter associated with a dialog window. The DWQ tag will be ignored if no corresponding ##DW tag exists to define the dialog window.

Dialog parameters are not currently available for comment. Pikauba suggests that users document dialog parameters using the ##DW tag.

The block comment version of this tag is ##CNQ_BEGIN and ##CNQ_END. The end tag must be present for the tag to be valid.

Syntax

##DWQ Ordinal ^^ VariableName ^^Comment

Or

##DWQ_BEGIN
Ordinal ^^ VariableName ^^ Comment
##DWQ_END

Where Ordinal is the ordinal of the parent dialog window,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

The following tag and its comment:

window.showModalDialog ( "page.htm?modal=True" )

window.showModelesslDialog ( "page.htm?modal=False" )

' ##DW 1 ^^ Opens a modal dialog
'##DWQ 1 ^^ modal ^^ Indicates to the server side code that we are modal

' ##DW 2 ^^ Opens a modeless dialog
'##DWQ 2 ^^ modal ^^ Indicates to the server side code that we are not modal


##WO Tag

The ##WO tag defines client side navigation which results in a new window, or which directs the browser to open content in a named window. This differs from all other client side navigation covered under the ##CN tag. All client navigation is considered an unnamed operation, so ASPHelp will assign an ordinal to each navigation attempt as the parser encounters new navigation attempts. Ordinals are assigned in physical sequence starting with the first navigation encountered in the file and incrementing from there. This ordinal approach is intended to allow for multiple navigations to refer to the same physical page, but have different intents.

Query string items of client navigation can be documented using the ##WOQ tag.

The block comment version of this tag is ##WO_BEGIN and ##WO_END. The end tag must be present for the tag to be valid.

Client side navigation which results in a new window is parsed for the following directive:

  • window.open

Syntax

##WO Ordinal ^^ Comment

Or

##WO_BEGIN
Ordinal ^^ Comment
##WO_END

Where Ordinal is the ordinal of the window open directive,
and Comment is the comment text to use.


##WOQ Tag

The ##WOQ tag defines a query string parameter associated with window open directive. The WOQ tag will be ignored if no corresponding ##WO tag exists to define the new window.

The block comment version of this tag is ##WOQ_BEGIN and ##WOQ_END. The end tag must be present for the tag to be valid.

Syntax

##WOQ Ordinal ^^ VariableName ^^Comment

Or

##WOQ_BEGIN
Ordinal ^^ VariableName ^^ Comment
##WOQ_END

Where Ordinal is the ordinal of the parent window open directive,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.


HTML options

HTML options indicate which types of HTML elements you wish ASPHelp to include in the output file. Only those tags listed are available for inclusion, and the file extension or type plays no role in the determination. If you elect to not include a given HTML element, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the HTML elements to include. If a given HTML element is not selected for inclusion, any documentation tags relating to it will be ignored.

HTML Element Tags

These documentation tags correspond to the HTML elements that can be documented by ASPHelp.

Tag | Description
##AN | Describes an anchor.
##FM | Describes a FRAME or an IFRAME
##FMV | Describes query string parameters associated with a FRAME or an IFRAME
##FR | Describes an HTML form on the page.
##FV | Describes the form variable of a form
##IM | Describes an image map
##IMA | Describes an image map area associated with an image map
##QI | Describes the query string variable of an anchor
##QIM | Describes the query string associated with an image map areas' link


##AN Tag

The ##AN tag defines an anchor. If the anchor tag is specified as a quoted string in the script, the page will be a hyperlink in the compiled help.

The block comment version of this tag is ##AN_BEGIN and ##AN_END. The end tag must be present for the tag to be valid.

The key in the tag is now the display link for the anchor. Leading or trailing spaces are ignored.

Query string variables contained in an anchor can now be documented with the ##QI tag. Developers and quality assurance professionals can now validate if an anchor is supplying the correct parameters for page, under all circumstances.

Syntax

##AN LinkText ^^Comment

Or

##AN_BEGIN
LinkText ^^Comment
##AN_END

Where LinkText is the hyperlinked text for the anchor,
and Comment is the comment text to use.

Example

The following tag and its comment:

<a href="home.asp">Home Base</a>

' ##AN Home Base ^^ Send the user to the home page.

Sample Output

The presence of hyper links for the destination page names allows development and QA the opportunity to compare the output parameters of this page with the input requirements of the destination page(s).

Anchors are grouped by link text.


##FM Tag

The ##FM tag defines a FRAME element or an inline frame (IFRAME) element.

If ASPHelp encounters an unnamed frame, ASPHelp will generate one in the form "Frame #x", where x is the number of the frame as it is encountered in the ASP. From a documentation perspective, any changes to the ASP file may cause unnamed frames to obtain a different number, thus Pikauba Software strongly recommends users to name their frames.

Query string items of a frame source can be documented using the ##FMV tag.

The block comment version of this tag is ##FM_BEGIN and ##FM_END. The end tag must be present for the tag to be valid.

Syntax

##FM FrameName ^^ Comment

Or

##FM_BEGIN
FrameName ^^ Comment
##FM_END

Where FrameName is the name of the frame or inline frame,
and Comment is the comment text to use.

Example

The following tag and its comment:

<frame src="home.asp" name="frmHome">

' ##FM frmHome ^^ Displays the home page in the main frame


##FMV Tag

The ##FMV tag defines a query string parameter associated with a frame or inline frame. The FMV tag will be ignored if no corresponding ##FM tag exists to define the frame. It will also be ignored if no corresponding frame exists.

The block comment version of this tag is ##FMV_BEGIN and ##FMV_END. The end tag must be present for the tag to be valid.

Syntax

##FMV FrameName ^^ VariableName ^^Comment

Or

##FMV_BEGIN
FrameName ^^ VariableName ^^Comment
##FMV_END

Where FrameName is the name for the parent frame. If the frame is not named, ASPHelp will number it. This generally will make ongoing documentation difficult, so users are strongly urged to name the frames on pages,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

<frame src="home.asp?newuser=true" name="frmHome">

' ##FMV frmHome ^^ newuser ^^ Indicates that the user has registered in this session


##FR Tag

The ##FR tag defines a form in the HTML.

If no form name is used, ASPHelp will generate one in the form "Form #x", where x is the number of the form as it is encountered in the ASP. From a documentation perspective, any changes to the ASP file may cause unnamed forms to obtain a different number, thus Pikauba Software strongly recommends users to name their forms.

Form variables contained in a form can be documented with the ##FV tag. Developers and quality assurance professionals can validate if a form is supplying the correct parameters for page, under all circumstances.

The block comment version of this tag is ##FR_BEGIN and ##FR_END. The end tag must be present for the tag to be valid.

Syntax

##FR FormName ^^ Comment

Or

##FR_BEGIN
FormName ^^ Comment
##FR_END

Where FormName is the name of the form,
and Comment is the comment text to use.

Example

The following tag and its comment:

<form action="home.asp" method="post" name="frmHome">
....
</form>

' ##FR frmHome ^^ Send the user to their customized home page

Sample Output

Since this is an unnamed form, it would need to be documented using the pseudo name "Form #1". Note that if a new form were introduced on the page before this form, "Form #1" would no longer be valid.


##FV Tag

The ##FV tag defines a form variable for a form. The FV tag will be ignored if no corresponding ##FR tag exists to define the form. It will also be ignored if no corresponding form exists.

The block comment version of this tag is ##FV_BEGIN and ##FV_END. The end tag must be present for the tag to be valid.

Syntax

##FV FormName ^^ VariableName ^^Comment

Or

##FV_BEGIN
FormName ^^ VariableName ^^Comment
##FV_END

Where FormName is the name for the parent form. If the form is not named, ASPHelp will number it. This generally will make ongoing documentation difficult, so users are strongly urged to name the forms on pages,
and VariableName is the name of the form variable,
and Comment is the comment text to use.

Example

The following tag and its comment:

<form action="home.asp" method="post" name="frmHome">
<input type="hidden" name="group"
value="10">
<input type="submit" name="btnSubmit" value="Home
Base">
</form>

' ##FV frmHome ^^ group ^^ Users have customized home pages based on their group membership.
' ##FV frmHome ^^ btnSubmit ^^ Submits to the form for page transition.

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


##IM Tag

The ##IM tag defines an image map.

Image map areas are documented with the ##IMA tag.

Query string variables contained in an image map area anchor are documented with the ##QIM tag. Developers and quality assurance professionals can validate if an anchor is supplying the correct parameters for page.

The block comment version of this tag is ##IM_BEGIN and ##IM_END. The end tag must be present for the tag to be valid.

Syntax

##IM Image Map Name ^^ Comment

Or

##IM_BEGIN
Image Map Name ^^ Comment
##IM_END

Where Image Map Name is the name of the image map,
and Comment is the comment text to use.

Example

The following tag and its comment:

<map name="LoginArea">
<area shape="rect" name="new" coords="0,0,96,12"
href="login.asp">
</map>

' ##IM LoginArea ^^ An image map inviting users to login


##IM Tag

Documentation tags ASPHelp

##IMA Tag

h1>

The ##IMA tag defines an image map area.

Image map areas are associated with image maps ( ##IM ) and may have query string parameters.

Query string variables contained in an image map area anchor are documented with the ##QIM tag. Developers and quality assurance professionals can validate if an anchor is supplying the correct parameters for page.

The block comment version of this tag is ##IMA_BEGIN and ##IMA_END. The end tag must be present for the tag to be valid.

Syntax

##IMA Image Map Name ^^ Image Map Area Name ^^Comment

Or

##IMA_BEGIN
Image Map Name ^^ Image Map Area Name ^^Comment
##IMA_END

Where Image Map Name is the name of the map the image map area is part of,
and Image Map Area Name is the name of the image map area,
and Comment is the comment text to use.

Example

The following tag and its comment:

<map name="LoginArea">
<area shape="rect" name="new" coords="0,0,96,12"
href="login.asp">
</map>

' ##IMA LoginArea ^^ new ^^ An image map inviting users to login


##QI Tag

The ##QI tag defines a query string variable for an anchor. The QI tag will be ignored if no corresponding ##AN tag exists to define the anchor. It will also be ignored if no corresponding anchor exists, or is defined if running in override mode.

The block comment version of this tag is ##QI_BEGIN and ##QI_END. The end tag must be present for the tag to be valid.

Syntax

##QI AnchorLinkText ^^ VariableName ^^Comment

Or

##QI_BEGIN
AnchorLinkText ^^ VariableName ^^Comment
##QI_END

Where AnchorLinkText is the hyperlinked text for the parent anchor,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

The following tag and its comment:

<a href="home.asp?group=10">Home Base</a>

' ##QI Home Base ^^ group ^^ Users have customized home pages based on their group membership.

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


##QIM Tag

The ##QIM tag defines a query string variable for an image map area. The QIM tag will be ignored if no corresponding ##IMA tag exists to define the image map area. It will also be ignored if no corresponding image map area exists, and the override flag has not been set.

The block comment version of this tag is ##QIM_BEGIN and ##QIM_END. The end tag must be present for the tag to be valid.

Syntax

##QIM Image Map Name ^^ Image Map Area Name ^^ VariableName ^^Comment

Or

##QIM_BEGIN
Image Map Name ^^ Image Map Area Name ^^ VariableName ^^Comment
##QIM_END

Where Image Map Name is the name of the map the image map area is part of,
and Image Map Area Name is the name of the image map area whose source link contains the name variable,
and VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

The following tag and its comment:

<map name="LoginArea">
<area shape="rect" name="newuser" coords="0,0,96,12"
href="login.asp?UserType=new">
</map>

' ##QIM LoginArea ^^ NewUser ^^ UserType ^^ The type of user we are working with, and need to customize the page for.


Request interface

The request or interface options define which inbound data flow types to include in the project. If you elect to not include a given request collection, that selection is set for all files in the project.

Note: Even when running in override or annotation only mode, you must select the request collections to include. If a given collection is not selected for inclusion, any documentation tags relating to it will be ignored.

Note: Selection of the Cookies option will enable documentation of the Response.Cookies collection for documentation.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix if _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

Request Collection Tags

These documentation tags correspond to the request collections that can be documented by ASPHelp.

Tag | Description
##RC | Describes a cookies collection.
##RF | Describes an input form (POST) variable.
##RQ | Describes an input querystring (GET) variable.
##RV | Describes an input variable that is not accessed via its named collection. The variables can be in either the cookies, forms, or querystring collections.


##RC Tag

1>

The ##RC tag defines a cookie key. If the cookie key is actually a collection, then this defines the collection.

The block comment version of this tag is ##RC_BEGIN and ##RC_END. The end tag must be present for the tag to be valid.

Syntax

##RC CookieKey ^^ Comment

Or

##RC_BEGIN
CookieKey ^^ Comment
##RC_END

Where CookieKey is the cookie key name,
and Comment is the comment text to use.

Example

The following tag, and its comment

strSessionId = Request.Cookies ("SessionId")

' ##RC SessionId ^^ The user's session ID

Sample Output

© Pikauba Software 2001 - 2005. All rights reserved.


##RF Tag

1>

The ##RF tag defines a form (POST) variable requested using the Request.Form collection. If the form variable is requested using Request ("") or Request.Item, then the value will be in the generic input variables defined in ##RV.

The block comment version of this tag is ##RF_BEGIN and ##RF_END. The end tag must be present for the tag to be valid.

Syntax

##RF VariableName ^^ Comment

Or

##RF_BEGIN
VariableName ^^ Comment
##RF_END

Where VariableName is the name of the form variable,
and Comment is the comment text to use.

Example

The following tag, and its comment:

strUserName = Request.Form ("UserName")

' ##RF UserName ^^ The name the user entered.

Sample Output

© Pikauba Software 2001-2003. All rights reserved.


##RQ Tag

The ##RQ tag defines a query string (GET) variable requested using the Request.QueryString collection. If the form variable is requested using Request ("") or Request.Item, then the value will be in the generic input variables defined in ##RV.

The block comment version of this tag is ##RQ_BEGIN and ##RQ_END. The end tag must be present for the tag to be valid.

Syntax

##RQ VariableName ^^ Comment

Or

##RQ_BEGIN
VariableName ^^ Comment
##RQ_END

Where VariableName is the name of the query string variable,
and Comment is the comment text to use.

Example

The following tag, and its comment

strPageId = Request.QueryString ("PageId")

' ##RQ PageId ^^ The customized page to deliver.

Sample Output

In this example the lack of documentation for the SessionExpired variable might indicate a parameter that is being passed in an unexpected way. i.e. The design calls for all parameters to be passed by QueryString (GET) but this one is being accessed in a generic way and might collide with a similarly named cookie or form.


##RV Tag

The ##RV tag defines generic input variables. These variables are retrieved by either Request ("") or Request.Item. They may originate from either the Cookies, Forms, or QueryString collections.

The block comment version of this tag is ##RV_BEGIN and ##RV_END. The end tag must be present for the tag to be valid.

Syntax

##RV VariableName ^^ Comment

Or

##RV_BEGIN
VariableName ^^ Comment
##RV_END

Where VariableName is the name of the request variable we are using,
and Comment is the comment text to use.

Example

The following tag, and its comment:

strPageId = Request ("PageId")

' ##RV PageId ^^ The customized page to deliver.


Interface definition tags

During the design phase of a web project, the web pages are not yet implemented, but the interactions amongst them are generally known. ASPHelp offers a large number of tags to assist in defining the data flow, page flow and information flow of the web site, in the absence of any physical user interface. Many of these tags are only valid on pages that are defined to be overriden. All global and generic tags are valid when ASPHelp is running in this mode.

The interface definition tags are intended to supplement the normal ASPHelp tags by providing default information that would normally be available from having parsed the page contents. As such, it is required that the core definition tag be present for the interface to be accurately defined. For example, if defining a FORM element, the ##FR tag will still be required, as will the ##FV tag for all elements of the form.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix of _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

Overridden Pages

Pages are defined to be overridden if either the Do not parse code option is selected and the ##NOV option has not been defined on the page. Additionally, if the ##OV option has been defined on a page, and the ##NOV option has not been defined, then the page will be overridden, regardless of the Do not parse code option.

Anchor Tags

Tag | Override required | Description
##AN | No | Describes an anchor.
##ANLD | Yes | Defines the default location for use with the ##AN tag
##QI | No | Describes the query string variable of an anchor
##QID | Yes | Defines a default value for use with the ##QI tag

Form Tags

Tag | Override required | Description
##FR | No | Describes an HTML form on the page.
##FRAM | Yes | Defines the default action method associated with the ##FR tag
##FRLD | Yes | Defines the default location for use with the ##FR tag
##FV | No | Describes an HTML form on the page.
##FVD | Yes | Defines the default value for use with the ##FV tag
##FVT | Yes | Defines the variable type for use with the ##FV tag

Frame or IFrame Tags

Tag | Override required | Description
##FM | No | Describes a FRAME or an IFRAME
##FMLD | Yes | Defines the default location for use with the ##FM tag
##FMV | No | Describes query string parameters associated with a FRAME or an IFRAME
##FMVD | Yes | Defines the default value for use with the ##FMV tag

Image Map Tags

Tag | Override required | Description
##IM | No | Describes an image map
##IMA | No | Describes an image map area associated with an image map
##IMLD | Yes | Defines the default location for use with the ##IMA tag
##QIM | No | Describes the query string associated with an image map areas' link
##QIMD | Yes | Defines a default value for use with the ##QIM tag

Request Tags

Tag | Override required | Description
##RC | No | Describes access to the cookie collection
##RF | No | Describes an input variable sent using the POST HTTP method
##RQ | No | Describes an input variable sent using the GET HTTP method
##RV | No | Describes an input variable sent using either the POST or GET HTTP method

Response Tags

Tag | Override required | Description
##RC | No | Describes access to the cookie collection
##RR | No | Describes a redirection in the response.


SQL Object Documentation

Documentation overview ASPHelp

SQL documentation

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:

  1. You must have ASPHelp 1.6 or greater
  2. You must have SQLHelp 1.6 or greater (version 1.7 or greater recommended)
  3. 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.
  4. The output folder for both the ASPHelp and SQLHelp/DBDocumentor projects must be the same.
  5. When you distribute the final help files, they must be located in the same folder for proper merging to occur
  6. If you are working with a case sensitive database, your usage of the SQL tag must also be case sensitive
  7. 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.


ASPHelp - User Interface

User interface ASPHelp

User interface

The ASPHelp user interface uses a simple wizard philosophy. You enter the various elements of information the tool looks for, and it goes about its merry way to generate HTML Help representing the database procedures in your project.

The wizard pages are:

  • Component Validation This page may be displayed if you are missing some critical component required for program execution.
  • Licensing Like all software products, ASPHelp has a licensing agreement that grants you, the user, the ability to use the product, as long as you play nice.
  • Registration Since ASPHelp is distributed via the shareware channels, the version you have now probably has 90% of the feature set working. Registration gives you that lacking 10%, and is well worth the price.
  • Step 1 is literally the first step a registered user sees when running the program.
  • Step 2 prompts you to select the directory where the source files, and destination files should be located, and allows you to set various other options.
  • Step 3 prompts you to select the files to form part of the project.
  • Step 4 confirms the information gathered and then produces the output.


ASPHelp - Component Validation

User Interface ASPHelp

Component Validation

ASPHelp requires a number of third party components to be installed on your system. If one or more of these components are missing from your system, the component validation screen will appear on each program run until such time as the missing items are installed. If a component is missing, you can press the Locate button to attempt to locate the missing component. Please note that this will attempt to launch an instance of your browser.

Common Controls

Normally the common controls are installed on your system by either the operating system, or by any number of other applications.

In the event that one or more is missing, the Locate button will download an installation package from Pikauba.com that contains the required components.

Internet Explorer

In order to view compiled HTML help files, Microsoft Internet Explorer version 4.02 or higher is required. This does imply that you need Internet Explorer to browse the Internet, only that Internet Explorer be installed on your system.

Pressing Locate will take you to the Microsoft home page for Internet Explorer where you can download the version that is appropriate for your region.

HTML Help System and Compiler

In order to compile HTML Help, ASPHelp requires the Microsoft HTML Help workshop to be installed. The licensing strategy for the Microsoft HTML Help workshop is such that it is installed and registered to individual users on a machine. As a result it is possible for the compiler to be installed, but not accessible. A reinstallation will correct this situation.

Pressing Locate will take you to the Microsoft MSDN HTML Help page. You want to download the HTML Help Workshop.

Data Access Components (MDAC)

ASPHelp makes extensive use of ADO components internally. The required installed version is 2.1 or higher.

Pressing Locate will take you to the Microsoft Universal Data Access site. Downloading any MDAC version with a version number greater than MDAC 2.1 will work.

Scripting Components

In order to work with a variety of systems including the file system and to launch applications, the Microsoft scripting components need to be installed.

Pressing Locate will take you to the Microsoft MSDN Scripting home page. You want to select Windows Script from the left frame. It will take you to a download page where you can select the version that is appropriate to your operating system and region.

MSXML3

Unlike version 1.x of ASPHelp, version 3 is XML dependent. No table of contents can be generated, nor will any XML operations work without at least MSXML3 service pack 3 installed. If you have MSXML4 installed, it too will function properly with ASPHelp.


ASPHelp - Licensing

User interface ASPHelp

Licensing

When you first run ASPHelp, and each day that you run the shareware version, you will be presented with the Licensing Agreement. Written mostly in legalese, it simply states that you will use the shareware version of ASPHelp for evaluation only. If it meets your needs, great, register it. If it fails to meet your needs (and we hope you'll let us know if this is the case), fine, delete it.

Basically, we all will be pressing I Agree and going to the next screen, but it is important to read what's in there.


ASPHelp - Registration

User interface ASPHelp

Registration

After pressing "I Agree" on the licensing page, you'll be taken to the registration page. On this page you have the option of registering ASPHelp, or trying it out. If you do elect to try it out, you'll be taken through this process until you either determine the program is worth it's registration fee, or decide to delete it. Unlike some shareware programs, this period is not fixed in time or duration, thus the ASPHelp shareware version will not expire. The shareware version does contain some limitations, including the inability to add your copyright notice to the output, and a limit of 20 pages of input.

The registration key and code were sent to via email during registration.
Please note that if you are registering an upgraded version, you do not need to get a new key and code (actually, you shouldn't even see this screen), unless you are outside the current major version.

If you wish to purchase ASPHelp, pressing Register will take you to the main registration page on Pikauba.com. You may select from the available registration options and, upon receipt of payment, the registration key and code will be emailed to you.

Press Try Me! to enter shareware mode and go to step 1.


ASPHelp - Step 1 - Welcome

User interface ASPHelp

Step 1 - Welcome

The first step of operation for ASPHelp is the welcome screen. On the welcome screen you have the opportunity to select a previous project, browse for a project file to load, or create a new project.

The recent project list will contain the ten most recently used projects, sorted alphabetically. By default the last project file is selected. After selecting a project file, press the Load button to continue.

If you wish to browse for previous project files, select the browse button. Once a project file is loaded, you will automatically be taken to step 2.

Project files will all have the .ASPHelp file extension and are located in the same folder as the source files for the project. These files are also registered with the system and can be double clicked to launch ASPHelp. There is an option in ASPHelp to specify project settings in an XML file. Full details on the XML project file can be found here.

Press New to create a new project.

Pressing Unlock will take you to the registration page. This button will only display if ASPHelp is not currently registered.

Press ? to launch the help system to display this manual.


ASPHelp - Step 2 - Select Folders

User interface ASPHelp

Step 2 - Folder options

Step 2 of the processing allows you to define the processing options. These processing options are broken down into five sections:

  1. Input Folders or Directories
  2. Parser options
  3. Items to document
  4. Allowed input file types
  5. Output options

Once a project file is loaded, or a new project is requested, you are taken to step 2. Step 2 sets all the processing options for the project. These options are saved with the project file, and default to the values used with the most recent project.

If you have loaded a project file, and that project file has files listed to process, the Finish button will be active and pressing it will begin processing of the project.

Directories

The directories tab allows you to select the input and output folders for the project.

  • Directory to process: Allows you to specify where the source files are located. This value is stored between runs of ASPHelp, so unless the source folder changes, this value does not need to be reentered.
    You can either enter the value directly, or press . . . to browse for the folder.

If the folder does not exist, an error message will be displayed

When creating a new project, this entry will be blank.

  • Output directory: Allows you to specify where the output compiled help file is stored. Generally, this should be a working directory as ASPHelp will generate various working files. As with the input folder, this value is stored between runs.

Note: If you select a file name using the . . . link, it will automatically populate the Output Filename field.

If the folder was entered directly and does not exist, a warning message will be displayed. This warning message will prompt you to create the folder.

  • Output filename: Allows you to specify the output filename directly. Previous versions determined the output filename during selection of the output directory.

Note: This filename must have the extension of .chm for the Microsoft HTML Help Viewer to correctly associate itself with the output configuration. As a result, only the extension of .chm is supported.

When creating a new project, this entry is blank.

  • Look in sub folders: ASPHelp can optionally recurse the directory hierarchy of your project to locate any ASP files contained in sub folders.
  • Include all/Select specific files: If you select the option to include all the files contained in the directory to process, with a file mask of the selected file types, you will not have the opportunity to select the specific files to include.

Parser Options

The parser options tab allows you to set how ASPHelp handles session variables, include files and procedure unrolling.

Documented Items

The documented items tab allows you to define the items to be included in the output documentation.

File Types

The file types tab allows you to define the various file types (or extensions) that will be processed in the project.

Output Options

The output options tab allows you to define the various options associated with generating the output file from the project.

  • Press Next once the options are selected.
  • Press Back to return to the welcome screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 2 - Parser Options

User interface ASPHelp

Step 2 - Parser options

Step 2 allows you to define how a session variable appears in your project. You have the choice of instructing the system to use the ASP Session object (default) or a custom session object.

Parser Options

The parser options tab allows you to set the options associated with session variable parsing.

  • Do not parse code. When checked, this option assumes that the override option is enabled on every input page.
  • Recurse includes. When checked, this option indicates that ASPHelp should load all available include files listed in the page and process them as part of the input page. If required, any files included in includes are also loaded. This option also applies to script libraries.
  • Process procedures. When checked, this option enables procedure expansion in ASPHelp. Procedure expansion is a process where the input web page is processed looking for method usage and render blocks. Any methods/blocks found are then loaded in place and rendered into the output stream. This process helps to ensure that the output documentation is consistent with actual execution options and the impact of the method/render block.
  • Use intrinsic ASP session object. If your project makes use of the ASP Session object, or doesn't use session variables, leave this box checked (default).
  • Object name. If you are using a custom session object, you will need to supply the name of the object as it appears in your script. For example, if you are creating a global session object with the name of objSession, the value to enter for the session object is objSession.
  • Default property. If you are using a custom session object, you will need to supply the name of the objects' default property. The default property is used to resolve session access issues when the session object is used in a With block. For example, if the the default property of objSession is SessionVariables then if you access session variables via objSession("foo") ASPHelp will translate that into objSession.SessionVariables("foo")

Directories

The directories tab allows you to select the input and output folders for the project.

Documented Items

The documented items tab allows you to define the items to be included in the output documentation.

File Types

The file types tab allows you to define the various file types (or extensions) that will be processed in the project.

Output Options

The output options tab allows you to define the various options associated with generating the output file from the project.

  • Press Next once the options are selected.
  • Press Back to return to the welcome screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 2 - Documented Items

User interface ASPHelp

Step 2 - Documented items

Step 2 allows you to define how ASPHelp will parse your scripts.

Documented Items

The listed options are available for documentation. ASPHelp parses each input file for the enabled items and includes them in the output.

Note: If the option to recurse includes is enabled, any script libraries or include files found will be considered to be part of the current page. If the process procedures option is enabled, ASPHelp will also expand inline any procedures explicitly called on the input page. Using these options will generally give a very complete view of the external interfaces exposed by a page, and the input data flow supported by the page.

Document - ASP

  • Application variables. If checked, ASPHelp will parse the script looking for use of the ASP application variable.
  • Response redirection. If checked, ASPHelp will parse the script looking for Response.Redirect commands.
  • Session variables. If checked, ASPHelp will parse the script looking for use of session variables as defined on the parser options tab of step 2.

Document HTML

  • Anchors. If checked, ASPHelp will attempt to determine the destination for every anchor on the pages.
  • Forms. If checked, ASPHelp will attempt to determine the posting location for every form on the pages.
  • Image maps. If checked, ASPHelp will attempt to determine the destination for all image maps and image map areas in the pages of the project
  • Frames and IFrames. If checked, ASPHelp will attempt to determine the frames used in the pages of the project. These frames may be either traditional Frame elements, of the Internet Explorer IFrame element.
  • Client script. If checked, ASPHelp will attempt to determine the destination and parameters for all client side navigation, new windows, and Internet Explorer Modal and Modeless dialog boxes.

Document - Script

  • Include method detail. If checked, ASPHelp will include a listing of all methods (procedures, functions, subroutines and event handlers) defined in the source page, both client and server side. Methods defined in includes or in script libraries are not considered defined in the source page and won't be included, but if the include file is written to the output, methods defined in the include file will be present in the documentation for the include file.
  • Include object usage. If checked, ASPHelp will parse the web page (client and server side script) looking for instances of object usage. Any operation consisting of a new, CreateObject, Server.CreateObject, META definition, or OBJECT tag is included.

Document - Request

  • Cookies. If checked, ASPHelp will parse the script looking for cookie use.
  • Forms. If checked, ASPHelp will parse the script looking for use of Request.Form commands.
  • QueryString. If checked, ASPHelp will parse the script looking for use of Request.QueryString commands.
  • Item (Generic). If checked, ASPHelp will parse the script looking for use of Request.Item or Request("") commands. Since these commands allow access to all collections of data, it is possible for a variable to be accessed incorrectly, or for a namespace collision to occur between a variable in the cookies collection and a forms element.

Directories

The directories tab allows you to select the input and output folders for the project.

Parser Options

The parser options tab allows you to set how ASPHelp handles session variables, include files and procedure unrolling.

File Types

The file types tab allows you to define the various file types (or extensions) that will be processed in the project.

Output Options

The output options tab allows you to define the various options associated with generating the output file from the project.

  • Press Next once the options are selected.
  • Press Back to return to the welcome screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 2 - Define File Types

User interface ASPHelp

Step 2 -Define file types

File Types

The file types tab allows you to define the various file types (or extensions) that will be processed in the project.

In versions of ASPHelp previous to version 1.3, the only supported file types were ASP and ASA. You had the option (which still remains) to specify an alternate extension by selecting a file of that type during the input folder selection process.

Only the files whose extension matches those selected on this tab will be included in the file selection list of step 3.

Documentation of static files uses the same syntax tags as dynamic files, but the comments are placed in HTML comment blocks.

Note: Publishing annotated static files, or files annotated in HTML comment blocks may provide unauthorized users with unintentional information relating to the structure and intent of your web site. Pikauba Software is not responsible for any unauthorized access to your web properties by any party making use of these annotation tags.

Directories

The directories tab allows you to select the input and output folders for the project.

Parser Options

The parser options tab allows you to set how ASPHelp handles session variables, include files and procedure unrolling.

Documented Items

The documented items tab allows you to define the items to be included in the output documentation.

Output Options

The output options tab allows you to define the various options associated with generating the output file from the project.

  • Press Next once the options are selected.
  • Press Back to return to the welcome screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 2 - Output Options

User interface ASPHelp

Step 2 - Output options

Output Options

Step 2 allows you to define the various options associated with generating the output file from the project.

  • Launch compiled help. Once the project is compiled, if this box is checked, the system will launch the resultant compiled help file.
  • Include source. If checked, every page that is included in the project will have it's source also included in the compiled output.
  • Colorize source code. If checked, the output source listing for every page will have its script and HTML colorized. The following items are colorized:
  • HTML tags, including all attributes
  • ASP render blocks
  • Client and server side script block language keywords for both VBScript and JavaScript
  • Comment tags in HTML and/or script
  • Explicit strings occurring in script blocks

If a context switch occurs from client side to server side processing, or a render block is encountered, ASPHelp will automatically switch contexts resulting in a very accurate representation of the current language. Note that this will also make visual validation of certain code errors more easy to spot (e.g. opening an HTML attribute with a double quote, rendering some ASP into the attribute and either failing to close the attribute, or closing it with a single quote.

Note: Colorization is a very CPU intensive process. Turning on colorization on machines with CPU ratings below 1GHz is strongly discouraged. For projects without large include files or script libraries, or projects where include files are not included in the output, colorization will add approximately 25-40% additional processing time. For projects with large include files or script libraries where the include files or script libraries are included in the output, colorization of these large files could easily dominate the entire processing time.

  • Include include files. This option only appears if the recurse includes option is checked on the include options tab, and the include source option is selected. If checked, the output source code will contain hyperlinks for the various include files. These hyperlinks will lead to the source of the include file.
  • Hyperlink dynamic content. If checked, ASPHelp will attempt to determine if the text of a variable refers to a page in the project, or some other valid hyperlink (e.g. on the Internet).
  • Modern MSDN layout. ASPHelp can output a compiled HTML Help file whose layout follows either a classic MSDN layout (common for Visual Studio 6 based development), or a modern layout (common for Visual Studio .Net based development)
  • Cleanup temporary files. The processing of ASP to generate HTML help files often creates a large number of temporary files. The vast majority of these files are HTML and may be suitable for use in a web based help system, but most users find that they only consume disk space. If you have no need for these temporary files, you can indicate to ASPHelp to remove them after generating the output HTML help file.
  • Include methods. If checked, ASPHelp will parse each file to determine any methods in the file and will include them in the output file. By selecting this option, you can fully annotate and document file level client side and server side methods.
  • Include objects. If checked, ASPHelp will parse each file to determine any object usage in the file and include the objects, along with their invocation details in the output file. Object usage reported is for both client and server side objects, and will include embedded objects.
  • Allow any user to modify output: When working under Windows Server 2003, the output file will be owned by the user running ASPHelp. Ownership implies that user account (and the Administrators security group) are the only users able to modify the output file. By selecting this checkbox, ASPHelp will allow the default behavior but will also make any user who is a member of the Users security group able to modify the output file.

    This option is only enabled under Windows NT based operating systems.
  • SQLHelp/DBDocumentor Linkage. If selected, ASPHelp will load the indicated SQLHelp or DBDocumentor project file and use its settings to define the core linkage. Please see the ##SQL tag for more information on linkage. The relevant settings from the SQLHelp/DBDocumentor project file include if the database is case sensitive and the location of the output SQLHelp/DBDocumentor help file. Merges of HTML Help files occur at runtime, so ASPHelp will validate if the output location of the current ASPHelp project and the output location of the SQLHelp/DBDocumentor project are the same. If they are not, a warning will be issued.

    SQLHelp linkage occurs with the SQLHelp project alone. This can result in situations where a procedure is specified to be in the SQLHelp project, but actually isn't.

    DBDocumentor linkage occurs via the SQLDocumentation XML file. This requires that the DBDocumentor project be configured to output SQLDocumentation files. Due to the use of SQLDocumentation for input validation, if a SQL object is specified in the ASP file, and isn't validated to be present in the SQLDocumentation file, then there will be no hyperlink between the ASP definition and the indicated SQL object.

    Note: To learn more about SQLHelp, please visit the Pikauba Software web site at this link.

    Note: To learn more about DBDocumentor, please visit the Pikauba Software web site at this link.

Directories

The directories tab allows you to select the input and output folders for the project.

Parser Options

The parser options tab allows you to set how ASPHelp handles session variables, include files and procedure unrolling.

Documented Items

The documented items tab allows you to define the items to be included in the output documentation.

File Types

The file types tab allows you to define the various file types (or extensions) that will be processed in the project.

  • Press Next once the options are selected.
  • Press Back to return to the welcome screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 3 - Select Files

User interface ASPHelp

Step 3 - Select files

In step 3, you select the files to include in your project.

In the left hand pane you'll see all files in the source folder meeting the file extension requirements specified. If you see ASPHelp.ini in this list, please do not include it to avoid duplication of information in the final output.

If you loaded a project file that had previously included files, the Finish button will be active and pressing it will begin the processing of the ASP files.

Note: After the first run of ASPHelp on a given project, the list of files included in the project may not match exactly those originally specified. ASPHelp will remove from inclusion those files that are only present as include files. Include files have special treatment in ASPHelp and are not required to be explicitly included in a project.

  • Click on a folder to select or deselect all files listed in that folder and below. After any given folder, ASPHelp will display the number of files below the folder matching your file mask, and the number of files currently selected for processing from that set. A check will be placed in the check-box for a folder only if all the files in the folder are included in the project.
  • Press Finish once the files are selected.
  • Press Back to return to the folder selection screen.
  • Press ? to launch the help system to display this manual.


ASPHelp - Step 4 - Final

User interface ASPHelp

Step 4 - Processing

In step 4, you confirm the project details, and instruct the system to prepare the output.

Before pressing Finish, verify that the Project Name and Source and Destination folders are correct.

Once Finish has been pressed, the system will parse through the ASP files in the source folder looking for the various tags in the files to produce the final output.

Phases

Processing goes through several distinct phases. Each phase is detailed in the white headline bar. The phases are:

  1. Determining includes. During this phase, ASPHelp attempts to determine if any of the project files contain includes. Normally this is a fairly short process.
  2. Scanning Includes. During this phase, ASPHelp will scan all the files in your project locating and loading the includes in the project. If a file is included in the project, and is also an include file it is removed from the project at this point.
  3. Processing files. It is during this phase that actual parsing occurs.
  4. Building Includes. During this phase the actual includes are used, and the hyperlinks are added to these source files.
  5. Building the table of contents. This marks the beginning of the compiled help file creation.
  6. Building Index. The searchable keyword index is constructed at this point.
  7. Compiling output. All the parts of the output help file are compiled at this point. Depending upon the number of pages in your project, this can be quite lengthy. If you do not have the Microsoft HTML Help compiler installed, you will receive an error at this point.
  8. Once done, you will be presented with the options of re-running the project or exiting ASPHelp. If you see a message box indicating that compilation failed, this normally indicates the lack of the Microsoft HTML Help compiler. Please view the troubleshooting guide for more information.

Progress Bars

During execution three progress bars will be displayed. The top bar gives the overall progress of the project. Immediately above it is an estimation of when processing will be completed.

The second progress bar denotes which file of the project is currently being processed. This progress bar will run from 0 to 100% twice in execution, once during include file scanning, and once for main processing.

The third progress bar denotes the precise step within a given file.

Press Finish to have the output prepared.

Press Back to return to the file selection screen.

Press ? to launch the help system to display this manual.


XML Layout

XML Files ASPHelp

XML File Layout

Generation 2 of ASPHelp brings with it the ability to define project files in XML. The XML project files do not replace the .ASPHelp files of previous versions, rather they can be used to programmatically modify the behavior of the .ASPHelp project when running from command line.

XML Files

Contained in the XML folder off the installation path are two XML files. One file is used in building of the table of contents. The other file offers a sample of how to generate a table of contents as used in previous versions of ASPHelp.

Standard.xml contains the standard (default) table of contents. Do not modify this file as modification could cause ASPHelp to fail to operate.

Suppress.xml contains an XML project file which will generate a table of contents as used in versions of ASPHelp prior to ASPHelp 2.10.

XSL Files

Contained in the XSL folder off the installation path are two XSL files used to produce the CHM and XML outputs.

CustomTOCLoad.xsl is used to convert the grouping options of the XML project file into a chapter representation. Modification of this file could cause all custom table of contents (groupings, or applies to entries) to fail to function.

StandardTOCLoad.xsl is used to convert the standard table of contents into a chapter representation. Modification of this file could cause all table of contents to fail to display.

XSD Files

Contained in the XSD folder off the installation path is one XSD file.

Config.xsd is used to describe and validate the XML project file.

© 2001 - 2005 Pikauba Software. All rights reserved.


XML Project File

Generation 2 of ASPHelp brings with it an XML project file. This XML project files does not replace .ASPHelp file used in previous versions, but rather allows for greater control of the textual elements which can be incorporated in the final output (e.g. project descriptions). The XML project file must be named ASPHelp.xml and located in the same folder as the .ASPHelp file.

Note: Use of the XML project file allows for considerable control over the operation of ASPHelp, but does not replace the GUI user interface. Specifically, while you can set overrides for many options present in the GUI, were you to open the GUI you would not see the settings defined by the XML file.

Note: If a data error occurs during the processing of the XML project file, the output may not be as expected. Data errors are defined as errors in the content of an attribute defining an override, but where the XML is well formed.

Note: If you make use of the XML file, none of the settings you may have specified for matching items in the INI file will be used. In other words, what is in the XML file is what will always be used.

Note: The rules for well formed documents must be followed for this file. Specifically, all items are case sensitive, if an XML reserved character is required in the description, it must be included in a CDATA section, and attention to the encoding may be required depending on the language of the computer ASPHelp is running on. If the XML document is not well formed, XML errors will occur and ASPHelp not run with any of the options defined in the file.

Note: An XML schema is included with the project. It is named config.xsd, and follows the XSD syntax. The file can be found in the XSD folder off the installation path.

Details

The XML project file can contain two document elements. One named groups, containing information about the table of contents and described here. The second named Config and described below.

Config Document Element

The Config document element is used to define any textual elements which were previously defined in the ASPHelp.ini file, and optionally to define any overrides of the settings stored in the ASPHelp project file. The Config document element is made up of the optional elements named: Settings, CopyrightInfo, StyleSheetLocation, ProjectDescription, ProjectPageHeader.

Settings Document Element

The Settings document element is used to define the overrides present in the XML project file. An entry is present for each of the available options in the GUI. All entries are optional.

AnyUser Attribute

The AnyUser attribute corresponds to the GUI element controlling whether any user is allowed to access the output. Valid values are yes/true and no/false.

Colorize Attribute

The Colorize attribute corresponds to the GUI element controlling whether the output is colorized. Valid values are yes/true and no/false.

Override Attribute

The Override attribute corresponds to the GUI element controlling whether parsing of any objects is to occur. Valid values are yes/true and no/false.

IncludeSource Attribute

The IncludeSource attribute corresponds to the GUI element controlling whether the output will contain the source used to define the SQL object being described. Valid values are yes/true and no/false.

LaunchHelp Attribute

The LaunchHelp attribute corresponds to the GUI element controlling whether the output is launched after compilation. Valid values are yes/true and no/false.

ProjectName Attribute

The ProjectName attribute corresponds to the GUI element defining the name of the project used in the final output.

OutputFileName Attribute

The OutputFileName attribute corresponds to the GUI element defining the name of the output file.

CopyrightInfo Element

If you are supplying a copyright notice to be placed at the bottom of each page in the output document, place that notice in the CopyrightInfo element. When using the XML project file, the ##CO tag is inoperative.

Note: If you are working with an unregistered version of ASPHelp, the contents of this element will be ignored.

StyleSheetLocation Element

If you are wishing to override the default stylesheet supplied with ASPHelp, please supply the name of that stylesheet in the StyleSheetLocation element. The required contents of a custom stylesheet are described here.

Note: The stylesheet must be located in the same folder as the XML file, or in a sub folder beneath it. If the stylesheet can not be found during output compilation, the default stylesheet will be use.

Note: If you are working with an unregistered version of ASPHelp, the contents of this element will be ignored.

ProjectDescription Element

If you are wishing to supply text to be displayed on the project summary page of the output document, please supply it using this element. When working with the XML project file, the ##PR tag is inoperative.

ProjectPageHeader Element

If you are wishing to define a header for the entire project following the conventions of ##PPH, please supply it using this element. When working with the XML project file, the ##PPH tag is inoperative.

Note: If you are working with an unregistered version of ASPHelp, the contents of this element will be ignored.

© 2001 - 2005 Pikauba Software. All rights reserved.


Grouping XML Description

XML Files ASPHelp

XML Table of Contents File Description

If you are making use of the XML project file, you will need to specify your grouping options in XML as well. In addition to the standard options offered with ##AT , with the XML project file you can specify groupings many levels deep, define fixed content for specific groupings, control which of the standard groupings are present, and associate HTML Help icons with any fixed content defined., The XML format permits the definition of multiple sub-groupings, and gives greater control over the layout of the standard groups.

The XML file is named ASPHelp.xml and must be located in the same folder as the .ASPHelp project file. Normally this location is where global.asa would be located.

Note: The rules for well formed documents must be followed for this file. Specifically, all items are case sensitive, if an XML reserved character is required in the description, it must be included in a CDATA section, and attention to the encoding may be required depending on the language of the computer ASPHelp is running on. If the XML document is not well formed, XML errors will occur and ASPHelp will revert to displaying a default table of contents.

Note: An XML schema is included with the project. It is named config.xsd, and follows the XSD syntax.

Details

The XML project file contains a document element named groups which is used to define the table of contents hierarchy. The groups element contains two document elements named, custom and standard.

Custom Document Element

The custom document element is used to define any custom table of contents items, and the associated descriptions for them. The layout of the table of contents will follow the layout of the custom document elements' group elements.

The custom document element is made up of many group elements. group elements may be nested within each other allowing for a hierarchy as deep as desired. Each group element must have an associated name attribute. The value of the name attribute is the text to display for the node in the table of contents. Each group element may have a description element. The textual description for the page will come from the description element. Failure to define a description element will result in a blank page being used.

By default, ASPHelp will include on the description page for all groups a list of hyperlinks to the content contained in the group. This default behavior can be suppressed using the optional ShowLinks attribute of any group document element for which this is the desired result. Valid values for the ShowLinks attribute are: yes and no.

By default, ASPHelp will sort the pages within each table of contents section. This default behavior can be suppressed using the optional SortGroup attribute of any group document element for which this is the desired result. Valid values are: yes and no.

Fixed External Content

If your project requires pre-defined content to be included in the final output, and in the table of contents, this can be specified within the custom document element under the desired group element. A group is marked as supporting pre-defined content with the optional attribute FixedContent. When FixedContent is set to yes, the group will be processed for fixed (pre-defined) content. Fixed content is defined using the content document element. The content document element encapsulates one or more entry elements. Each entry document element represents a single entry in the table of contents for the section defined by its associated group. Each entry element contains two required attributes, name and file. The name attribute defines the name to be displayed within the table of contents. The file attribute defines the name of the file to be included in the project. entry elements may also have an optional attribute named IconIndex. If present, the IconIndex indicates which of the stock HTML Help viewer's icons will be used when displaying the topic.

Note: The file name specified must exist in the output folder when ASPHelp is run for a valid output document to be produced. ASPHelp performs no presence validation on the file. If the file specified can not be found by the HTML Help compiler, compilation problems may result. If the file references other files via hyperlink, they too need to be present in the output folder prior to running ASPHelp. Hyperlinked files, which are not explicitly included as content, will be included in the output document by the HTML Help compiler, regardless of where the files may exist on disk at the time of compilation.

Standard Document Element

The standard document element is intended to allow the user to override the default description for specific table of contents entries, to control if default table of contents entries are displayed, and to allow control over where the standard table of contents is located in the final document.

The standard document element has two attributes, order and subordinate. The order attribute controls where in the table of contents the standard table of contents is displayed. The values are lead, follow and subordinate.

The value of lead indicates that the standard table of contents will precede any custom entries, and will be a peer to any custom entries. It is the default value.

A value of follow indicates that the standard table of contents will trail any custom entries, and will be a peer to the custom entries. If there are no custom entries, lead and follow will result in the same table of contents structure.

A value of subordinate indicates that the standard table of contents will be placed immediately below the top level custom group entry identified by the subordinate attribute. If the named top level entry isn't present, the default values will be used. No support is included to place the standard table of contents at any custom level other than the top level.

The standard document element is made up of many group elements. Like the group elements of the custom element, standard group elements require a description element, and name attribute. Unlike the custom element, the name attribute values are predefined, and an optional suppress attribute is present. The list of predefined name values can be found here. If the suppress attribute is defined, this indicates that the table of contents associated with the group entry and any of its children will be suppressed when the output is written. The actual web pages and their documentation will still be present in the final document, but there will be no entry in the table of contents for the specified entry.

By default, ASPHelp will sort the pages within each table of contents section. This default behavior can be suppressed using the optional SortGroup attribute of any group document element for which this is the desired result. Valid values are: yes and no.

© 2001 - 2005 Pikauba Software. All rights reserved.


Tag reference

ASPHelp provides a rich set of commands for use in the source ASP to produce formatted, professional compiled help. Each of these tags can appear more than once in a file.

Tags may occur more than once per file. If the identical tag name is encountered, the system will append (concatenate) the value to the previous value. This allows for greater readability of the source file, and ease of documentation.

Tags may make use of any valid HTML syntax to create more detailed help. In addition to the tags listed below, a series of tags have been defined that only apply to the definition of interfaces.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix of _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

Note: Publishing annotated static files, or files annotated in HTML comment blocks may provide unauthorized users with unintentional information relating to the structure and intent of your web site. Pikauba Software is not responsible for any unauthorized access to your web properties by any party making use of these annotation tags.

Tag | Block tag | Description
##AN | ##AN_BEGIN - ##AN_END | Describes an anchor.
##AT | n/a | Provides an "Applies To" description. The "Applies To" section allows the developer the capability to group functional pages in the final compiled output.
##AV | ##AV_BEGIN - ##AV_END | Describes an application variable.
##BD | ##BD_BEGIN - ##BD_END | Provides a page description.
##CN | ##CN_BEGIN - ##CN_END | Describes client side navigation
##CNQ | ##CNQ_BEGIN - ##CNQ_END | Describes querystring parameters used in client side navigation
##CO | ##CO_BEGIN - ##CO_END | Provides a copyright description. May only be used in the ASPHelp.ini file.
##DW | ##DW_BEGIN - ##DW_END | Describes a web dialog window opened in client side code
##DWQ | ##DWQ_BEGIN - ##DWQ_END | Describes querystring parameters used to open a web dialog window from client side code
##FM | ##FM_BEGIN - ##FM_END | Describes a FRAME or an IFRAME
##FMV | ##FMV_BEGIN - ##FMV_END | Describes query string parameters associated with a FRAME or an IFRAME
##FR | ##FR_BEGIN - ##FR_END | Describes an HTML form on the page.
##FV | ##FV_BEGIN - ##FV_END | Describes the form variable of a form
##IM | ##IM_BEGIN - ##IM_END | Describes an image map
##IMA | ##IMA_BEGIN - ##IMA_END | Describes an image map area associated with an image map
##MLD | n/a | Defines the string action to take on the named method.
##OV | n/a | Denotes an overridden page. Overridden pages do not have any of their content parsed, rather the values explicitly named are included in the compiled help.
##PR | ##PR_BEGIN - ##PR_END | Provides a project description. All ##PR tags in the project are combined to make the final title page. Note: ##PR tags may only appear in the ASPHelp.ini file
##QI | ##QI_BEGIN - ##QI_END | Describes the query string variable of an anchor
##QIM | ##QIM_BEGIN - ##QIM_END | Describes the query string associated with an image map areas' link
##RC | ##RC_BEGIN - ##RC_END | Describes a cookies collection.
##RF | ##RF_BEGIN - ##RF_END | Describes an input form (POST) variable.
##RQ | ##RQ_BEGIN - ##RQ_END | Describes an input querystring (GET) variable.
##RQI | ##RQI_BEGIN - ##RQI_END | Describes the query string associated with a redirection
##RR | ##RR_BEGIN - ##RR_END | Describes a redirection in the response.
##RV | ##RV_BEGIN - ##RV_END | Describes an input variable that is not accessed via its named collection. The variables can be in either the cookies, forms, or querystring collections.
##RVD | n/a | Defines the default value to assign to a variable.
##SPL | n/a | Defines a database stored procedure link. Generally used to indicate which stored procedures are referenced or used in the construction or servicing of a web request. May also be used to indicate any SQL object when used with DBDocumentor produced database documentation.
##SV | ##SV_BEGIN - ##SV_END | Describes a session variable.
##VDD | n/a | Defines the translation between a virtual root and its physical location on disk
##WO | ##WO_BEGIN - ##WO_END | Describes a web dialog window opened in client side code whose target is a window other than the current window
##WOQ | ##WOQ_BEGIN - ##WOQ_END | Describes querystring parameters used to open a web dialog window from client side code whose target is a window other than the current window
* @description | n/a | Describes a method.
* @object | n/a | Describes an object reference.
* @param | n/a | Describes a method variable.
* @return | n/a | Describes the return value of a function.


Global tags

Global tags are specified in either ASPHelp.ini, or in global.asa. These tags have global scope to the project and will affect all all the pages in the project.

In addition to all the specific global tags described here, if any of the other ASPHelp tags are specified in one or the other global file, they will also be assumed to have global scope. For example, if the ##SV tag is used in global.asa to define a session variable named "foo", then all the pages in the project will be assumed to be using this variable.

Tags Valid Only at Global Level

The following tags are valid only at the global level, that is to say in either ASPHelp.ini or global.asa

Tag | Description
##CO | Provides a copyright description. Valid only in registered versions of ASPHelp.
##MLD | Defines the string action to take on the named method.
##PR | Provides a project description. All ##PR tags in the project are combined to make the final title page.
##RVD | Defines the default value to assign to a variable.
##VDD | Defines the translation between a virtual root and its physical location on disk


##CO Tag

The ##CO tag denotes a copyright. Copyrights will appear at the bottom of all compiled files. The ##CO may only appear in the ASPHelp .ini file.

Since the #CO is not legal ASP, it must appear inside a comment. If multiple tags exist for the same element, they will be concatenated.

Syntax

##CO Comment

Or

##CO_BEGIN
Copyright
##CO_END

Example

'##CO ©2004 MyCompany.com. All rights reserved.

Evaluation Output

If you compile the your project with an evaluation copy of ASPHelp, this warning will be at the botton of each page.


##MLD Tag

The ##MLD tag provides a unique capability within ASPHelp. Using the ##MLD tag you can define approximate behaviors for procedures and methods at a global level. It is intended to describe those global methods which provide formatting of URLs or other elements ASPHelp uses in its documentation efforts.

The ##MLD is global in nature and valid only in global.asa or ASPHelp.ini.

Syntax

The syntax for ##MLD is unique. It provides you with the ability to define different behaviors for each parameter in a method. Note that there is no requirement that all parameters be included.

##MLD Method Name ^^ Parameter Number ^^ Definition Type

Where Method Name is the name of the method name being defined,
and Parameter Number is the zero-based number of the parameter being defined
and Definition Type one of the following values:
0 - Parameter contains a string that is root relative and should have the ? symbol appended
1 - Parameter is a simple string that should have the & symbol appended
2 - Reserved
3 - Reserved
4 - Parameter is a simple string that should have the ? symbol appended
5 - Parameter is a simple string
6 - Parameter contains a string that is root relative
7 - Parameter contains a string that is root relative and should have the & symbol appended

Example

Consider the following ASP sample:

<A href="<%=pageURL("Home.asp")%>">Testing</A>

Without the ##MLD, this anchor would be documented as having an Action Location defined by the ASP fragment: pageURL("Home.asp")

If the following ##MLD were applied:

##MLD pageURL ^^ 0 ^^ 6

this anchor would be documented as having an Action Location of Home.asp, and the Action Location would be hyperlinked.


##PR Tag

1>

The ##PR tag denotes a project definition. The project definition is included in the default page of the compiled help file. ##PR tags may only appear in the ASPHelp .ini file. Multiple lines are permitted and will be concatenated together to form the full project definition.

Since the ##PR is not legal ASP, it must appear inside a comment. If multiple tags exist for the same element, they will be concatenated.

The block comment version of this tag is ##PR_BEGIN and ##PR_END. The end tag must be present for the tag to be valid.

Syntax

##PR Comment

Or

##PR_BEGIN
Comment
##PR_END

Example

' ##PR_BEGIN

'This project forms the web application for the transaction processing
'system for our new book store. Only those pages relating to the sale
'of merchandise are included.

'##PR_END


##RVD Tag

As the ASP in your project is parsed, ASPHelp attempts to determine the values assigned to variables it encounters. It will attempt to use such variables whenever it is displaying a default value or encounters a string that should be included in the output file descriptions. If there is a default value that ASPHelp should use for a given variable, ##RVD allows its definition.

The ##RVD is global in nature and valid only in global.asa or ASPHelp.ini. Its definition will apply to all pages in the project.

Syntax

##RVD Variable Name ^^ Replacement Text

Where Variable Name is the name of the variable to be replaced,
and Replacement Text is the text to replace the variable with

Example

' ##RVD strRootPage ^^ HomePage.asp

In this example, if ASPHelp encounters the ASP variable strRootPath, it will replace it with the string HomePage.asp.


##VDD Tag

The ##VDD tag describes the physical location of virtual directories. If you application makes use of virtual directories, ASPHelp does not natively have access to them. If you wish to have the content or pages referred to by a virtual folder, the ##VDD tag provides a means of specifying this mapping.

Please note that the ##VDD tag is unable to resolve UNC pathed physical folders or resolve to alternate virtual folders.

The ##VDD is global in nature and valid only in global.asa or ASPHelp.ini.

Syntax

##VDD Virtual Directory ^^ Physical Directory

Where Virtual Directory is the name of the virtual path to be resolved,
and Physical Directory is the directory it is resolved to

Example

' ##VDD /Content ^^ D:/Content


Generic Tags

Documentation tags ASPHelp

Generic page tags

The generic tags provide basic layout and description capability on a page by page level.

Tags

Tag | Description
##AT | Provides an "Applies To" description. The "Applies To" section allows the developer the capability to group functional pages in the final compiled output.
##BD | Provides a page description.
##NOV | Reverses any override directive in effect. If no override directive is in effect, the ##NOV tag has no effect.
##OV | Denotes an overridden page. Overridden pages do not have any of their content parsed, rather the values explicitly named are included in the compiled help.


##AT Tag

Provides an "Applies To", or table of contents description. The "Applies To" section allows the developer the capability to group functional procedures in the final compiled output. Default categorizations remain as appropriate to the object being documented, but the ##AT tag only applies to your custom categorizations and allows you to span web pages.

If a tag is found at the batch level, it must have been defined at the ASPHelp.ini level or it will be ignored.

Syntax

Page: -- ##AT Section

ASPHelp.ini: -- ##AT Section ^^ Comment

Where Section is the name of the applies to section the developer wishes to group pages by,
and Comment is the documentation text to use.

Example

'##AT Product Catalogue ^^

'##AT Product Catalogue ^^ These pages are define the functionality
'##AT Product Catalogue ^^ of the product catalogue.

Sample Output

In this example we see the default applies to sections.

© Pikauba Software 2001-2003. All rights reserved.


##BD Tag

The ##BD tag defines an ASP page. An ASP page is any file that is included for processing in the project.

Since the ##BD is not legal ASP, it must appear inside a comment. If multiple tags exist for the same element, they will be concatenated.

The block comment version of this tag is ##BD_BEGIN and ##BD_END. The end tag must be present for the tag to be valid.

Syntax

##BD Comment

Or

##BD_BEGIN
Comment
##BD_END

Example

' ##BD Product.asp Displays the specified product to the user.


##OV Tag

If your procedure contains complex ASP or HTML, it may not be parsed correctly. It is recommended that you first try to parse the ASP using ASPHelp to see if any issues are present before using the override tag.

If the ##OV tag is present, the following items are not processed:

  • Anchors
  • HTML Forms
  • Cookies
  • Request Forms
  • Request QueryString
  • Generic Input
  • Redirects
  • Session variables
  • Application variables

TIP: If you want to have an entire project have the override tag, either define the tag in either the ASPHelp.ini or global.asa file, or select the Do not parse code from step 2.

Syntax

'##OV


##NOV Tag

If you have defined a global override as described under the ##OV tag, you can reverse that tags effect on a page by page basis by including the ##NOV tag in the page.

Technically there is no reason to remove any existing ##OV tag, but from a readability perspective removal of the ##OV tag is recommended.

If there is no override directive in effect for a page containing the ##NOV tag, it will have no effect on the output file.

Syntax

'##NOV


HTML tags

The HTML tags are used to define the intended purpose of the specified HTML element. These purposes are key in describing the behavior and intent of a given web page, and more importantly how it interacts with the other pages making up a dynamic web. There are HTML documentation tags for all the standard HTML tags which generate page transitions. The uniqueness key for all HTML tags is the name attribute of the tag.

NOTE: If the HTML that is present in the files to be documented, be that HTML dynamically generated, or statically defined, has not been validated, ASPHelp may experience some difficulties. Specific problems will arise if tags are not closed, or if tag attributes are not enclosed in quotes. For example, if an anchor tag is missing its </A>, then there is a real possibility for ASPHelp to include items in its documentation of the anchor which are not intended. Another good example are tags for whom a height or width has been specified as a percentage, but that percentage is not enclosed in quotes. In this case, there is the possibility that ASPHelp will interpret the height or width attribute as an ASP closing tag.

NOTE: Unless operating in override mode, only those HTML elements defined to be processed will have their tags read.

HTML Element Documentation Tags

Tag | Description
##AN | Describes an anchor.
##FM | Describes a FRAME or an IFRAME
##FMV | Describes query string parameters associated with a FRAME or an IFRAME
##FR | Describes an HTML form on the page.
##FV | Describes the form variable of a form
##IM | Describes an image map
##IMA | Describes an image map area associated with an image map
##QI | Describes the query string variable of an anchor
##QIM | Describes the query string associated with an image map areas' link

Anchor Tags

Tag | Description
##AN | Describes an anchor.
##QI | Describes the query string variable of an anchor

Form Tags

Tag | Description
##FR | Describes an HTML form on the page.
##FV | Describes the form variable of a form

Frame or IFrame Tags

Tag | Description
##FM | Describes a FRAME or an IFRAME
##FMV | Describes query string parameters associated with a FRAME or an IFRAME

Image Map Tags

Tag | Description
##IM | Describes an image map
##IMA | Describes an image map area associated with an image map
##QIM | Describes the query string associated with an image map areas' link


ASP Variable Tags

Documentation tags ASPHelp

ASP Variable Cache Tags

ASP cache variable tags allow for documentation of the use of the session and application object data caches. When not running in override mode, documentation of these data caches will only occur if they have been defined to be included in the project.

If you are not using the intrinsic ASP session object, it is possible to have your custom session objects' usage documented by specifying the name of the session object variable. It is a requirement that the same session object name be used for the entire project (but different projects can have differing names for their session objects), and that the session object have a defined property for its session variables. For example, if you use a session object whose variable name is objSession, and whose session variable access property is SessionVariables, then you would define it in step 2, under the session options tab.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix if _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

ASP Variable Cache Documentation Tags

Tag | Description
##AV | Describes an application variable.
##SV | Describes a session variable.


Request and response tags

Request and response tags are used to describe the inbound data flow on a web page, and to describe the internal page transition logic on the server side. When matched with the corresponding referring page's action (Anchor, Form, or Image Map), data flow can be verified.

Some of the tags used for documentation purposes have alternate block commenting forms. These alternate forms permit items to be annotated in detail without requiring a new documentation tag on each line. Note that for any given object, only the single line or block comment tags may be used. If the tag styles are combined for any object, the single line comments will only be used.

All block comment tags have the same name as their single line counter part, just with a suffix if _BEGIN and _END.

Note: When using the block comments, the leading single quote character (') used to comment VBScript will be removed. If you wish to have a single quote character begin a line, you must provide two (i.e. one to start the comment and one for the documentation.

Request Tags

Tag | Description
##RC | Describes a cookies collection.
##RF | Describes an input form (POST) variable.
##RQ | Describes an input querystring (GET) variable.
##RV | Describes an input variable that is not accessed via its named collection. The variables can be in either the cookies, forms, or querystring collections.

Response Tags

Tag | Description
##RC | Describes a cookie in the response.
##RR | Describes a redirection in the response.
##RQI | Describes the query string associated with a redirection


Documentation Licensing Agreement

Please note that this is an abridged version of the licensing agreement associated with ASPHelp. This abridged version is present for those users who (a) downloaded the documentation separately from the product, or (b) are viewing the documentation prior to product use. This agreement follows a plain English format.

  1. RIGHTS TO USE

    By downloading this documentation, or viewing this documentation prior to actual use of the product (ASPHelp), you are agreeing that the procedures and techniques described in this documentation are proprietary to Pikauba Software. You have the right to use this documentation in the use of and evaluation of ASPHelp, but may not use this documentation for any other purpose, including:
  • Product reviews, without previously informing Pikauba of this intent. This restriction is in place to ensure that any reviews are conducted with the most recent public version of the product, and to ensure that any reviews are from product usage, not details present in documentation.
  • Design of competing products, or inclusion of feature concepts in products not directly competing with Pikauba Software products. This restriction is in place largely to protect any derivative works from being developed. If you believe that you might wish to make use of any concept presented here in a product, please contact mailto:sales@pikauba.com. In many cases a simple agreement can be reached allowing specified derivations to be conducted.
  • Extraction of product screen shots or other images for any use. If you are planning on writing a product review, or providing any level of image linkage related to this product, we have found that use of the most recent image is the most effective course of action. Since product development is ongoing, the images you may have obtained from this documentation may no longer be relevant. Please contact mailto:sales@pikauba.com if you wish to make use of product images and details can be arranged to ensure your content is as accurate as possible.
  2. WARRANTY

    Use of this documentation does not convey any warranty, or suitability to purpose of either the documentation or its associated product. This documentation was obtained free of any charge from Pikauba Software. In no event shall Pikauba Software be liable for any damages, including any loss of revenue, loss of profit, incidental, indirect or consequential damages resulting from the use of this documentation, or its associated product. Further details relating to limitation of liability can be found in the file License.txt which is included with the product.

© 2001 - 2005 Pikauba Software. All rights reserved.


##ANLD Tag

The ##ANLD tag defines the default location for an ##AN tag when running in override mode. The default location refers to the local URL of the page this anchor would link to if implemented.

Syntax

##ANLD AnchorLinkText ^^Location

Where AnchorLinkText is the text for the parent anchor,
and Location is the page to use for the default link.

Example

' ##AN Home Base ^^ Send the user to the home page.
' ##ANLD Home Base ^^ home.asp


##FMLD Tag

The ##FMLD tag defines the default location for an ##FM tag when running in override mode. The default location refers to the local URL of the page this frame or IFrame would link to if implemented.

Syntax

##FMLD FrameLinkText ^^Location

Where FrameLinkText is the text for the parent frame or IFrame,
and Location is the page to use for the default link.

Example

' ##FM Main ^^ The main page display frame
' ##FMLD Main ^^ No default defined. Each link will provide its own.


##FMVD Tag

The ##FMVD tag defines a default value for use with a query string parameter associated with a frame or inline frame. The ##FMVD tag will be ignored when not running in override mode, and if no corresponding ##FM tag exists to define the frame, or if no ##FMV tag exists to define the query string parameter.

Syntax

##FMVD FrameName ^^ VariableName ^^ Default

Where FrameName is the name for the parent frame,
and VariableName is the name of the query string variable,
and Default is the default value to use.

Example

' ##FM Help ^^ Our centralizaed FAQ system
' ##FMLD Help ^^ faq.asp
' ##FMV Help ^^ section ^^ The section of the FAQ we are showing the user
' ##FMVD Help ^^ section ^^ The value will be obtained from the input querystring to the page


##FRAM Tag

The ##FRAM tag defines the default access method for an ##FR tag when running in override mode. The default access method should be either GET or POST, but the value is not validated against HTML or HTTP specifications.

Syntax

##FRAM FormLinkText ^^Method

Where FormLinkText is the text for the parent form,
and Method is the access method to use by default.

Example

' ##FR Search ^^ The search form
' ##FRLD Search ^^ searchresults.asp
' ##FRAM Search ^^ POST


##FRLD Tag

The ##FRLD tag defines the default location for an ##FR tag when running in override mode. The default location refers to the local URL of the page this form would link to if implemented.

Syntax

##FRLD FormLinkText ^^Location

Where FormLinkText is the text for the parent form,
and Location is the page to use for the default link.

Example

' ##FR Search ^^ The search form
' ##FRLD Search ^^ searchresults.asp


##FVD Tag

##FVD Tag

The ##FVD tag defines the default value for a form variable of a form. The ##FVD tag will be ignored when not running in override mode, and if no corresponding ##FR tag exists to define the form and no ##FV tag exists to define the variable.

See the ##FVT tag for details on defining a data type for the variable.

Syntax

##FVD FormName ^^ VariableName ^^Default

Where FormName is the name for the parent form,
and VariableName is the name of the form variable,
and Default is the default value to use.

Example

' ##FR frmLogin ^^ The form to use for login. This needs to be SSL based.
' ##FV frmLogin ^^ group ^^ Users can choose to login via group membership, or not.
' ##FVD frmHome ^^ group ^^
' ##FVT frmHome ^^ group ^^ CHECKBOX


##FVT Tag

The ##FVT tag defines the data type of the default value for a form variable of a form. The ##FVT tag will be ignored when not running in override mode, and if no corresponding ##FR tag exists to define the form and no ##FV tag exists to define the variable.

Syntax

##FV FormName ^^ VariableName ^^Data Type

Where FormName is the name for the parent form,
and VariableName is the name of the form variable,
and Data Type is the intended HTML form data type to use for the variable. Please note that this value is not validated to allow for maximum flexability.

Example

' ##FR frmLogin ^^ The form to use for login. This needs to be SSL based.
' ##FV frmLogin ^^ group ^^ Users can choose to login via group membership, or not.
' ##FVD frmHome ^^ group ^^
' ##FVT frmHome ^^ group ^^ CHECKBOX


##IMLD Tag

The ##IMLD tag defines the default location for an ##IMA tag when running in override mode. The default location refers to the local URL of the page this image map would link to if implemented.

Syntax

##IMLD ImageMapLinkText ^^ Image Map Area ^^ Location

Where ImageMapLinkText is the text for the parent image map,
and Image Map Area is the section of the image map we are working with,
and Location is the page to use for the default link.

Example

' ##IM Logo ^^ The section of the logo that when clicked sends the user to the home page
' ##IMA Logo ^^ Home ^^ The section of the logo that when clicked sends the user to the home page
' ##IMLD Logo ^^ Home ^^ home.asp


##QID Tag

The ##QID tag defines the default value for a query string variable of an anchor. The ##QID tag will be ignored when not running in override mode and if no corresponding ##AN tag exists to define the anchor, and if no ##QI tag exists to define the variable.

Syntax

##QID AnchorLinkText ^^ VariableName ^^Default

Where AnchorLinkText is the hyperlinked text for the parent anchor,
and VariableName is the name of the query string variable,
and Defaultis the default value to use.

Example

' ##AN Home Base ^^ Send the user to the home page.
' ##QI Home Base ^^ group ^^ Users have customized home pages based on their group membership.
' ##QID Home Base ^^ group ^^ Defined by session variable


##QIMD Tag

The ##QIMD tag defines a default value for a query string variable of an image map area. The ##QIMD tag will be ignored when not running in override mode, and; if no corresponding ##IM tag exists to define the image map, if no corresponding ##IMA tag exists to define the image map area, and if no ##QIM tag exists to define the query string.

Syntax

##QIMD Image Map Name ^^ Image Map Area Name ^^ VariableName ^^ Default

Where Image Map Name is the name of the map the image map area is part of,
and Image Map Area Name is the name of the image map area whose source link contains the name variable,
and VariableName is the name of the query string variable,
and Default is the default value to use.

Example

' ##IM Logo ^^ The section of the logo that when clicked sends the user to the home page
' ##IMA Logo ^^ Home ^^ The section of the logo that when clicked sends the user to the home page
' ##IMLD Logo ^^ Home ^^ home.asp
' ##QIM Logo ^^ Home ^^ UserType ^^ The type of user we are working with, and need to customize the page for
' ##QIMD Logo ^^ Home ^^ UserType ^^ The default value will be passed in as part of the query string.


ASPHelp - Select Input

User interface ASPHelp

Select input folder

In this dialog you select the location of the files for the project. The default extension is *.asp, but other types are supported, simply select a file of that type.
Both the folder and the default extension are saved for future runs of ASPHelp.

Press Save when done


ASPHelp - Select Output

User interface ASPHelp

Select output folder

In this dialog you select the location of the output files for the project. The output files consist of the project chm file, and all HTML files required to prepare a web site containing the documentation.

You are required to enter a name for the chm file. This name, including case, will become the project name for this project.
Note that these values are saved for future runs of ASPHelp.

Press Save when done


##SQL Tag

The ##SQL tag allows you to define SQL object usage in your ASP page, and link that usage to the underlying database. If you are linking to a SQLHelp defined project, then you are limited to describing stored procedures, but if you are linking to a DBDocumentor project, you can describe the usage of any SQL object. Please see this page for more information on the integration.

Note: In order to make full use of the DBDocumentor/SQLHelp and ASPHelp linkage, you will need to have both products installed on the same machine, and will need to have the output files located in the same folder. ASPHelp will provide warnings on this subject.

Note: To learn more about SQLHelp, please visit the Pikauba Software web site at this link.

Note: To learn more about DBDocumentor, please visit the Pikauba Software web site at this link.

Note: If you are using case sensitive SQL objects, the case of the object name in the ##SQL tag must match exactly the physical object name as defined to DBDocumentor/SQLHelp.

Note: The ##SQL tag was known in previous versions of ASPHelp as the ##SPL tag. Use of the ##SPL tag is currently supported, but if you are using it, you should consider migrating to the ##SQL tag.

Syntax

##SQL ProcedureName ^^ Comment

Where ProcedureName is the name of the stored procedure as it was described in DBDocumentor/SQLHelp,
and Comment is the comment text to use.


ASPHelp - Step 5 - Processing completed

User interface ASPHelp

Step 5 - Processing complete

When processing of the project has completed, step 5 will be displayed.

  • Exit ASPHelp If selected, when you press the close button ASPHelp will exit.
  • Select a different project or define a new project If selected, when you press continue, ASPHelp will go to Step 1.
  • Reload the current project and change project options If selected, when you press continue, ASPHelp will go to Step 2.
  • Rerun the current project with all current processing options If selected, when you press continue, ASPHelp will go to Step 4 and the project will re-run.

Pressing "?" will display this page.

© 2001 - 2005 Pikauba Software. All rights reserved.


Stylesheet Elements

Documentation Procedures ASPHelp

Custom Stylesheets

Using the XML project file, an alternate stylesheet can be defined for a project. This alternate stylesheet must contain all the elements and classes defined in the standard default stylesheet, or presentation errors will result.

Note: The stylesheet must be located in the same folder as the XML file, or in a sub folder beneath it. If the stylesheet can not be found during output compilation, the default stylesheet will be use.

Note: If you are working with an unregistered version of ASPHelp, the contents of this element will be ignored.

Tip: When defining a custom stylesheet, copy the default stylesheet from the installation path. Failure to do so will result in your changes being overwritten if you upgrade ASPHelp.

Classes

This section describes the classes contained in the default stylesheet.

clsSource

clsSource is used whenever source is to be formatted.

clsSectionLink

This class is used for the links on any table of contents summary page.

clsSectionHeader

This class is used for any section headers. A section header is the text used to denote a change in context in a summary page. Examples of section headers include Access method, Object usage, and Client navigation.

clsTableHeader

This class is used for the header row of all data tables, and the key column of all attribute tables. Examples of data tables include the parameters of methods.

clsTableBorderKey

This class is used for for the content key used in a table row. The content key is the unique identifier for the row.

clsTableBorderDataType

This class is used for table content which contains a data type.

clsTableBorder

This class is used for all table content which is not keyed or data type content.

clsSyntax

This class is used to define the formatting of the text describing the syntax of the page.

clsObjectDescription

This class is used for the description of the page.

clsLabelHeader

This class is used for the object type and file location headers.

clsLabelDescription

This class is used for the object type and file location values.

clsBase

This class contains the last item on each page. By default this class determines how topics in the CHM are printed, but should you desire suppression of the "compiled by Pikauba Software" link at the base of each page, make this class hidden.

© 2001 - 2005 Pikauba Software. All rights reserved.


Valid HTML for Pikauba Products

Documentation tags ASPHelp

Valid HTML for Pikauba product documentation

Throughout this manual you will encounter the term "valid HTML". For the purposes of describing your objects, "valid HTML" differs slightly from regular page oriented HTML in a number of ways. For example, "valid HTML" has the following characteristics:

  1. It is an HTML page fragment. That is to say, it can not contain any <HTML> or <BODY> tags.
  2. Descriptions must have valid HTML syntax for inclusion within <P>, <TD> and <BLOCKQUOTE> tags. If this requirement is not met (i.e. the description includes a closing tag, or an object which is not valid for use within these containers), minimally you will have poorly formatted output. Please be aware that very poorly formatted HTML fragments have been known to cause the HTML Help workshop compiler to crash.
  3. If you make use of HTML 4.0 or higher tags, please be aware that the HTML Help compiler may not function correctly. The HTML should be HTML 3.2 compliant.
  4. Non-Microsoft Internet Explorer tags may cause problems with the output. Please do remember that the HTMLHelp viewer is using Internet Explorer components and as such may not render tags specific to other browsers.
  5. Only use Microsoft HTML extensions appropriate to the lowest common browser you expect anyone to view your documentation on. For example, if you were to leverage IE 6.0 concepts in you descriptions, those pages may not render correctly when viewed on a base Windows 2000 system using IE 5.0.
  6. If you desire to make use of raw HTML or XML tags in you descriptions, place them within <PRE></PRE> tags. The <PRE> tags will use the system default font, but can be overridden with stylesheets.
  7. Each Pikauba Software product comes with a default stylesheet named stylesheet.css. Please feel free to customize this file as your needs warrant, but do bear in mind that if you perform an upgrade of a Pikauba Software product, this file will be overwritten during the upgrade process. In other words, make certain you back this file up before you upgrade.
  8. If you reference a local file in your description and that file is not present when the project compiles, a compilation error may occur in hhc.exe. If you see such an error and have local file references which were not generated by a Pikauba Software product, please contact Pikauba support for assistance in determining a resolution.

Formatting HTML/XML for output

If you are formatting HTML or XML for display to the user (i.e. as part of an example), you must either escape the "<" and ">" characters, or place the XML within a <PRE> block and apply a style to the <PRE> block.

© 2001 - 2005 Pikauba Software. All rights reserved.