tcldoc.tcl
| Procedure Summary |
add_summary { entry target arguments source description type }Adds an entry to the global summary table. |
declaration_scan { filename }Scans a file for all instances of lines beginning with proc indicating a procedure declaration. |
deep_scan { filename }Take a single source Tcl file and scan it intensively, generating its HTML version. |
filecomp { a b }Compares the last part of a filename |
flatten_args { x }Given an arbitrary length list (such as the one supplying arguments to a procedure declaration) remove excess spaces between arguments. |
get_param { param_list param_num param_name }Retrives a parameter from the options list. |
glob_all { dir exts }Glob recursively across a directory and its subdirectory for all files matching a list of extensions. |
initialize_tables { }Initialize all of the various cross-reference tables used by TclDoc. |
lookup_procrecord { procname basename }Given a procedure name, look up within the procedure table for its declaration. |
path_lookup { orig_file }Given a filename returns the location of where its TclDoc'ed files are located. |
prepare_destination { }Creates the destination directory as necessary. |
print_status { args }If running in verbose mode print to standard output its arguments. |
print_tcldoc_help { chan }Print TclDoc's usage to a |
sanitize { s }Given some text, replaces potentially dangerous characters with their HTML character code. |
scan_recursively { dest buffer basename annotname }Given a buffer of Tcl code recursively examine each command within. |
tcldoc_args { argv }Parse the command line and set global |
tcldoc_error { message {returnvalue -1} }Called to abort TclDoc upon all other errors. |
tcldoc_file_error { message }Called to abort whenever TclDoc discovers a problem with a particular input file. |
tcldoc_file_warning { message }Called whenever TclDoc found a problem with a file, particularly something that it could not parse. |
tcldoc_main { }Actually run TclDoc across requested files and directories. |
write_and_update { dest output }Writes to channel $dest the contents of $output. |
write_export_file { } |
write_footer { dest }Output a common header for HTML-ized Tcl files. |
write_header { dest basename title }Outputs a common header for HTML-ized Tcl |
write_index_annotations { }Write two indices of all declared procedures and source files. |
write_index_bycall { mainindex }Write the index of procedure calls. |
write_index_byfile { mainindex }Write the index of filenames. |
write_index_byproc { mainindex }Write the index of procedures. |
write_index_footer { dest }Outputs a common footer for the various generated index |
write_index_header { dest page_title index_line {page_header {}} }Outputs a common header for the various generated index |
write_index_master { }Writes the overall |
| Procedure Detail |
proc add_summary { entry target arguments source description type }
entry - brief entry name
target - for file entries the HTML version of the file; for
procedures the file containing its declaration
arguments - for procedures a list or arguments to it; ignored
for files
source - source Tcl file for the entry
description - a one line summary describing the entry
type - type of entry; currently just file and
proc are understood.
proc declaration_scan { filename }
proc indicating a procedure declaration. Add
discovered declarations to the procedure table along with its line
number in the file.filename - file to scan for procedure declarations
proc deep_scan { filename }
filename - file to scan
proc filecomp { a b }
$a occurs lexically
before, with, or after $b.a - first file to compare
b - second file to compare
proc flatten_args { x }
x - list to flatten
proc get_param { param_list param_num param_name }
getopt function; otherwise increment
param_num by one.param_list - list of parameters from the command line
param_num - index into param_list to retrieve
param_name - name of the parameter, used when reporting an error
$param_num'th element into $param_list
proc glob_all { dir exts }
dir - root directory to scan
exts - list of extension (e.g., *.tcl) to search
proc initialize_tables { }
proc lookup_procrecord { procname basename }
procname - procedure name to look up
basename - preferred file to use
proc path_lookup { orig_file }
$::dest_dir, especially if the file is being imported
from elsewhere by way of --import.orig_file - filename to find
proc prepare_destination { }
--overview specified) and doc files
(--doc-files) as necessary.proc print_status { args }
args - any valid string suitable to be passed to puts
proc print_tcldoc_help { chan }
chan - I/O channel to print usage documentation
proc sanitize { s }
s - string to sanitize
$s
proc scan_recursively { dest buffer basename annotname }
if statement) recursively examine each
subpart. In this way discover comment blocks, procedure
declarations, and procedure calls.
There are limits to this scanner because it only does static
analysis. Mainly, things that make Tcl such a dynamic language
(such as eval and subst commands) may
potentially confuse this scanner.
buffer - buffer of Tcl code to examine
basename - source file from which this Tcl code originated
dest - I/O channel to write HTML-ized version of the buffer
proc tcldoc_args { argv }
argv - list of options from the command line
proc tcldoc_error { message {returnvalue -1} }
message - message to display
returnvalue - exit code
proc tcldoc_file_error { message }
message - message to display
proc tcldoc_file_warning { message }
message - message to display
proc tcldoc_main { }
proc write_and_update { dest output }
$dest the contents of
$output. Updates the global ::line_number
to keep track of how many lines have been written; hopefully this
number is the same as the lines read from the source file.dest - channel to write $output
output - data to write
proc write_export_file { }
proc write_footer { dest }
dest - I/O channel to write HTML footer
proc write_header { dest basename title }
dest - I/O channel to write HTML header
basename - Tcl source filename, sans any directory paths
title - HTML title to use for generated file
proc write_index_annotations { }
proc write_index_bycall { mainindex }
mainindex - I/O channel of index_main.html
proc write_index_byfile { mainindex }
mainindex - I/O channel of index_main.html
proc write_index_byproc { mainindex }
mainindex - I/O channel of index_main.html
proc write_index_footer { dest }
dest - I/O channel to write HTML footer
proc write_index_header { dest page_title index_line {page_header {}} }
dest - I/O channel to write HTML footer
page_title - HTML title to use for generated file
index_line - HTML source to print for the Index by: line
page_header - an optional title to put at the top of the page
proc write_index_master { }
--overview) then have
the index load the overview; otherwise just load index_main.html.