INTRODUCTION
------------

This file explains how to translate Tcl/Tk man pages into html pages.  The 
translation program is written entirely in Tcl and so should run correctly 
on all supported platforms.  It has been tested on a PowerMac and SunOS.

The script is designed to support the translation of all Tcl packages that 
follow Sun's man page conventions.  So if you want fully cross-referenced and 
hyperlinked documentation of Tcl, Tk, itcl and expect, this script should 
work as long as all commands and library calls have unique names.


USAGE
-----

Start tclsh or wish and source man2html.tcl. At the tcl prompt type

	main tcl_dir html_dir packages...

where 

'tcl_dir' is the master directory containing Tcl distributions (or 
	'packages').  

'html_dir' will be the top level directory containing the HTML files 
	produced by the program.  This directory will be created by the 
	script. Except for temporary files, all output of the script goes
	here.

'packages...'  are the names of distributions in the 'tcl_dir' directory  
	which will be converted.  man2html.tcl expects to find unconverted (no 
	man.macros expansion) man pages in the doc sub-directory of each
	distribution. Converted man pages, e.g. those in man/mann, will not
	work.
	
For example,

	main Tcl-Tk_docs /usr/local/src/tcl tcl7.6b1 tk4.2b1

should work for a standard Unix installation of the current beta.  In this 
case, the script expects to find the Tcl man pages in the 
/usr/local/src/tcl/tcl7.6b1/doc directory and the Tk man pages in the 
/usr/local/src/tcl/tk4.2b1/doc directory.

man2html.tcl hasn't been tested with other distributions, but it should 
work if they follow the directory structure and man page convensions of Tcl 
and Tk.  Build time for Tcl/Tk is about 8 minutes on a Sparc 10 or a 
PowerMac 7100/66 using tcl7.6b1.  (On the Mac, tcl7.5 is about 3 times 
slower than tcl7.6b1; thanks Ray.)


SCRIPT OVERVIEW
---------------

The translation process is a two pass affair with each pass traversing all 
packages.

The first pass builds an array (NAME_file) that defines the relationship 
between cammand and library names and the files that they are documented 
in.  The first pass also builds an array (KEY_file) that defines the 
relationship between keywords (found in the Keyword section) and the files 
those words appear in.

The second pass actually generates the html pages.  It uses information in 
the NAME_file to insert hyperlinks at every bolded phrase that satisfies 
two requirements.  The first word of the phrase must match a name in the 
NAME_file array and the name must not reference the current file.  In rare 
cases, this leads to nonsensical hyperlinks, but such is the price of 
automation.

Finally the cross reference file is built using information in the 
KEY_file.

The translation script is broken into four files:

man2html.tcl -- This file defines the main procedures that convert man 
	pages to html. It sources the other files to perform the first and  
	second passes. It also generates the contents for each package and  
	the cross-reference file (xref.html).

man2tcl.tcl -- This file contains a program that turns a man page of the 
	form used for Tcl and Tk into a Tcl script that invokes a Tcl command  
	for each construct in the man page. These commands are defined (and
	re-defined) in the following files.

man2html1.tcl -- This file defines procedures that are used during the 
	first pass of the man page to html process. These procedures invoke 
	man2tcl.tcl, save its output in temporary files, and build the 
	NAME_file and KEY_file arrays.

man2html2.tcl -- This file defines procedures that are used during the 
	second pass of the man page to html process. It sources the temporary 
	files saved during the first pass and generates the html man pages.


TO DO
-----

Clean up and add comments to source files.

Clean up the footer mess.


CREDITS
-------

Raymond Johnson at Sun provided an example tcl script that converted man 
pages to Windows help file format.  man2tcl.tcl is based on a C program 
written at Sun.

Having Roger E. Critchlow Jr's html version of the man pages for an example 
was a big help.


Any suggestions are appreciated.

Tom L. Davis
Texas Instruments, Inc.
tom-l-davis@ti.com
