gform Version 1.1d notes.	10-Oct-95 HR

Also note that docco is available in HTML as gform.html and for the
latest check http://www.swin.edu.au/csit/gform.html

1.0 	gform - generic web forms handler

	The problem with forms is that they all need their own
   program or script to handle the fields in the form and perform
  some sort of action. Most often you want to collect submitted forms 
  in a file or send it thru the mail to yourself or someone else
  who can colate these.  
   
   I find that web information providers are generally not programmers
   and therefor can not easily write their own form programs.

   gform addresses the problem of application style forms.
   It enables the results of a form to be formatted and send 
   to a file or via the mail. ( You could also forward mail to
   a "mail-to-print" gateway and get hardcopies ).

1.1 How it works

    In HTML you use the tag FORM to specify a form and you use 
    'ACTION' to describe which scipt/program will handle the form
    data. You specfy the ACTION as 'gform'
 
    In the HTML tag set there is a tag for comment <!-- .. --> 
    What gform does is read comments that start with <!--gform ... -->
    These special comments contain commands for gform. 
    Any number of these <!--gform ..--> comments maybe used anywhere
    in the file. 

    (NOTE: The old TAG format of <!gform is still supported and will
     probably work Ok, but it is not the correct syntax for
     a HTML comment. Therefor the "<!--gform" form is encouraged.)

    Gform works with various FORM specifiers such as Textarea, 
    radio buttons, checkboxes, multiple choice selections. 

1.2 syntax of gform commands

    There are 2 types of <!--gform ... --> commandlines. 

	Firstly, variables and text strings. Variables start with
	a '$' sign followed by the variable name as specified on
	the HTML INPUT tag in the HTML form file. The varables you use
	should be those that you specified in the INPUT tags.
	If the variable doesn't match, it will look for the variable
	in the"environment" (See environement variables notes).
	If it can't find it there it will return "null".
	Beaware that "type=checkbox" returns "null" if it is 
	unticked. This is a side effect of how forms are handled.

	You can also specify variables by enclosing them with
	brackets and prefixing a dollar char: '$(variable)'
     	This is handy if you want text straight after the variable 
	name. 

	Variables maybe freely mixed with text. The following example 
	will send the text string and replace the "$name" variable 
	with what was given in the form submission.

	<!--gform "Form submitted by: $name"-->

	You will have to specify newlines and tabs by escaping them.
	by preceding a special char with a '\'. 
        The following escaped chars are recognised:

		\n	- newline
		\t	- tab
		\f	- form feed
		\r 	- return
		\$	- Escape a dollar sign
		\"	- Escape a double quote
		\\	- Escape a slash 

	So using the above example with a newline appended;

	<!--gform "Form submitted by: $name\n And more text"-->

2.0 	There are 2 special variables $(date) and $(time) that can be
	used to return the current date and time.

2.1	Environment variables.

	An extra bit was added (6-oct-95) that returns the values
	of CGI environment variables.

	For example;

	<!--gform "Remote host is: $(REMOTE_HOST)\n"-->

	will return the value of the remote host that submitted the
	form. 

	These variables can also be seen in action with the "test-cgi"
	shell script that comes with the CGI distribution.

	The following variables exist:
	
	SERVER_VERSION		REDIRECT_REQUEST
	SERVER_SOFTWARE		REDIRECT_URL
	SERVER_NAME		REDIRECT_STATUS
	SERVER_PORT		GATEWAY_INTERFACE
	REMOTE_HOST		SERVER_PROTOCOL
	REMOTE_ADDR		REQUEST_METHOD
	REMOTE_USER		PATH_INFO
	REMOTE_GROUP		PATH_TRANSLATED
	REMOTE_IDENT		SCRIPT_NAME
	DOCUMENT_ROOT		QUERY_STRING
	ANNOTATION_SERVER	CONTENT_TYPE
	AUTH_TYPE		CONTENT_LENGHT
	HTTP_ACCEPT
	HTTP_USER_AGENT
	HTTP_REFERER
	
	(The usefullness of variables with gform is debatable.
	 However, it was easy to implement. The meaning of all these
	is documented elsewhere, try http://www.yahoo.com )	

2.1
	The second commandline type that is recognised are lines with 
	keywords.  These control where and how the form data is handled.
        The following are recognised.

    The next line will put the results in the file "/path/of/file"

	<!--gform deliver=file "/path/of/file"-->

    The next example will email the results to "address@swin.edu.au"

	<!--GFORM deliver=mail "address@swin.edu.au"-->

    and optionally specify a subject

	<!--gform deliver=mail "address@swin.edu.au" subject="form Submission"-->
    To print the results directly to a printer use, 

	<!--gform deliver=print "hp"-->

    where "hp" is the name of a printer as found in your /etc/printcap

    This following example displays the HTML file 'thanks.html' after 
    the form has been submitted. The pathname of "thanks.html" is 
    relative to your WEB directory (Absolute pathnames can also be 
    given).

	<!--gform reply="thanks.html"-->

    (commands and variables are case-insensative)

    There is a compile time option that can enable tilde ( ~ )
  character file expansion. If enabled, a "~user" in the http reference
  will expand to a users home directory and a subdirectory 
  if so configured.

For example; 

	~harry/foo.html

will expand to the users home directory ( plus to whatever USERDIR is
defined to be . See INSTALL notes ) 

and 

	<!--gform reply="/~user/html/foo.html"--> 

is also expanded to a users home directory.

1.4 Complete examples.

    See the files
	sample.html
	sample2.html 
	sample3.html