===================
 VBDoc : User guide
===================

DESCRIPTION
===========
VBDoc is a simple utility which creates HTML pages out of your program 
comments. All you have to do is to get your comments started with easily 
memorizable tags. This is the only way to get a value-added documentation, 
worth readable outside the VB environment.
I made VBDoc for a own project, to content the customer's will of getting a 
complete, meaningfull and evolutive technical documentation on a 200 forms 
project.


INSTALLATION
============
Just Unzip the Zip file and run setup.exe, or click on 'install' in Winzip.
VBDoc will be placed in Program Files\VBDoc, along with an example VB program.


USER GUIDE
==========
- Open a VB 5 project
	
	The forms included in the project are listed in the VBDoc window.
The project himself figures in the first line: it's extractible and will 
make the summary.
A document icon preceeding the form indicates a documented form.
A red light means the source has been modified since the last 
extraction.
A green light indicated an updated documentation.

- Select one or more forms, and click on 'Extract'

	Please take care of extracting the project himself at the last place, 
for its documentation will contain information based on the forms (like 
the form's title).
Each Html page is created in the directory declared in the .ini file.

- Click on 'Preview' to launch IE3, or use your own browser.



TAG DESCRIPTION
===============

This is a description of the 6 tags you'll have to remember:

- #O : form/function/proc object
--------------------------------
To give a title to a window, place a #O in the "General/Declaration".
This will constitue your page title.
To give a title to a function or proc, place the #O before it.

Example of a form title:
[general/declaration]
'#O Customer management form
Const C_VALIDATE = 0
...
or for a proc title:
'#O Insert a new customer in the database
Sub p_Create ()
...
End Sub


- #D : form/function/proc description
-------------------------------------
Just after a #O comment, place a #D for a better description.

Example:
'#O Customer account management form
'#D This form is used to add, modify, or delete a customer
'#D BlaBlaBla...
Const C_VALIDATE = 0
...

Use the #D to describe a proc in term of functionnalities, to assure a global 
understanding outside any procedural approach.
You can also use it to declare function paramameters.

- #E : Event
----------------
This tag identifies an external event, most of the time following a user 
action.

Exemple : 
Sub Command1_Click ()
	'#E User clicks on VALIDATE
	p_Create
End Sub



- #A : Action
-------------
This tag allows to describe a portion of code.
It's binded to the sub or event just preceeding.

Example:
'#O Add a customer in the database
'#D This proc is called when the user clicks on 'Validate'
'#D A new customer record is then added on Oracle's T_CUSTOMER
Sub p_Create ()
	'#A Open a new transaction
	BeginTrans
	'#A Find the next customer number
	...
	'#A Insert a new record
	...
	'#A Update the next customer number
	...
	'#A Close the transaction
	CommitTrans
End Sub

You can have your #A comments indented in the HTML page by adding A's.
Example:
'#A Scan the customer's type:
Select Case CustomerType
	'#AA Type 1 processing:
	Case 1
		'#AAA Open a new file...
...


- #P[file name] : Image (Picture)
-------------------------------
This tag is used to reference an image which will be included in the Html 
page.
This could be a screen shot (better taken during runtime), or a data flow 
diagram helping the program comprehension.

Example:
'#X[Chart1.jpg]



- <html ref> : Refers to an other HTML document
-----------------------------------------------
With the #D, #E and #A tags, you can refer to an other HTML document.

Example:
'#A Insert a new customer in the <T_CUSTOMER> table
Refers to a T_CUSTOMER.htm document which could contain the table description.

An other example:
'#O Customer account management
'#D This form is used to manage the customer account
'#D It's called from <MAINMENU> and can go to <CUSTOMER_WINDOW_1>


- Miscellaneous
---------------
o  A minus sign prevents VBDoc from putting a CR at the end of the line.
Example:
'#O Customer account management
'#D This form is used to manage the customer account
'#D It's called from <MAINMENU> -
'#D and can go to <CUSTOMER_WINDOW_1>

o  Html documents inherit the form name, followed by .htm. Don't forget this 
if you want to set hypertext links between your forms.

o  Undocumented procs are signaled at the end of the document.

o  Form_Load, Form_Activate, and Command1_Click, if detected, are placed at 
the beginning of the document.

o  Please excuse my poor english, and thank you for using VBDoc !

AUTHOR
======
VBDoc is an original creation of:
Jean-Louis Ercolani
1, Place des Boutons d'Argent
Residence les Bordieres
94000 CRETEIL
FRANCE
ajl@isicom.fr
jean-louis.ercolani@seita.fr (emergency only please)





